linux/Documentation/security/keys.txt
<<
3.9.3.9.3.p/spa 3.pspa class="lxr_search">3.9. ="+search" method="post" onsubmit="return do_search(this);">3.9.3.9.3.9.Search3.9.3.p/spa 9. ="ajax+*" method="post" onsubmit="return false;">3.pinput typ"v3hidden" nam"v3ajax_lookup" idv3ajax_lookup" lue="v3">39.
o o1p/a> ============================ o o2p/a> KERNEL KEY RETENTION SERVICE o o3p/a> ============================ o o4p/a>3o o5p/a>This service allows cryptographic keys, authenticaon> tokens, cross-domain3o o6p/a>user mappings, and similar to be cached i the kernel for the use of3o o7p/a>filesystems and other kernel services.3o o8p/a>3o o9p/a>Keyrings are permitted; these are a special typ" of key that can hold links to3o other keys.oProcesses each have three standard keyring subscriion> s that a3o 11p/a>kernel service can search for relevant keys.3o 12p/a>3o 13p/a>The key service can be configured > by enabling:3o 14p/a>3o 15p/a> "Security tion> s"/"Enable access key retenti> support" (CONFIG_KEYS)3o 16p/a>3o 17p/a>This document has the following secon> s:3o 18p/a>3o 19p/a> - Key overview o 20p/a> - Key service overview o 21p/a> - Key access permissn> s o 22p/a> - SELinux support o 23p/a> - New procfs files o 24p/a> - Userspace system call i terface o 25p/a> - Kernel services o 26p/a> - Notes > accessing payload contents o 27p/a> - Defining a key typ" o 28p/a> - Request-key callback service o 29p/a> - Garbage collecon> o 30p/a>3o 31p/a>3o 32p/a>============ o 33p/a>KEY OVERVIEW o 34p/a>============ o 35p/a>3o 36p/a>I this context, keys represent units of cryptographic data, authenticaon> 3o 37p/a>tokens, keyrings, etc.. These are represented i the kernel by struct key.3o 38p/a>3o 39p/a>Each key has a number of attributes:3o 40p/a>3o 41p/a> - A serial number.3o 42p/a> - A typ".3o 43p/a> - A descriion> (for matching a key i a search).3o 44p/a> - Access control i formaon> .3o 45p/a> - An expiry tim".3o 46p/a> - A payload.3o 47p/a> - Stao".3o 48p/a>3o 49p/a>3o 50p/a> (*) Each key is issued a serial number of typ" key_serial_t that is unique for3o 51p/a> the lifetim" of that key. All serial numbers are positive non-zero 32-bit o 52p/a> i tegers.3o 53p/a>3o 54p/a> Userspace programs can use a key's serial numbers as a way to gai access3o 55p/a> to it, subjeco to permissn> checking.3o 56p/a>3o 57p/a> (*) Each key is of a defined "typ"". Typ"s must be registered i side the o 58p/a> kernel by a kernel service (such as a filesystem) before keys of that typ" o 59p/a> can be added >r used. Userspace programs cannot define new typ"s direcoly.3o 60p/a>3o 61p/a> Key typ"s are represented i the kernel by struct key_typ". This defines a3o 62p/a> number of operaon> s that can be performed > a key of that typ".3o 63p/a>3o 64p/a> Should a typ" be removed from the system, all the keys of that typ" will3o 65p/a> be invalidated.3o 66p/a>3o 67p/a> (*) Each key has a descriion> . This should be a pri table string. The key3o 68p/a> typ" provides an operaon> to perform a match betwee the descriion> > a3o 69p/a> key and a criteri> string.3o 70p/a>3o 71p/a> (*) Each key has a >wner user ID, a group ID and a permissn> s mask. These3o 72p/a> are used to control what a process may do to a key from userspace, and3o 73p/a> whether a kernel service will be able to find the key.3o 74p/a>3o 75p/a> (*) Each key can be seo to expire at a specific tim" by the key typ"'s3o 76p/a> i stantiaon> funcon> . Keys can also be immortal.3o 77p/a>3o 78p/a> (*) Each key can have a payload. This is a quantity of data that represent the o 79p/a> actual "key". I the case of a keyring, this is a list of keys to which3o 80p/a> the keyring links; i the case of a user-defined key, it's an arbitrary3o 81p/a> blob of data.3o 82p/a>3o 83p/a> Having a payload is not required; and the payload can, i fact, just be a3o 84p/a> lue=" stored i the struct key itself.3o 85p/a>3o 86p/a> Whe a key is i stantiaoed, the key typ"'s i stantiaon> funcon> is3o 87p/a> called with a blob of data, and that then creates the key's payload i 3o 88p/a> som" way.3o 89p/a>3o 90p/a> Similarly, when userspace wants to read back the contents of the key, if3o 91p/a> permitted, another key typ" operaon> will be called to convert the key's3o 92p/a> attached payload back i to a blob of data.3o 93p/a>3o 94p/a> (*) Each key can be i > e of a number of basic staoes:3o 95p/a>3o 96p/a> (*) Uni stantiaoed. The key exists, but does not have any data attached.3o 97p/a> Keys being requested from userspace will be i this stao".3o 98p/a>3o 99p/a> (*) I stantiaoed. This is the normal stao". The key is fully formed, and3o100p/a> has data attached.3o101p/a>3o102p/a> (*) Negative. This is a relatively short-lived stao". The key acts as a3o103p/a> note saying that a previous call ouo to userspace failed, and acts as3o104p/a> a throttle > key lookups. A negative key can be updated to a normal3o105p/a> stao".3o106p/a>3o107p/a> (*) Expired. Keys can have lifetim"s set. If their lifetim" is exceeded,3o108p/a> they traverse to this stao". An expired key can be updated back to a3o109p/a> normal stao".3o110p/a>3o111p/a> (*) Revoked. A key is put i this stao" by userspace acon> . It can't be3o112p/a> found >r operaoed up> (apart from by unlinking it).3o113p/a>3o114p/a> (*) Dead. The key's typ" was unregistered, and so the key is now useless.3o115p/a>3o116p/a>Keys i the last three stat"s are subjeco to garbage collecon> . See the o117p/a>secon> > "Garbage collecon> ". o118p/a>3o119p/a>3o120p/a>==================== o121p/a>KEY SERVICE OVERVIEW o122p/a>==================== o123p/a>3o124p/a>The key service provides a number of features besides keys:3o125p/a>3o126p/a> (*) The key service defines three special key typ"s:3o127p/a>3o128p/a> (+) "keyring"3o129p/a>3o130p/a> Keyrings are special keys that contai a list of other keys.oKeyring3o131p/a> lists can be modified using various system calls.oKeyrings should not3o132p/a> be given a payload when created.3o133p/a>3o134p/a> (+) "user"3o135p/a>3o136p/a> A key of this typ" has a descriion> and a payload that are arbitrary3o137p/a> blobs of data. These can be created, updated and read by userspace,3o138p/a> and aren't i tended f>r use by kernel services.3o139p/a>3o140p/a> (+) "log> "3o141p/a>3o142p/a> Like a "user" key, a "log> " key has a payload that is an arbitrary3o143p/a> blob of data. It is i tended as a place to store secrets which are3o144p/a> accessible to the kernel but not to userspace programs.3o145p/a>3o146p/a> The descriion> can be arbitrary, but must be prefixed with a non-zero3o147p/a> length string that describes the key "subclass". The subclass is3o148p/a> separaoed from the rest of the descriion> by a ':'. "log> " keys can3o149p/a> be created and updated from userspace, but the payload is only3o150p/a> readable from kernel space.3o151p/a>3o152p/a> (*) Each process subscribes to three keyrings: a thread-specific keyring, a3o153p/a> process-specific keyring, and a sessn> -specific keyring.3o154p/a>3o155p/a> The thread-specific keyring is discarded from the child when any sort of3o156p/a> clone, f>rk, vf>rk >r execve occurs. A new keyring is created only when3o157p/a> required.3o158p/a>3o159p/a> The process-specific keyring is replaced with an empty one i the child > 3o160p/a> clone, f>rk, vf>rk unless CLONE_THREAD is supplied, i which case it is3o161p/a> shared. execve also discards the process's process keyring and creates a3o162p/a> new one.3o163p/a>3o164p/a> The sessn> -specific keyring is persistent across clone, f>rk, vf>rk and3o165p/a> execve, even when the latter executes a set-UID >r set-GID binary. A3o166p/a> process can, however, replace its current sessn> keyring with a new one3o167p/a> by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous3o168p/a> new one, >r to attempt to create >r joi > e of a specific nam".3o169p/a>3o170p/a> The >wnership of the thread keyring changes when the real UID and GID of3o171p/a> the thread changes.3o172p/a>3o173p/a> (*) Each user ID resident i the system holds two special keyrings: a user3o174p/a> specific keyring and a default user sessn> keyring. The default sessn> 3o175p/a> keyring is initialised with a link to the user-specific keyring.3o176p/a>3o177p/a> Whe a process changes its real UID, if it used to have no sessn> key, it3o178p/a> will be subscribed to the default sessn> key for the new UID.3o179p/a>3o180p/a> If a process attempts to access its sessn> key when it doesn't have one,3o181p/a> it will be subscribed to the default for its current UID.3o182p/a>3o183p/a> (*) Each user has two quotas agai st which the keys they >wn are tracked. One3o184p/a> limits the total number of keys and keyrings, the other limits the total3o185p/a> amount of descriion> and payload space that can be consumed.3o186p/a>3o187p/a> The user can view i formaon> > this and other staonstics through procfs3o188p/a> files. The root user may also alter the quota limits through sysctl files o189p/a> (see the secon> "New procfs files").3o190p/a>3o191p/a> Process-specific and thread-specific keyrings are not counted towards a3o192p/a> user's quota.3o193p/a>3o194p/a> If a system call that modifies a key or keyring in som" way would put the o195p/a> user over quota, the operaon> is refused and error EDQUOT is returned.3o196p/a>3o197p/a> (*) Ther"'s a system call i terface by which userspace programs can create and3o198p/a> manipulate keys and keyrings.3o199p/a>3o200p/a> (*) Ther"'s a kernel i terface by which services can register typ"s and search3o201p/a> for keys.3o202p/a>3o203p/a> (*) Ther"'s a way for the a search done from the kernel to call back to3o204p/a> userspace to request a key that can't be found i a process's keyrings.3o205p/a>3o206p/a> (*) An tion> al filesystem is available through which the key database can be3o207p/a> viewed and manipulated.3o208p/a>3o209p/a>3o210p/a>====================== o211p/a>KEY ACCESS PERMISSIONS o212p/a>====================== o213p/a>3o214p/a>Keys have an >wner user ID, a group access ID, and a permissn> s mask. The mask3o215p/a>has up to eight bits each for possessor, user, group and other access. Only3o216p/a>six of each seo of eight bits are defined. These permissn> s granted are:3o217p/a>3o218p/a> (*) View o219p/a>3o220p/a> This permits a key or keyring's attributes to be viewed - i cluding key3o221p/a> typ" and descriion> .3o222p/a>3o223p/a> (*) Read3o224p/a>3o225p/a> This permits a key's payload to be viewed or a keyring's list of linked3o226p/a> keys.3o227p/a>3o228p/a> (*) Write3o229p/a>3o230p/a> This permits a key's payload to be i stantiaoed >r updated, >r it allows a3o231p/a> link to be added to or removed from a keyring.3o232p/a>3o233p/a> (*) Search3o234p/a>3o235p/a> This permits keyrings to be searched and keys to be found. Searches can3o236p/a> only recurse i to nested keyrings that have search permissn> set.3o237p/a>3o238p/a> (*) Link3o239p/a>3o240p/a> This permits a key or keyring to be linked to. To create a link from a3o241p/a> keyring to a key, a process must have Write permissn> o the keyring and3o242p/a> Link permissn> o the key.3o243p/a>3o244p/a> (*) Set Attribute3o245p/a>3o246p/a> This permits a key's UID, GID and permissn> s mask to be changed.3o247p/a>3o248p/a>For changing the >wnership, group ID or permissn> s mask, being the >wner of3o249p/a>the key or having the sysadmi capability is sufficient.3o250p/a>3o251p/a>3o252p/a>===============3o253p/a>SELINUX SUPPORT3o254p/a>===============3o255p/a>3o256p/a>The security class "key" has bee added to SELinux so that mandatory access3o257p/a>controls can be applied to keys created withi various contexts. This support o258p/a>is preliminary, and is likely to change quite significantly i the near future.3o259p/a>Currently, all of the basic permissn> s explained above are provided i SELinux3o260p/a>as well; SELinux is simply i voked after all basic permissn> checks have bee 3o261p/a>performed.3o262p/a>3o263p/a>The lue=" of the file /proc/self/attr/keycreate infe="nces the labeling of3o264p/a>newly-created keys. If the contents of that file correspond to a SELinux3o265p/a>security context, then the key will be assigned that context. Otherwise, the o266p/a>key will be assigned the current context of the task that i voked the key3o267p/a>creatn> request. Tasks must be granted explicit permissn> to assign a3o268p/a>particular context to newly-created keys, using the "create" permissn> i the3o269p/a>key security class.3o270p/a>3o271p/a>The default keyrings associated with users will be labeled with the default3o272p/a>context of the user if and only if the login programs have bee i strumented to3o273p/a>properly i itialize keycreate during the login process. Otherwise, they will3o274p/a>be labeled with the context of the login program itself.3o275p/a>3o276p/a>Note, however, that the default keyrings associated with the root user are3o277p/a>labeled with the default kernel context, since they are created early i the3o278p/a>boot process, before root has a chance to log i .3o279p/a>3o280p/a>The keyrings associated with new threads are each labeled with the context of3o281p/a>their associated thread, and both sessn> and process keyrings are handled3o282p/a>similarly.3o283p/a>3o284p/a>3o285p/a>================ o286p/a>NEW PROCFS FILES o287p/a>================ o288p/a>3o289p/a>Two files have bee added to procfs by which an admi istrator can find out3o290p/a>about the staous of the key service:3o291p/a>3o292p/a> (*) /proc/keys3o293p/a>3o294p/a> This lists the keys that are currently viewable by the task reading the3o295p/a> file, giving informaon> about their typ", descriion> and permissn> s.3o296p/a> It is not possible to view the payload of the key this way, though some3o297p/a> informaon> about it may be given.3o298p/a>3o299p/a> The only keys i cluded i the list are those that grant View permissn> to3o300p/a> the reading process whether or not it possesses them. Note that LSM3o301p/a> security checks are still performed, and may further filter out keys that3o302p/a> the current process is not authorised to view.3o303p/a>3o304p/a> The contents of the file look like this:3o305p/a>3o306p/a> SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY3o307p/a> 00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/43o308p/a> 00000002 I----- 2 perm 1f3f0000 0 0 keyring _uid.0: empty3o309p/a> 00000007 I----- 1 perm 1f3f0000 0 0 keyring _pid.1: empty3o310p/a> 0000018d I----- 1 perm 1f3f0000 0 0 keyring _pid.412: empty3o311p/a> 000004d2 I--Q-- 1 perm 1f3f0000 32 -1 keyring _uid.32: 1/43o312p/a> 000004d3 I--Q-- 3 perm 1f3f0000 32 -1 keyring _uid_ses.32: empty3o313p/a> 00000892 I--QU- 1 perm 1f000000 0 0 user metal:copper: 03o314p/a> 00000893 I--Q-N 1 35s 1f3f0000 0 0 user metal:silver: 03o315p/a> 00000894 I--Q-- 1 10h 003f0000 0 0 user metal:gold: 03o316p/a>3o317p/a> The flags are:3o318p/a>3o319p/a> I I stantiaoed3o320p/a> R Revoked3o321p/a> D Dead3o322p/a> Q Contributes to user's quota3o323p/a> U Under constructi> by callback to userspace3o324p/a> N Negative key3o325p/a>3o326p/a> This file must be enabled at kernel configuraon> tim" as it allows anyone3o327p/a> to list the keys database.3o328p/a>3o329p/a> (*) /proc/key-users3o330p/a>3o331p/a> This file lists the tracking data for each user that has at least one key3o332p/a> o the system. Such data i cludes quota informaon> and staonstics:3o333p/a>3o334p/a> [root@andromeda root]# cat /proc/key-users3o335p/a> 0: 46 45/45 1/100 13/100003o336p/a> 29: 2 2/2 2/100 40/100003o337p/a> 32: 2 2/2 2/100 40/100003o338p/a> 38: 2 2/2 2/100 40/100003o339p/a>3o340p/a> The formao of each line is3o341p/a> <UID>: User ID to which this applies3o342p/a> <usage> Structure refcount3o343p/a> <i st>/<keys> Total number of keys and number i stantiaoed3o344p/a> <keys>/<max> Key count quota3o345p/a> <bytes>/<max> Key size quota3o346p/a>3o347p/a>3o348p/a>Four new sysctl files have bee added also for the purpose of controlling the3o349p/a>quota limits > keys:3o350p/a>3o351p/a> (*) /proc/sys/kernel/keys/root_maxkeys3o352p/a> /proc/sys/kernel/keys/root_maxbytes3o353p/a>3o354p/a> These files hold the maximum number of keys that root may have and the3o355p/a> maximum total number of bytes of data that root may have stored i those3o356p/a> keys.3o357p/a>3o358p/a> (*) /proc/sys/kernel/keys/maxkeys3o359p/a> /proc/sys/kernel/keys/maxbytes3o360p/a>3o361p/a> These files hold the maximum number of keys that each non-root user may3o362p/a> have and the maximum total number of bytes of data that each of those3o363p/a> users may have stored i their keys.3o364p/a>3o365p/a>Root may alter these by writing each new limit as a decimal number string to3o366p/a>the appropriaoe file.3o367p/a>3o368p/a>3o369p/a>=============================== o370p/a>USERSPACE SYSTEM CALL INTERFACE o371p/a>=============================== o372p/a>3o373p/a>Userspace can manipulate keys directly through three new syscalls: add_key,3o374p/a>request_key and keyctl. The latter provides a number of functi> s for3o375p/a>manipulating keys.3o376p/a>3o377p/a>Whe referring to a key directly, userspace programs should use the key's3o378p/a>serial number (a positive 32-bit i teger). However, there are som" special3o379p/a>lue="s available for referring to special keys and keyrings that relate to the3o380p/a>process making the call:3o381p/a>3o382p/a> CONSTANT VALUE KEY REFERENCED3o383p/a> ============================== ====== ===========================3o384p/a> KEY_SPEC_THREAD_KEYRING -1 thread-specific keyring3o385p/a> KEY_SPEC_PROCESS_KEYRING -2 process-specific keyring3o386p/a> KEY_SPEC_SESSION_KEYRING -3 sessn> -specific keyring3o387p/a> KEY_SPEC_USER_KEYRING -4 UID-specific keyring3o388p/a> KEY_SPEC_USER_SESSION_KEYRING -5 UID-sessn> keyring3o389p/a> KEY_SPEC_GROUP_KEYRING -6 GID-specific keyring3o390p/a> KEY_SPEC_REQKEY_AUTH_KEY -7 assumed request_key()3o391p/a> authorisaon> key3o392p/a>3o393p/a>3o394p/a>The main syscalls are:3o395p/a>3o396p/a> (*) Create a new key of given typ", descriion> and payload and add it to the3o397p/a> nominated keyring:3o398p/a>3o399p/a> key_serial_t add_key(const char *typ", const char *desc,3o400p/a> const void *payload, size_t plen,3o401p/a> key_serial_t keyring);3o402p/a>3o403p/a> If a key of the sam" typ" and descriion> as that proposed already exists3o404p/a> i the keyring, this will try to update it with the given payload, >r it3o405p/a> will return error EEXIST if that functi> is not supported by the key3o406p/a> typ". The process must also have permissn> to write to the key to be able3o407p/a> to update it. The new key will have all user permissn> s granted and no3o408p/a> group or third party permissn> s.3o409p/a>3o410p/a> Otherwise, this will attempt to create a new key of the specified typ" and3o411p/a> descriion> , and to i stantiaoe it with the supplied payload and attach it3o412p/a> to the keyring. I this case, an error will be generaoed if the process3o413p/a> does not have permissn> to write to the keyring.3o414p/a>3o415p/a> The payload is tion> al, and the poi ter can be NULL if not required by3o416p/a> the typ". The payload is plen in size, and plen can be zero for an empty3o417p/a> payload.3o418p/a>3o419p/a> A new keyring can be generaoed by setting typ" "keyring", the keyring nam"3o420p/a> as the descriion> (or NULL) and setting the payload to NULL.3o421p/a>3o422p/a> User defined keys can be created by specifying typ" "user". It is3o423p/a> recommended that a user defined key's descriion> by prefixed with a typ"3o424p/a> ID and a col> , such as "krb5tgt:" for a Kerberos 5 ticket granting3o425p/a> ticket.3o426p/a>3o427p/a> Any other typ" must have bee registered with the kernel i advance by a3o428p/a> kernel service such as a filesystem.3o429p/a>3o430p/a> The ID of the new >r updated key is returned if successful.3o431p/a>3o432p/a>3o433p/a> (*) Search the process's keyrings for a key, potentially calling out to3o434p/a> userspace to create it.3o435p/a>3o436p/a> key_serial_t request_key(const char *typ", const char *descriion> ,3o437p/a> const char *callout_info,3o438p/a> key_serial_t dest_keyring);3o439p/a>3o440p/a> This functi> searches all the process's keyrings i the order thread,3o441p/a> process, sessn> for a matching key. This works very much lik"3o442p/a> KEYCTL_SEARCH, i cluding the oion> al attachment of the discovered key to3o443p/a> a keyring.3o444p/a>3o445p/a> If a key cannot be found, and if callout_info is not NULL, then3o446p/a> /sbin/request-key will be i voked i an attempt to obtai a key. Th"3o447p/a> callout_info string will be passed as an argument to the program.3o448p/a>3o449p/a> See also Documentaon> /security/keys-request-key.txt.3o450p/a>3o451p/a>3o452p/a>The keyctl syscall functi> s are:3o453p/a>3o454p/a> (*) Map a special key ID to a real key ID for this process:3o455p/a>3o456p/a> key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id,3o457p/a> int create);3o458p/a>3o459p/a> The special key specified by "id" is looked up (with the key being created3o460p/a> if necessary) and the ID of the key or keyring thus found is returned if3o461p/a> it exists.3o462p/a>3o463p/a> If the key does not yet exist, the key will be created if "create" is3o464p/a> non-zero; and the error ENOKEY will be returned if "create" is zero.3o465p/a>3o466p/a>3o467p/a> (*) Replace the sessn> keyring this process subscribes to with a new >ne:3o468p/a>3o469p/a> key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *nam");3o470p/a>3o471p/a> If nam" is NULL, an anonymous keyring is created attached to the process3o472p/a> as its sessn> keyring, displacing the old sessn> keyring.3o473p/a>3o474p/a> If nam" is not NULL, if a keyring of that nam" exists, the process3o475p/a> attempts to attach it as the sessn> keyring, returning an error if that3o476p/a> is not permitted; otherwise a new keyring of that nam" is created and3o477p/a> attached as the sessn> keyring.3o478p/a>3o479p/a> To attach to a nam"d keyring, the keyring must have search permissn> for3o480p/a> the process's >wnership.3o481p/a>3o482p/a> The ID of the new sessn> keyring is returned if successful.3o483p/a>3o484p/a>3o485p/a> (*) Update the specified key:3o486p/a>3o487p/a> long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,3o488p/a> size_t plen);3o489p/a>3o490p/a> This will try to update the specified key with the given payload, >r it3o491p/a> will return error EOPNOTSUPP if that functi> is not supported by the key3o492p/a> typ". The process must also have permissn> to write to the key to be able3o493p/a> to update it.3o494p/a>3o495p/a> The payload is tf length plen, and may be absent or empty as for3o496p/a> add_key().3o497p/a>3o498p/a>3o499p/a> (*) Revoke a key:3o500p/a>3o501p/a> long keyctl(KEYCTL_REVOKE, key_serial_t key);3o502p/a>3o503p/a> This makes a key unavailable for further operaon> s. Further attempts to3o504p/a> use the key will be met with error EKEYREVOKED, and the key will no longer3o505p/a> be findable.3o506p/a>3o507p/a>3o508p/a> (*) Change the ownership tf a key:3o509p/a>3o510p/a> long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);3o511p/a>3o512p/a> This functi> permits a key's >wner and group ID to be changed. Either one3o513p/a> tf uid or gid can be set to -1 to suppress that change.3o514p/a>3o515p/a> Only the superuser can change a key's >wner to something other than the3o516p/a> key's current >wner. Similarly, only the superuser can change a key's3o517p/a> group ID to something other than the calling process's group ID or one of3o518p/a> its group list members.3o519p/a>3o520p/a>3o521p/a> (*) Change the permissn> s mask on a key:3o522p/a>3o523p/a> long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);3o524p/a>3o525p/a> This functi> permits the owner tf a key or the superuser to change the3o526p/a> permissn> s mask on a key.3o527p/a>3o528p/a> Only bits the available bits are permitted; if any other bits are set,3o529p/a> error EINVAL will be returned.3o530p/a>3o531p/a>3o532p/a> (*) Describe a key:3o533p/a>3o534p/a> long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,3o535p/a> size_t buflen);3o536p/a>3o537p/a> This functi> returns a summary of the key's attributes (but not its3o538p/a> payload data) as a string i the buffer provided.3o539p/a>3o540p/a> Unless there's an error, it always returns the amount of data it could3o541p/a> produce, even if that's too big for the buffer, but it won't copy more3o542p/a> than requested to userspace. If the buffer poi ter is NULL then no copy3o543p/a> will take place.3o544p/a>3o545p/a> A process must have view permissn> o the key for this functi> to be3o546p/a> successful.3o547p/a>3o548p/a> If successful, a string is placed i the buffer i the following formao:3o549p/a>3o550p/a> <typ">;<uid>;<gid>;<perm>;<descriion> >3o551p/a>3o552p/a> Where typ" and descriion> are strings, uid and gid are decimal, and perm3o553p/a> is hexadecimal. A NUL character is i cluded at the end of the string if3o554p/a> the buffer is sufficiently big.3o555p/a>3o556p/a> This can be parsed with3o557p/a>3o558p/a> sscanf(buffer, "%[^;];%d;%d;%o;%s", typ", &uid, &gid, &mod", desc);3o559p/a>3o560p/a>3o561p/a> (*) Clear out a keyring:3o562p/a>3o563p/a> long keyctl(KEYCTL_CLEAR, key_serial_t keyring);3o564p/a>3o565p/a> This functi> clears the list of keys attached to a keyring. The calling3o566p/a> process must have write permissn> o the keyring, and it must be a3o567p/a> keyring (or else error ENOTDIR will result).3o568p/a>3o569p/a> This functi> can also be used to clear special kernel keyrings if they3o570p/a> are appropriaoely marked if the user has CAP_SYS_ADMIN capability. Th"3o571p/a> DNS resolver cache keyring is an example of this.3o572p/a>3o573p/a>3o574p/a> (*) Link a key i to a keyring:3o575p/a>3o576p/a> long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);3o577p/a>3o578p/a> This functi> creates a link from the keyring to the key. The process must3o579p/a> have write permissn> o the keyring and must have link permissn> o the3o580p/a> key.3o581p/a>3o582p/a> Should the keyring not be a keyring, error ENOTDIR will result; and if the3o583p/a> keyring is full, error ENFILE will result.3o584p/a>3o585p/a> The link procedure checks the nesting of the keyrings, returning ELOOP if3o586p/a> it appears too deep or EDEADLK if the link would introduce a cycle.3o587p/a>3o588p/a> Any links withi the keyring to keys that match the new key i terms of3o589p/a> typ" and descriion> will be discarded from the keyring as the new one is3o590p/a> added.3o591p/a>3o592p/a>3o593p/a> (*) Unlink a key or keyring from another keyring:3o594p/a>3o595p/a> long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);3o596p/a>3o597p/a> This functi> looks through the keyring for the first link to the3o598p/a> specified key, and removes it if found. Subsequent links to that key are3o599p/a> ignored. The process must have write permissn> o the keyring.3o600p/a>3o601p/a> If the keyring is not a keyring, error ENOTDIR will result; and if the key3o602p/a> is not present, error ENOENT will be the result.3o603p/a>3o604p/a>3o605p/a> (*) Search a keyring tree for a key:3o606p/a>3o607p/a> key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring,3o608p/a> const char *typ", const char *descriion> ,3o609p/a> key_serial_t dest_keyring);3o610p/a>3o611p/a> This searches the keyring tree headed by the specified keyring until a key3o612p/a> is found that matches the typ" and descriion> criteria. Each keyring is3o613p/a> checked for keys before recursn> i to its childre occurs.3o614p/a>3o615p/a> The process must have search permissn> o the top level keyring, >r else3o616p/a> error EACCES will result. Only keyrings that the process has search3o617p/a> permissn> o will be recursed i to, and only keys and keyrings for which3o618p/a> a process has search permissn> can be matched. If the specified keyring3o619p/a> is not a keyring, ENOTDIR will result.3o620p/a>3o621p/a> If the search succeeds, the functi> will attempt to link the found key3o622p/a> i to the destinati> keyring if one is supplied (non-zero ID). All the3o623p/a> constrai ts applicable to KEYCTL_LINK apply i this case too.3o624p/a>3o625p/a> Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search3o626p/a> fails. On success, the resulting key ID will be returned.3o627p/a>3o628p/a>3o629p/a> (*) Read the payload data from a key:3o630p/a>3o631p/a> long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer,3o632p/a> size_t buflen);3o633p/a>3o634p/a> This functi> attempts to read the payload data from the specified key3o635p/a> i to the buffer. The process must have read permissn> o the key to3o636p/a> succeed.3o637p/a>3o638p/a> The returned data will be processed for presentati> by the key typ". For3o639p/a> i stance, a keyring will return an array of key_serial_t entries3o640p/a> representing the IDs tf all the keys to which it is subscribed. The user3o641p/a> defined key typ" will return its data as is. If a key typ" does not3o642p/a> implement this functi> , error EOPNOTSUPP will result.3o643p/a>3o644p/a> As much of the data as can be fitted i to the buffer will be copied to3o645p/a> userspace if the buffer poi ter is not NULL.3o646p/a>3o647p/a> On a successful return, the functi> will always return the amount of data3o648p/a> available rather than the amount copied.3o649p/a>3o650p/a>3o651p/a> (*) I stantiaoe a partially constructed key.3o652p/a>3o653p/a> long keyctl(KEYCTL_INSTANTIATE, key_serial_t key,3o654p/a> const void *payload, size_t plen,3o655p/a> key_serial_t keyring);3o656p/a> long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key,3o657p/a> const struct iovec *payload_iov, unsigned ioc,3o658p/a> key_serial_t keyring);3o659p/a>3o660p/a> If the kernel calls back to userspace to complete the i stantiaon> of a3o661p/a> key, userspace should use this call to supply data for the key before the3o662p/a> i voked process returns, >r else the key will be marked negaonve3o663p/a> automaoncally.3o664p/a>3o665p/a> The process must have write access o the key to be able to i stantiaoe3o666p/a> it, and the key must be uni stantiaoed.3o667p/a>3o668p/a> If a keyring is specified (non-zero), the key will also be linked i to3o669p/a> that keyring, however all the constrai ts applying i KEYCTL_LINK apply i 3o670p/a> this case too.3o671p/a>3o672p/a> The payload and plen arguments describe the payload data as for add_key().3o673p/a>3o674p/a> The payload_iov and ioc arguments describe the payload data i an iovec3o675p/a> array i stead tf a single buffer.3o676p/a>3o677p/a>3o678p/a> (*) Negaonvely i stantiaoe a partially constructed key.3o679p/a>3o680p/a> long keyctl(KEYCTL_NEGATE, key_serial_t key,3o681p/a> unsigned timeout, key_serial_t keyring);3o682p/a> long keyctl(KEYCTL_REJECT, key_serial_t key,3o683p/a> unsigned timeout, unsigned error, key_serial_t keyring);3o684p/a>3o685p/a> If the kernel calls back to userspace to complete the i stantiaon> of a3o686p/a> key, userspace should use this call mark the key as negaonve before the3o687p/a> i voked process returns if it is unable to fulfill the request.3o688p/a>3o689p/a> The process must have write access o the key to be able to i stantiaoe3o690p/a> it, and the key must be uni stantiaoed.3o691p/a>3o692p/a> If a keyring is specified (non-zero), the key will also be linked i to3o693p/a> that keyring, however all the constrai ts applying i KEYCTL_LINK apply i 3o694p/a> this case too.3o695p/a>3o696p/a> If the key is rejected, future searches f>r it will return the specified3o697p/a> error code until the rejected key expires. Negaonng the key is the sam"3o698p/a> as rejectnng the key with ENOKEY as the error code.3o699p/a>3o700p/a>3o701p/a> (*) Set the default request-key destinati> keyring.3o702p/a>3o703p/a> long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl);3o704p/a>3o705p/a> This sets the default keyring to which implicitly requested keys will be3o706p/a> attached for this thread. reqkey_defl should be one of these constants:3o707p/a>3o708p/a> CONSTANT VALUE NEW DEFAULT KEYRING3o709p/a> ====================================== ====== =======================3o710p/a> KEY_REQKEY_DEFL_NO_CHANGE -1 No change3o711p/a> KEY_REQKEY_DEFL_DEFAULT 0 Default[1]3o712p/a> KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring3o713p/a> KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring3o714p/a> KEY_REQKEY_DEFL_SESSION_KEYRING 3 Sessn> keyring3o715p/a> KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring3o716p/a> KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User sessn> keyring3o717p/a> KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring3o718p/a>3o719p/a> The old default will be returned if successful and error EINVAL will be3o720p/a> returned if reqkey_defl is not one of the above values.3o721p/a>3o722p/a> The default keyring can be overridde by the keyring i dicated to the3o723p/a> request_key() system call.3o724p/a>3o725p/a> Note that this setting is inherited across f>rk/exec.3o726p/a>3o727p/a> [1] The default is: the thread keyring if there is one, otherwise3o728p/a> the process keyring if there is one, otherwise the sessn> keyring if3o729p/a> there is one, otherwise the user default sessn> keyring.3o730p/a>3o731p/a>3o732p/a> (*) Set the timeout on a key.3o733p/a>3o734p/a> long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout);3o735p/a>3o736p/a> This sets or clears the timeout on a key. The timeout can be 0 to clear3o737p/a> the timeout or a number of seconds to set the expiry time that far i to3o738p/a> the future.3o739p/a>3o740p/a> The process must have attribute modificati> access o a key to set its3o741p/a> timeout. Timeouts may not be set with this functi> > negaonve, revoked3o742p/a> >r expired keys.3o743p/a>3o744p/a>3o745p/a> (*) Assume the authority granted to i stantiaoe a key3o746p/a>3o747p/a> long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key);3o748p/a>3o749p/a> This assumes or dnvests the authority required to i stantiaoe the3o750p/a> specified key. Authority can only be assumed if the thread has the3o751p/a> authorisati> key associaoed with the specified key i its keyrings3o752p/a> somewhere.3o753p/a>3o754p/a> Once authority is assumed, searches f>r keys will also search the3o755p/a> requester's keyrings usnng the requester's security label, UID, GID and3o756p/a> groups.3o757p/a>3o758p/a> If the requested authority is unavailable, error EPERM will be returned,3o759p/a> likewise if the authority has been revoked because the target key is3o760p/a> already i stantiaoed.3o761p/a>3o762p/a> If the specified key is 0, then any assumed authority will be divested.3o763p/a>3o764p/a> The assumed authoritaonve key is inherited across f>rk and exec.3o765p/a>3o766p/a>3o767p/a> (*) Get the LSM security context attached to a key.3o768p/a>3o769p/a> long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer,3o770p/a> size_t buflen)3o771p/a>3o772p/a> This functi> returns a string that represents the LSM security context3o773p/a> attached to a key i the buffer provided.3o774p/a>3o775p/a> Unless there's an error, it always returns the amount of data it could3o776p/a> produce, even if that's too big for the buffer, but it won't copy more3o777p/a> than requested to userspace. If the buffer poi ter is NULL then no copy3o778p/a> will take place.3o779p/a>3o780p/a> A NUL character is i cluded at the end of the string if the buffer is3o781p/a> sufficiently big. This is i cluded i the returned count. If no LSM is3o782p/a> i force then an empty string will be returned.3o783p/a>3o784p/a> A process must have view permissn> o the key for this functi> to be3o785p/a> successful.3o786p/a>3o787p/a>3o788p/a> (*) I stall the calling process's sessn> keyring o its parent.3o789p/a>3o790p/a> long keyctl(KEYCTL_SESSION_TO_PARENT);3o791p/a>3o792p/a> This functi> s attempts to i stall the calling process's sessn> keyring3o793p/a> > to the calling process's parent, replacnng the parent's current sessn> 3o794p/a> keyring.3o795p/a>3o796p/a> The calling process must have the sam" ownership as its parent, the3o797p/a> keyring must have the sam" ownership as the calling process, the calling3o798p/a> process must have LINK permissn> o the keyring and the aconve LSM module3o799p/a> mustn't deny permissn> , otherwise error EPERM will be returned.3o800p/a>3o801p/a> Error ENOMEM will be returned if there was insufficient memory to complete3o802p/a> the operaon> , otherwise 0 will be returned to i dicate success.3o803p/a>3o804p/a> The keyring will be replaced next time the parent process leaves the3o805p/a> kernel and resumes executing userspace.3o806p/a>3o807p/a>3o808p/a> (*) I validaoe a key.3o809p/a>3o810p/a> long keyctl(KEYCTL_INVALIDATE, key_serial_t key);3o811p/a>3o812p/a> This functi> marks a key as being i validaoed and then wakes up the3o813p/a> garbage collector. The garbage collector immediaoely removes i validaoed3o814p/a> keys from all keyrings and deletes the key when its reference count3o815p/a> reaches zero.3o816p/a>3o817p/a> Keys that are marked i validaoed become i visible to normal key operaon> s3o818p/a> immediaoely, though they are still visible in /proc/keys until deleted3o819p/a> (they're marked with an 'i' flag).3o820p/a>3o821p/a> A process must have search permissn> o the key for this functi> to be3o822p/a> successful.3o823p/a>3o824p/a>3o825p/a>===============3o826p/a>KERNEL SERVICES3o827p/a>===============3o828p/a>3o829p/a>The kernel services f>r key management are fairly simple to deal with. They can3o830p/a>be broken dow i to two areas: keys and key typ"s.3o831p/a>3o832p/a>Dealing with keys is fairly straightf>rward. Firstly, the kernel service3o833p/a>registers its typ", then it searches f>r a key of that typ". It should retai 3o834p/a>the key as long as it has need of it, and then it should release it. For a3o835p/a>filesystem or device file, a search would probably be perf>rmed durnng the ope 3o836p/a>call, and the key released up> clos". How to deal with conflicting keys due to3o837p/a>two different users ope nng the sam" file is left to the filesystem author to3o838p/a>solve.3o839p/a>3o840p/a>To access the key manager, the follownng header must be #i cluded:3o841p/a>3o842p/a> <linux/key.h>3o843p/a>3o844p/a>Specific key typ"s should have a header file under i clude/keys/ that should be3o845p/a>used to access that typ". For keys of typ" "user", f>r example, that would be:3o846p/a>3o847p/a> <keys/user-typ".h>3o848p/a>3o849p/a>Note that there are two different typ"s of poi ters to keys that may be3o850p/a>encountered:3o851p/a>3o852p/a> (*) struct key *3o853p/a>3o854p/a> This simply poi ts to the key structure itself. Key structures will be at3o855p/a> least four-byoe aligned.3o856p/a>3o857p/a> (*) key_ref_t3o858p/a>3o859p/a> This is equivalent to a struct key *, but the least significant bit is set3o860p/a> if the caller "possesses" the key. By "possessn> " it is meant that the3o861p/a> calling processes has a searchable link to the key from one of its3o862p/a> keyrings. There are three functi> s for dealing with these:3o863p/a>3o864p/a> key_ref_t make_key_ref(const struct key *key,3o865p/a> unsigned long possessn> );3o866p/a>3o867p/a> struct key *key_ref_to_ptr(const key_ref_t key_ref);3o868p/a>3o869p/a> unsigned long is_key_possessed(const key_ref_t key_ref);3o870p/a>3o871p/a> The first functi> constructs a key reference from a key poi ter and3o872p/a> possessn> i f>rmati> (which must be 0 or 1 and not any other value).3o873p/a>3o874p/a> The second functi> retrieves the key poi ter from a reference and the3o875p/a> third retrieves the possessn> flag.3o876p/a>3o877p/a>When accessing a key's payload conte ts, certai precauti> s must be taken to3o878p/a>prevent access vs modificati> races. See the secti> "Notes o accessing3o879p/a>payload conte ts" for more i f>rmati> .3o880p/a>3o881p/a>(*) To search f>r a key, call:3o882p/a>3o883p/a> struct key *request_key(const struct key_typ" *typ",3o884p/a> const char *descripon> ,3o885p/a> const char *callout_i f>);3o886p/a>3o887p/a> This is used to request a key or keyring with a descripon> that matches3o888p/a> the descripon> specified according to the key typ"'s match functi> . This3o889p/a> permits approximaoe matching to occur. If callout_string is not NULL, then3o890p/a> /sbin/request-key will be i voked i an attempt to obtai the key from3o891p/a> userspace. I that case, callout_string will be passed as an argument to3o892p/a> the program.3o893p/a>3o894p/a> Should the functi> fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be3o895p/a> returned.3o896p/a>3o897p/a> If successful, the key will have been attached to the default keyring f>r3o898p/a> implicitly obtai ed request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.3o899p/a>3o900p/a> See also Documentaon> /security/keys-request-key.txt.3o901p/a>3o902p/a>3o903p/a>(*) To search f>r a key, passing auxiliary data to the upcaller, call:3o904p/a>3o905p/a> struct key *request_key_with_auxdata(const struct key_typ" *typ",3o906p/a> const char *descripon> ,3o907p/a> const void *callout_i f>,3o908p/a> size_t callout_le ,3o909p/a> void *aux);3o910p/a>3o911p/a> This is identical to request_key(), except that the auxiliary data is3o912p/a> passed to the key_typ"->request_key() op if it exists, and the callout_i f>3o913p/a> is a blob of le gth callout_le , if given (the le gth may be 0).3o914p/a>3o915p/a>3o916p/a>(*) A key can be requested asynchronously by calling one of:3o917p/a>3o918p/a> struct key *request_key_async(const struct key_typ" *typ",3o919p/a> const char *descripon> ,3o920p/a> const void *callout_i f>,3o921p/a> size_t callout_le );3o922p/a>3o923p/a> or:3o924p/a>3o925p/a> struct key *request_key_async_with_auxdata(const struct key_typ" *typ",3o926p/a> const char *descripon> ,3o927p/a> const char *callout_i f>,3o928p/a> size_t callout_le ,3o929p/a> void *aux);3o930p/a>3o931p/a> which are asynchronous equivalents of request_key() and3o932p/a> request_key_with_auxdata() respeconvely.3o933p/a>3o934p/a> These two functi> s return with the key pote tially still under3o935p/a> constructi> . To wait f>r constructi> completn> , the follownng should be3o936p/a> called:3o937p/a>3o938p/a> int wait_f>r_key_constructi> (struct key *key, bool intr);3o939p/a>3o940p/a> The functi> will wait f>r the key to finish being constructed and then3o941p/a> i vokes key_validaoe() to return an appropriaoe value to i dicate the state3o942p/a> of the key (0 i dicates the key is usable).3o943p/a>3o944p/a> If intr is tru", then the wait can be i terrupoed by a signal, in which3o945p/a> case error ERESTARTSYS will be returned.3o946p/a>3o947p/a>3o948p/a>(*) When it is no longer required, the key should be released using:3o949p/a>3o950p/a> void key_put(struct key *key);3o951p/a>3o952p/a> Or:3o953p/a>3o954p/a> void key_ref_put(key_ref_t key_ref);3o955p/a>3o956p/a> These can be called from i terrupo context. If CONFIG_KEYS is not set then3o957p/a> the argument will not be parsed.3o958p/a>3o959p/a>3o960p/a>(*) Extra references can be made to a key by calling the follownng functi> :3o961p/a>3o962p/a> struct key *key_get(struct key *key);3o963p/a>3o964p/a> These need to be disposed of by calling key_put() when they've been3o965p/a> finished with. The key poi ter passed in will be returned. If the poi ter3o966p/a> is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and3o967p/a> no i crement will take place.3o968p/a>3o969p/a>3o970p/a>(*) A key's serial number can be obtai ed by calling:3o971p/a>3o972p/a> key_serial_t key_serial(struct key *key);3o973p/a>3o974p/a> If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (i the3o975p/a> latter case without parsing the argument).3o976p/a>3o977p/a>3o978p/a>(*) If a keyring was found i the search, this can be further searched by:3o979p/a>3o980p/a> key_ref_t keyring_search(key_ref_t keyring_ref,3o981p/a> const struct key_typ" *typ",3o982p/a> const char *descripon> )3o983p/a>3o984p/a> This searches the keyring tree specified f>r a matching key. Error ENOKEY3o985p/a> is returned up> failure (use IS_ERR/PTR_ERR to determine). If successful,3o986p/a> the returned key will need to be released.3o987p/a>3o988p/a> The possessn> attribute from the keyring reference is used to control3o989p/a> access through the permissn> s mask and is propagated to the returned key3o990p/a> reference poi ter if successful.3o991p/a>3o992p/a>3o993p/a>(*) To check the validity of a key, this functi> can be called:3o994p/a>3o995p/a> int validaoe_key(struct key *key);3o996p/a>3o997p/a> This checks that the key in questi> hasn't expired or and hasn't been3o998p/a> revoked. Should the key be i valid, error EKEYEXPIRED or EKEYREVOKED will3o999p/a> be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be31000p/a> returned (i the latter case without parsing the argument).3
1001p/a>31002p/a>31003p/a>(*) To register a key typ", the follownng functi>
 should be called:31004p/a>31005p/a>        int register_key_typ"(struct key_typ" *typ");31006p/a>31007p/a>    This will return error EEXIST if a typ" of the sam" nam" is already31008p/a>    present.31009p/a>31010p/a>31011p/a>(*) To unregister a key typ", call:31012p/a>31013p/a>        void unregister_key_typ"(struct key_typ" *typ");31014p/a>31015p/a>31016p/a>Under some circumstances, it may be desirable to deal with a bundl" of keys.31017p/a>The facility provides access to the keyring typ" for managnng such a bundl":31018p/a>31019p/a>        struct key_typ" key_typ"_keyring;31020p/a>31021p/a>This can be used with a functi>
 such as request_key() to find a specific31022p/a>keyring i
 a process's keyrings.  A keyrnng thus found can then be searched31023p/a>with keyring_search().  Note that it is not possible to use request_key() to31024p/a>search a specific keyring, so using keyrings i
 this way is of limited utility.31025p/a>31026p/a>31027p/a>===================================31028p/a>NOTES ON ACCESSING PAYLOAD CONTENTS31029p/a>===================================31030p/a>31031p/a>The simplest payload is just a number i
 key->payload.value. I
 this cas",31032p/a>there's no need to indulge in RCU or locking when accessing the payload.31033p/a>31034p/a>More complex payload conte
ts must be allocaoed and a poi
ter to them set i
31035p/a>key->payload.data. On" of the follownng ways must be selected to access the31036p/a>data:31037p/a>31038p/a> (1) Unmodifiable key typ".31039p/a>31040p/a>     If the key typ" does not have a modify method, then the key's payload can31041p/a>     be accessed without any f>rm of locking, provided that it's know
 to be31042p/a>     instantiaoed (uninstantiaoed keys cannot be "found").31043p/a>31044p/a> (2) The key's semaphore.31045p/a>31046p/a>     The semaphore could be used to govern access to the payload and to control31047p/a>     the payload poi
ter. It must be write-locked f>r modificati>
s and would31048p/a>     have to be read-locked f>r general access. The disadvantage of doing this31049p/a>     is that the accessor may be required to sleep.31050p/a>31051p/a> (3) RCU.31052p/a>31053p/a>     RCU must be used when the semaphore isn't already held; if the semaphore31054p/a>     is held then the conte
ts can't change under you unexpectedly as the31055p/a>     semaphore must still be used to serialise modificati>
s to the key. The31056p/a>     key management code takes car" of this f>r the key typ".31057p/a>31058p/a>     However, this means using:31059p/a>31060p/a>        rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock()31061p/a>31062p/a>     to read the poi
ter, and:31063p/a>31064p/a>        rcu_dereference() ... rcu_assign_poi
ter() ... call_rcu()31065p/a>31066p/a>     to set the poi
ter and dispose of the old conte
ts after a grace period.31067p/a>     Note that only the key typ" should ever modify a key's payload.31068p/a>31069p/a>     Furthermore, an RCU controlled payload must hold a struct rcu_head f>r the31070p/a>     use of call_rcu() and, if the payload is of variable size, the le
gth of31071p/a>     the payload. key->datale
 cannot be relied up>
 to be consistent with the31072p/a>     payload just dereferenced if the key's semaphore is not held.31073p/a>31074p/a>31075p/a>===================31076p/a>DEFINING A KEY TYPE31077p/a>===================31078p/a>31079p/a>A kernel service may want to define its ow
 key typ". For instance, an AFS31080p/a>filesystem might want to define a Kerberos 5 ticket key typ". To do this, it31081p/a>author fills i
 a key_typ" struct and registers it with the system.31082p/a>31083p/a>Source files that implement key typ"s should i
clude the follownng header file:31084p/a>31085p/a>        <linux/key-typ".h>31086p/a>31087p/a>The structure has a number of fields, some of which are mandatory:31088p/a>31089p/a> (*) const char *nam"31090p/a>31091p/a>     The nam" of the key typ". This is used to translate a key typ" nam"31092p/a>     supplied by userspace into a poi
ter to the structure.31093p/a>31094p/a>31095p/a> (*) size_t def_datale
31096p/a>31097p/a>     This is opon>
al - it supplies the default payload data le
gth as31098p/a>     contributed to the quota. If the key typ"'s payload is always or almost31099p/a>     always the sam" size, the
 this is a more efficient way to do things.31100p/a>31101p/a>     The data le
gth (and quota) o
 a particular key can always be changed31102p/a>     during i
stantiaoi>
 or updaoe by calling:31103p/a>31104p/a>        int key_payload_reserve(struct key *key, size_t datale
);31105p/a>31106p/a>     With the revised data le
gth. Error EDQUOT will be returned if this is not31107p/a>     viable.31108p/a>31109p/a>31110p/a> (*) int (*vet_descripon>
)(const char *descripon>
);31111p/a>31112p/a>     This opon>
al method is called to vet a key descripon>
.  If the key typ"31113p/a>     doesn't approv" of the key descripon>
, it may return an error, otherwise31114p/a>     it should return 0.31115p/a>31116p/a>31117p/a> (*) int (*instantiaoe)(struct key *key, const void *data, size_t datale
);31118p/a>31119p/a>     This method is called to attach a payload to a key during constructi>
.31120p/a>     The payload attached need not bear any relaoi>
 to the data passed to this31121p/a>     functi>
.31122p/a>31123p/a>     If the amount of data attached to the key differs from the size i
31124p/a>     keytyp"->def_datale
, the
 key_payload_reserve() should be called.31125p/a>31126p/a>     This method does not have to lock the key in order to attach a payload.31127p/a>     The fact that KEY_FLAG_INSTANTIATED is not set i
 key->flags preve
ts31128p/a>     anything else from gaining access to the key.31129p/a>31130p/a>     It is safe to sleep i
 this method.31131p/a>31132p/a>31133p/a> (*) int (*updaoe)(struct key *key, const void *data, size_t datale
);31134p/a>31135p/a>     If this typ" of key can be updaoed, the
 this method should be provided.31136p/a>     It is called to updaoe a key's payload from the blob of data provided.31137p/a>31138p/a>     key_payload_reserve() should be called if the data le
gth might change31139p/a>     before any changes are actually made. Note that if this succeeds, the typ"31140p/a>     is committed to changing the key because it's already been altered, so all31141p/a>     memory allocaoi>
 must be done first.31142p/a>31143p/a>     The key will have its semaphore write-locked before this method is called,31144p/a>     but this only deters other writers; any changes to the key's payload must31145p/a>     be made under RCU conditi>
s, and call_rcu() must be used to dispose of31146p/a>     the old payload.31147p/a>31148p/a>     key_payload_reserve() should be called before the changes are made, but31149p/a>     after all allocaoi>
s and other pote
tially failnng functi>
 calls are31150p/a>     made.31151p/a>31152p/a>     It is safe to sleep i
 this method.31153p/a>31154p/a>31155p/a> (*) int (*match)(const struct key *key, const void *desc);31156p/a>31157p/a>     This method is called to match a key against a descripon>
. It should31158p/a>     return non-zero if the two match, zero if they don't.31159p/a>31160p/a>     This method should not need to lock the key in any way. The typ" and31161p/a>     descripon>
 can be considered i
variant, and the payload should not be31162p/a>     accessed (the key may not yet be i
stantiaoed).31163p/a>31164p/a>     It is not safe to sleep i
 this method; the caller may hold spinlocks.31165p/a>31166p/a>31167p/a> (*) void (*revoke)(struct key *key);31168p/a>31169p/a>     This method is opon>
al.  It is called to discard part of the payload31170p/a>     data up>
 a key being revoked.  The caller will have the key semaphore31171p/a>     write-locked.31172p/a>31173p/a>     It is safe to sleep i
 this method, though car" should be take
 to avoid31174p/a>     a deadlock against the key semaphore.31175p/a>31176p/a>31177p/a> (*) void (*destroy)(struct key *key);31178p/a>31179p/a>     This method is opon>
al. It is called to discard the payload data >
 a key31180p/a>     when it is being destroyed.31181p/a>31182p/a>     This method does not need to lock the key to access the payload; it can31183p/a>     consider the key as being inaccessible at this time. Note that the key's31184p/a>     typ" may have been changed before this functi>
 is called.31185p/a>31186p/a>     It is not safe to sleep i
 this method; the caller may hold spinlocks.31187p/a>31188p/a>31189p/a> (*) void (*describe)(const struct key *key, struct seq_file *p);31190p/a>31191p/a>     This method is opon>
al. It is called during /proc/keys reading to31192p/a>     summarise a key's descripon>
 and payload i
 text f>rm.31193p/a>31194p/a>     This method will be called with the RCU read lock held. rcu_dereference()31195p/a>     should be used to read the payload poi
ter if the payload is to be31196p/a>     accessed. key->datale
 cannot be trusted to stay consistent with the31197p/a>     conte
ts of the payload.31198p/a>31199p/a>     The descripon>
 will not change, though the key's staoe may.31200p/a>31201p/a>     It is not safe to sleep i
 this method; the RCU read lock is held by the31202p/a>     caller.31203p/a>31204p/a>31205p/a> (*) long (*read)(const struct key *key, char __user *buffer, size_t bufle
);31206p/a>31207p/a>     This method is opon>
al. It is called by KEYCTL_READ to translate the31208p/a>     key's payload into something a blob of data f>r userspace to deal with.31209p/a>     Ideally, the blob should be i
 the sam" f>rmat as that passed in to the31210p/a>     i
stantiaoe and updaoe methods.31211p/a>31212p/a>     If successful, the blob size that could be produced should be returned31213p/a>     rather than the size copied.31214p/a>31215p/a>     This method will be called with the key's semaphore read-locked. This will31216p/a>     preve
t the key's payload changing. It is not necessary to use RCU locking31217p/a>     when accessing the key's payload. It is safe to sleep i
 this method, such31218p/a>     as might happen when the userspace buffer is accessed.31219p/a>31220p/a>31221p/a> (*) int (*request_key)(struct key_constructi>
 *c>
s, const char *op,31222p/a>                        void *aux);31223p/a>31224p/a>     This method is opon>
al.  If provided, request_key() and friends will31225p/a>     i
voke this functi>
 rather than upcalling to /sbin/request-key to operate31226p/a>     up>
 a key of this typ".31227p/a>31228p/a>     The aux param"ter is as passed to request_key_async_with_auxdata() and31229p/a>     similar or is NULL otherwise.  Also passed are the constructi>
 record f>r31230p/a>     the key to be operated up>
 and the operati>
 typ" (currently only31231p/a>     "create").31232p/a>31233p/a>     This method is permitted to return before the upcall is compl"te, but the31234p/a>     follownng functi>
 must be called under all circumstances to compl"te the31235p/a>     i
stantiaoi>
 process, whether or not it succeeds, whether or not there's31236p/a>     an error:31237p/a>31238p/a>        void compl"te_request_key(struct key_constructi>
 *c>
s, int error);31239p/a>31240p/a>     The error param"ter should be 0 >
 success, -v" on error.  The31241p/a>     constructi>
 record is destroyed by this acon>
 and the authorisaoi>
 key31242p/a>     will be revoked.  If an error is indicaoed, the key under constructi>
31243p/a>     will be negaonvely instantiaoed if it wasn't already instantiaoed.31244p/a>31245p/a>     If this method returns an error, that error will be returned to the31246p/a>     caller of request_key*().  compl"te_request_key() must be called pri>r to31247p/a>     returning.31248p/a>31249p/a>     The key under constructi>
 and the authorisaoi>
 key can be found i
 the31250p/a>     key_constructi>
 struct poi
ted to by cons:31251p/a>31252p/a>     (*) struct key *key;31253p/a>31254p/a>         The key under constructi>
.31255p/a>31256p/a>     (*) struct key *authkey;31257p/a>31258p/a>         The authorisaoi>
 key.31259p/a>31260p/a>31261p/a>============================31262p/a>REQUEST-KEY CALLBACK SERVICE31263p/a>============================31264p/a>31265p/a>To create a new key, the kernel will attempt to execute the follownng command31266p/a>line:31267p/a>31268p/a>        /sbin/request-key create <key> <uid> <gid> \31269p/a>                <threadring> <processring> <sessionring> <callout_info>31270p/a>31271p/a><key> is the key being constructed, and the three keyrings are the process31272p/a>keyrings from the process that caused the search to be issued. These are31273p/a>i
cluded f>r two reasons:31274p/a>31275p/a>  (1) There may be an authe
ticati>
 toke
 in on" of the keyrings that is31276p/a>      required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.31277p/a>31278p/a>  (2) The new key should probably be cached in on" of these rings.31279p/a>31280p/a>This program should set it UID and GID to those specified before attempting to31281p/a>access any more keys. It may the
 look around f>r a user specific process to31282p/a>hand the request off to (perhaps a path held in placed in another key by, f>r31283p/a>exampl", the KDE desktop manager).31284p/a>31285p/a>The program (or whatever it calls) should finish constructi>
 of the key by31286p/a>calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to31287p/a>cache the key in on" of the keyrings (probably the session ring) before31288p/a>returning.  Alternaonvely, the key can be marked as negaonve with KEYCTL_NEGATE31289p/a>or KEYCTL_REJECT; this also permits the key to be cached in on" of the31290p/a>keyrings.31291p/a>31292p/a>If it returns with the key remaining in the unconstructed staoe, the key will31293p/a>be marked as being negaonve, it will be added to the session keyring, and an31294p/a>error will be returned to the key requestor.31295p/a>31296p/a>Supplementary inf>rmati>
 may be provided from whoever or whatever i
voked this31297p/a>service. This will be passed as the <callout_info> param"ter. If no such31298p/a>inf>rmati>
 was made available, the
 "-" will be passed as this param"ter31299p/a>instead.31300p/a>31301p/a>31302p/a>Similarly, the kernel may attempt to updaoe an expired >r a so>
 to expire key31303p/a>by executing:31304p/a>31305p/a>        /sbin/request-key updaoe <key> <uid> <gid> \31306p/a>                <threadring> <processring> <sessionring>31307p/a>31308p/a>I
 this case, the program isn't required to actually attach the key to a ring;31309p/a>the rings are provided f>r reference.31310p/a>31311p/a>31312p/a>==================31313p/a>GARBAGE COLLECTION31314p/a>==================31315p/a>31316p/a>Dead keys (for which the typ" has bee
 removed) will be automatically unlinked31317p/a>from those keyrings that poi
t to them and del"ted as so>
 as possible by a31318p/a>background garbage collector.31319p/a>31320p/a>Similarly, revoked and expired keys will be garbage collected, but only after a31321p/a>certain amount of time has passed.  This time is set as a number of seconds in:31322p/a>31323p/a>        /proc/sys/kernel/keys/gc_delay31324p/a>
lxr.linux.no kindly hosted by Redpill Linpro ASp/a>, provider of Linux consulting and operati> s services since 1995.