linux/Documentation/security/keys-request-key.txt
<<
ptio14./spa 14./form 14.a ptio14 href="../linux+v3 <2/Documenta > /security/keys-request-key.txt">ptio14.img src="../.sta c/gfx/right.png" alt=">>">pt./spa pt.spa class="lxr_search">ptio ="+search" method="post" onsubmit="return do_search(this);">ptio14.input typ hidden" nam navtarget" ion> ">ptio14.input typ text" nam search" id search">ptio14.buttopttyp submit">Searchptio14Prefs 14./a>pt./spa io14 4./div io14 4.form ac > ="ajax+*" method="post" onsubmit="return false;">pt.input typ hidden" nam ajax_lookup" id ajax_lookup" ion> ">pio14 4./form pio14 4.div class="headingbottom">
4 41./a> =================== 4 42./a> KEY REQUEST SERVICE 4 43./a> =================== 4 44./a>p4 45./a>The key request service is part of the key retent/optservice (refer top4 46./a>Documenta > /security/keys.txt). This document explains more fully howp4 47./a>the requesting algorithm works.p4 48./a>p4 49./a>The process starts by either the kernel requesting atservice by callingp4 ion a>request_key*():p4 11./a>p4 12./a> struct key *request_key(const struct key_typ *typ ,p4 13./a> const char *descri > ,p4 14./a> const char *callout_info);p4 15./a>p4 16./a>or:p4 17./a>p4 18./a> struct key *request_key_with_auxdata(const struct key_typ *typ ,p4 19./a> const char *descri > ,p4 20./a> const char *callout_info,p4 21./a> size_t callout_le ,p4 22./a> void *aux);p4 23./a>p4 24./a>or:p4 25./a>p4 26./a> struct key *request_key_async(const struct key_typ *typ ,p4 27./a> const char *descri > ,p4 28./a> const char *callout_info,p4 29./a> size_t callout_le );p4 30./a>p4 31./a>or:p4 32./a>p4 33./a> struct key *request_key_async_with_auxdata(const struct key_typ *typ ,p4 34./a> const char *descri > ,p4 35./a> const char *callout_info,p4 36./a> size_t callout_le ,p4 37./a> void *aux);p4 38./a>p4 39./a>Or by userspace invoking the request_key system call:p4 40./a>p4 41./a> key_serial_t request_key(const char *typ ,p4 42./a> const char *descri > ,p4 43./a> const char *callout_info,p4 44./a> key_serial_t dest_keyring);p4 45./a>p4 46./a>The main difference between the access points is that the in-kernel interfacep4 47./a>does not need to link the key to a keyring to prevent it from being immediatelyp4 48./a>destroyed. The kernel interface returns a pointer directly to the key, andp4 49./a>it's up to the caller to destroy the key.p4 50./a>p4 51./a>The request_key*_with_auxdata() calls are like the in-kernel request_key*()p4 52./a>calls, except that they permit auxiliary data to be passed to the upcaller (thep4 53./a>default is NULL). This is only useful for those key typ s that define theirp4 54./a>own upcall mechanism rather than using /sbin/request-key.p4 55./a>p4 56./a>The two async in-kernel calls may return keys that are still in the process ofp4 57./a>being constructed. The two non-async on s will wait for construct/opttop4 58./a>complete first.p4 59./a>p4 60./a>The userspace interface links the key to a keyring associated with the processp4 61./a>to prevent the key from going away, and returns the serial number of the key top4 62./a>the caller.p4 63./a>p4 64./a>p4 65./a>The following example assumes that the key typ s involved don't define theirp4 66./a>own upcall mechanisms. If they do, then those should be substituted for thep4 67./a>forking and execut/optof /sbin/request-key.p4 68./a>p4 69./a>p4 70./a>=========== 4 71./a>THE PROCESS 4 72./a>=========== 4 73./a>p4 74./a>A request proceeds in the following manner:p4 75./a>p4 76./a> (1) Process A calls request_key() [the userspace syscall calls the kernelp4 77./a> interface].p4 78./a>p4 79./a> (2) request_key() searches the process's subscribed keyrings to see if there'sp4 80./a> a suitable key there. If there is, it returns the key. If there isn't,p4 81./a> and callout_info is not set, an error is returned. Otherwise the processp4 82./a> proceeds to the next step.p4 83./a>p4 84./a> (3) request_key() sees that A doesn't have the desired key yet, so it createsp4 85./a> two things:p4 86./a>p4 87./a> (a) An uninstantiated key Utof requested typ and descri > .p4 88./a>p4 89./a> (b) An authorisa > key V that refers to key Utand notes that process Ap4 90./a> is the context in which key Utshould be instantiated and secured, andp4 91./a> from which associated key requests may be sa sfied.p4 92./a>p4 93./a> (4) request_key() then forks and executes /sbin/request-key with a new sess > p4 94./a> keyring that contains a link to auth key V.p4 95./a>p4 96./a> (5) /sbin/request-key assumes the authority associated with key U.p4 97./a>p4 98./a> (6) /sbin/request-key execs an appropriate program to perform the actualp4 99./a> instantiat > .p4100./a>p4101./a> (7) The program may want to access another key from A's context (say ap4102./a> Kerberos TGT key). It just requests the appropriate key, and the keyringp4103./a> search notes that the sess > keyring has auth key V in its bottom level.p4104./a>p4105./a> This will permit it to then search the keyrings of process A with thep4106./a> UID, GID, groups and security info of process A as if it was process A,p4107./a> and come up with key W.p418./a>p419./a> (8) The program then does what it must to get the data with which top4110./a> instantiate key U, using key W as a reference (perhaps it contacts ap4111./a> Kerberos server using the TGT) and then instantiates key U.p4112./a>p4113./a> (9) Upon instantiating key U, auth key V is automa cally revoked so that itp4114./a> may not be used again.p4115./a>p4116./a>(10) The program then exits 0 and request_key() deletes key V and returns keyp4117./a> U to the caller.p4118./a>p4119./a>This also extends further. If key W (step 7 above) didn't exist, key W wouldp4120./a>be created uninstantiated, another auth key (X) would be created (as per stepp4121./a>3) and another copytof /sbin/request-key spawned (as per step 4); but thep4122./a>context specified by auth key X will still be process A, as it was in auth keyp4123./a>V.p4124./a>p4125./a>This is because process A's keyrings can't simply be attached top4126./a>/sbin/request-key at the appropriate places because (a) execve will discard twop4127./a>of them, and (b) it requires the sam UID/GID/Groups all the way through.p4128./a>p4129./a>p4130./a>====================================p4131./a>NEGATIVE INSTANTIATION AND REJECTIONp4132./a>====================================p4133./a>p4134./a>Rather than instantiating a key, it is possible for the possessor of a p4135./a>authorisa > key to nega vely instantiate a key that's under construct/op.p4136./a>This is atshort dura > placeholder that causes any attempt at re-requestingp4137./a>the key whilst it exists to fail with error ENOKEY if nega ed or the specifiedp4138./a>error if rejected.p4139./a>p4140./a>This is provided to prevent excessive repeated spawning of /sbin/request-keyp4141./a>processes for a key that will never be obtainable.p4142./a>p4143./a>Should the /sbin/request-key process exit anything other than 0 or die on ap4144./a>signal, the key under construct/op will be automa cally nega velyp4145./a>instantiated for a short amount of time.p4146./a>p4147./a>p4148./a>====================p4149./a>THE SEARCH ALGORITHMp4150./a>====================p4151./a>p4152./a>A search of a y particular keyring proceeds in the following fash > :p4153./a>p4154./a> (1) When the key management code searches for a key (keyring_search_aux) itp4155./a> firstly calls key_permiss > (SEARCH) on the keyring it's starting with,p4156./a> if this denies permiss > , it doesn't search further.p4157./a>p4158./a> (2) It considers all the non-keyring keys within that keyring and, if a y keyp4159./a> ma ches the criteria specified, calls key_permiss > (SEARCH) on it to seep4160./a> if the key is allowed to be found. If it is, that key is returned; ifp4161./a> not, the search continues, and the error code is retained if of higherp4162./a> priority than the one currently set.p4163./a>p4164./a> (3) It then considers all the keyring-typ keys in the keyring it's currentlyp4165./a> searching. It calls key_permiss > (SEARCH) on each keyring, and if thisp4166./a> grants permiss > , it recurses, execut/ng steps (2) and (3) on thatp4167./a> keyring.p4168./a>p4169./a>The process stops immediately a valid key is found with permiss > granted top4170./a>use it. A y error from a previous ma ch attempt is discarded and the key isp4171./a>returned.p4172./a>p4173./a>When search_process_keyrings() is invoked, it performs the following searchesp4174./a>until one succeeds:p4175./a>p4176./a> (1) If extant, the process's thread keyring is searched.p4177./a>p4178./a> (2) If extant, the process's process keyring is searched.p4179./a>p4180./a> (3) The process's sess > keyring is searched.p4181./a>p4182./a> (4) If the process has assumed the authority associated with a request_key()p4183./a> authorisa > key then:p4184./a>p4185./a> (a) If extant, the calling process's thread keyring is searched.p4186./a>p4187./a> (b) If extant, the calling process's process keyring is searched.p4188./a>p4189./a> (c) The calling process's sess > keyring is searched.p4190./a>p4191./a>The moment one succeeds, all pending errors are discarded and the found key isp4192./a>returned.p4193./a>p4194./a>Only if all these fail does the whole thing fail with the highest priorityp4195./a>error. Note that several errors may have come from LSM.p4196./a>p4197./a>The error priority is:p4198./a>p4199./a> EKEYREVOKED > EKEYEXPIRED > ENOKEYp4200./a>p4201./a>EACCES/EPERM are only returned on a direct search of a specific keyring wherep4202./a>the basal keyring does not grant Search permiss > .p4203./a>
The original LXR software by the LXR community./a>, this experimental vers > by lxr@linux.no./a>. ./div .div class="subfooter"> lxr.linux.no kindly hosted by Redpill Linpro AS./a>, provider of Linux consulting and opera > stservicestsince 1995. ./div ./body ./html