€•ïˆ      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ-/translations/zh_CN/security/keys/request-key”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/zh_TW/security/keys/request-key”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/it_IT/security/keys/request-key”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ja_JP/security/keys/request-key”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ko_KR/security/keys/request-key”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/sp_SP/security/keys/request-key”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒKey Request Service”h]”hŒKey Request Service”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒG/var/lib/git/docbuild/linux/Documentation/security/keys/request-key.rst”h KubhŒ	paragraph”“”)”}”(hŒ´The key request service is part of the key retention service (refer to
Documentation/security/keys/core.rst).  This document explains more fully how
the requesting algorithm works.”h]”hŒ´The key request service is part of the key retention service (refer to
Documentation/security/keys/core.rst).  This document explains more fully how
the requesting algorithm works.”…””}”(hh¹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hŒ\The process starts by either the kernel requesting a service by calling
``request_key*()``::”h]”(hŒHThe process starts by either the kernel requesting a service by calling
”…””}”(hhÇhžhhŸNh NubhŒliteral”“”)”}”(hŒ``request_key*()``”h]”hŒrequest_key*()”…””}”(hhÑhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÏhhÇubhŒ:”…””}”(hhÇhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K	hh£hžhubhŒliteral_block”“”)”}”(hŒ˜struct key *request_key(const struct key_type *type,
                        const char *description,
                        const char *callout_info);”h]”hŒ˜struct key *request_key(const struct key_type *type,
                        const char *description,
                        const char *callout_info);”…””}”hhësbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1héhŸh¶h Khh£hžhubh¸)”}”(hŒor::”h]”hŒor:”…””}”(hhûhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubhê)”}”(hŒâstruct key *request_key_tag(const struct key_type *type,
                            const char *description,
                            const struct key_tag *domain_tag,
                            const char *callout_info);”h]”hŒâstruct key *request_key_tag(const struct key_type *type,
                            const char *description,
                            const struct key_tag *domain_tag,
                            const char *callout_info);”…””}”hj	  sbah}”(h]”h ]”h"]”h$]”h&]”hùhúuh1héhŸh¶h Khh£hžhubh¸)”}”(hŒor::”h]”hŒor:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubhê)”}”(hXo  struct key *request_key_with_auxdata(const struct key_type *type,
                                     const char *description,
                                     const struct key_tag *domain_tag,
                                     const char *callout_info,
                                     size_t callout_len,
                                     void *aux);”h]”hXo  struct key *request_key_with_auxdata(const struct key_type *type,
                                     const char *description,
                                     const struct key_tag *domain_tag,
                                     const char *callout_info,
                                     size_t callout_len,
                                     void *aux);”…””}”hj%  sbah}”(h]”h ]”h"]”h$]”h&]”hùhúuh1héhŸh¶h Khh£hžhubh¸)”}”(hŒor::”h]”hŒor:”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K hh£hžhubhê)”}”(hŒ¬struct key *request_key_rcu(const struct key_type *type,
                            const char *description,
                            const struct key_tag *domain_tag);”h]”hŒ¬struct key *request_key_rcu(const struct key_type *type,
                            const char *description,
                            const struct key_tag *domain_tag);”…””}”hjA  sbah}”(h]”h ]”h"]”h$]”h&]”hùhúuh1héhŸh¶h K"hh£hžhubh¸)”}”(hŒ6Or by userspace invoking the request_key system call::”h]”hŒ5Or by userspace invoking the request_key system call:”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K&hh£hžhubhê)”}”(hŒÄkey_serial_t request_key(const char *type,
                         const char *description,
                         const char *callout_info,
                         key_serial_t dest_keyring);”h]”hŒÄkey_serial_t request_key(const char *type,
                         const char *description,
                         const char *callout_info,
                         key_serial_t dest_keyring);”…””}”hj]  sbah}”(h]”h ]”h"]”h$]”h&]”hùhúuh1héhŸh¶h K(hh£hžhubh¸)”}”(hX  The main difference between the access points is that the in-kernel interface
does not need to link the key to a keyring to prevent it from being immediately
destroyed.  The kernel interface returns a pointer directly to the key, and
it's up to the caller to destroy the key.”h]”hX  The main difference between the access points is that the in-kernel interface
does not need to link the key to a keyring to prevent it from being immediately
destroyed.  The kernel interface returns a pointer directly to the key, and
itâ€™s up to the caller to destroy the key.”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K-hh£hžhubh¸)”}”(hŒ¯The request_key_tag() call is like the in-kernel request_key(), except that it
also takes a domain tag that allows keys to be separated by namespace and
killed off as a group.”h]”hŒ¯The request_key_tag() call is like the in-kernel request_key(), except that it
also takes a domain tag that allows keys to be separated by namespace and
killed off as a group.”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K2hh£hžhubh¸)”}”(hX  The request_key_with_auxdata() calls is like the request_key_tag() call, except
that they permit auxiliary data to be passed to the upcaller (the default is
NULL).  This is only useful for those key types that define their own upcall
mechanism rather than using /sbin/request-key.”h]”hX  The request_key_with_auxdata() calls is like the request_key_tag() call, except
that they permit auxiliary data to be passed to the upcaller (the default is
NULL).  This is only useful for those key types that define their own upcall
mechanism rather than using /sbin/request-key.”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K6hh£hžhubh¸)”}”(hŒ¯The request_key_rcu() call is like the request_key_tag() call, except that it
doesn't check for keys that are under construction and doesn't attempt to
construct missing keys.”h]”hŒ³The request_key_rcu() call is like the request_key_tag() call, except that it
doesnâ€™t check for keys that are under construction and doesnâ€™t attempt to
construct missing keys.”…””}”(hj•  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K;hh£hžhubh¸)”}”(hŒªThe userspace interface links the key to a keyring associated with the process
to prevent the key from going away, and returns the serial number of the key to
the caller.”h]”hŒªThe userspace interface links the key to a keyring associated with the process
to prevent the key from going away, and returns the serial number of the key to
the caller.”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K?hh£hžhubh¸)”}”(hŒÅThe following example assumes that the key types involved don't define their
own upcall mechanisms.  If they do, then those should be substituted for the
forking and execution of /sbin/request-key.”h]”hŒÇThe following example assumes that the key types involved donâ€™t define their
own upcall mechanisms.  If they do, then those should be substituted for the
forking and execution of /sbin/request-key.”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KDhh£hžhubh¢)”}”(hhh]”(h§)”}”(hŒThe Process”h]”hŒThe Process”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj¿  hžhhŸh¶h KJubh¸)”}”(hŒ+A request proceeds in the following manner:”h]”hŒ+A request proceeds in the following manner:”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KLhj¿  hžhubhŒblock_quote”“”)”}”(hX  1) Process A calls request_key() [the userspace syscall calls the kernel
   interface].

2) request_key() searches the process's subscribed keyrings to see if there's
   a suitable key there.  If there is, it returns the key.  If there isn't,
   and callout_info is not set, an error is returned.  Otherwise the process
   proceeds to the next step.

3) request_key() sees that A doesn't have the desired key yet, so it creates
   two things:

    a) An uninstantiated key U of requested type and description.

    b) An authorisation key V that refers to key U and notes that process A
       is the context in which key U should be instantiated and secured, and
       from which associated key requests may be satisfied.

4) request_key() then forks and executes /sbin/request-key with a new session
   keyring that contains a link to auth key V.

5) /sbin/request-key assumes the authority associated with key U.

6) /sbin/request-key execs an appropriate program to perform the actual
   instantiation.

7) The program may want to access another key from A's context (say a
   Kerberos TGT key).  It just requests the appropriate key, and the keyring
   search notes that the session keyring has auth key V in its bottom level.

   This will permit it to then search the keyrings of process A with the
   UID, GID, groups and security info of process A as if it was process A,
   and come up with key W.

8) The program then does what it must to get the data with which to
   instantiate key U, using key W as a reference (perhaps it contacts a
   Kerberos server using the TGT) and then instantiates key U.

9) Upon instantiating key U, auth key V is automatically revoked so that it
   may not be used again.

10) The program then exits 0 and request_key() deletes key V and returns key
    U to the caller.
”h]”hŒenumerated_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒRProcess A calls request_key() [the userspace syscall calls the kernel
interface].
”h]”h¸)”}”(hŒQProcess A calls request_key() [the userspace syscall calls the kernel
interface].”h]”hŒQProcess A calls request_key() [the userspace syscall calls the kernel
interface].”…””}”(hjï  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KNhjë  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hŒùrequest_key() searches the process's subscribed keyrings to see if there's
a suitable key there.  If there is, it returns the key.  If there isn't,
and callout_info is not set, an error is returned.  Otherwise the process
proceeds to the next step.
”h]”h¸)”}”(hŒørequest_key() searches the process's subscribed keyrings to see if there's
a suitable key there.  If there is, it returns the key.  If there isn't,
and callout_info is not set, an error is returned.  Otherwise the process
proceeds to the next step.”h]”hŒþrequest_key() searches the processâ€™s subscribed keyrings to see if thereâ€™s
a suitable key there.  If there is, it returns the key.  If there isnâ€™t,
and callout_info is not set, an error is returned.  Otherwise the process
proceeds to the next step.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KQhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hXc  request_key() sees that A doesn't have the desired key yet, so it creates
two things:

 a) An uninstantiated key U of requested type and description.

 b) An authorisation key V that refers to key U and notes that process A
    is the context in which key U should be instantiated and secured, and
    from which associated key requests may be satisfied.
”h]”(h¸)”}”(hŒUrequest_key() sees that A doesn't have the desired key yet, so it creates
two things:”h]”hŒWrequest_key() sees that A doesnâ€™t have the desired key yet, so it creates
two things:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KVhj  ubjß  )”}”(hX  a) An uninstantiated key U of requested type and description.

b) An authorisation key V that refers to key U and notes that process A
   is the context in which key U should be instantiated and secured, and
   from which associated key requests may be satisfied.
”h]”jå  )”}”(hhh]”(jê  )”}”(hŒ;An uninstantiated key U of requested type and description.
”h]”h¸)”}”(hŒ:An uninstantiated key U of requested type and description.”h]”hŒ:An uninstantiated key U of requested type and description.”…””}”(hj8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KYhj4  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hj1  ubjê  )”}”(hŒÀAn authorisation key V that refers to key U and notes that process A
is the context in which key U should be instantiated and secured, and
from which associated key requests may be satisfied.
”h]”h¸)”}”(hŒ¿An authorisation key V that refers to key U and notes that process A
is the context in which key U should be instantiated and secured, and
from which associated key requests may be satisfied.”h]”hŒ¿An authorisation key V that refers to key U and notes that process A
is the context in which key U should be instantiated and secured, and
from which associated key requests may be satisfied.”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K[hjL  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hj1  ubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œ
loweralpha”Œprefix”hŒsuffix”Œ)”uh1jä  hj-  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÞ  hŸh¶h KYhj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hŒwrequest_key() then forks and executes /sbin/request-key with a new session
keyring that contains a link to auth key V.
”h]”h¸)”}”(hŒvrequest_key() then forks and executes /sbin/request-key with a new session
keyring that contains a link to auth key V.”h]”hŒvrequest_key() then forks and executes /sbin/request-key with a new session
keyring that contains a link to auth key V.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K_hj{  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hŒ?/sbin/request-key assumes the authority associated with key U.
”h]”h¸)”}”(hŒ>/sbin/request-key assumes the authority associated with key U.”h]”hŒ>/sbin/request-key assumes the authority associated with key U.”…””}”(hj—  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kbhj“  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hŒT/sbin/request-key execs an appropriate program to perform the actual
instantiation.
”h]”h¸)”}”(hŒS/sbin/request-key execs an appropriate program to perform the actual
instantiation.”h]”hŒS/sbin/request-key execs an appropriate program to perform the actual
instantiation.”…””}”(hj¯  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kdhj«  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hX~  The program may want to access another key from A's context (say a
Kerberos TGT key).  It just requests the appropriate key, and the keyring
search notes that the session keyring has auth key V in its bottom level.

This will permit it to then search the keyrings of process A with the
UID, GID, groups and security info of process A as if it was process A,
and come up with key W.
”h]”(h¸)”}”(hŒÖThe program may want to access another key from A's context (say a
Kerberos TGT key).  It just requests the appropriate key, and the keyring
search notes that the session keyring has auth key V in its bottom level.”h]”hŒØThe program may want to access another key from Aâ€™s context (say a
Kerberos TGT key).  It just requests the appropriate key, and the keyring
search notes that the session keyring has auth key V in its bottom level.”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KghjÃ  ubh¸)”}”(hŒ¥This will permit it to then search the keyrings of process A with the
UID, GID, groups and security info of process A as if it was process A,
and come up with key W.”h]”hŒ¥This will permit it to then search the keyrings of process A with the
UID, GID, groups and security info of process A as if it was process A,
and come up with key W.”…””}”(hjÕ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KkhjÃ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hŒÂThe program then does what it must to get the data with which to
instantiate key U, using key W as a reference (perhaps it contacts a
Kerberos server using the TGT) and then instantiates key U.
”h]”h¸)”}”(hŒÁThe program then does what it must to get the data with which to
instantiate key U, using key W as a reference (perhaps it contacts a
Kerberos server using the TGT) and then instantiates key U.”h]”hŒÁThe program then does what it must to get the data with which to
instantiate key U, using key W as a reference (perhaps it contacts a
Kerberos server using the TGT) and then instantiates key U.”…””}”(hjí  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kohjé  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hŒ`Upon instantiating key U, auth key V is automatically revoked so that it
may not be used again.
”h]”h¸)”}”(hŒ_Upon instantiating key U, auth key V is automatically revoked so that it
may not be used again.”h]”hŒ_Upon instantiating key U, auth key V is automatically revoked so that it
may not be used again.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kshj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubjê  )”}”(hŒZThe program then exits 0 and request_key() deletes key V and returns key
U to the caller.
”h]”h¸)”}”(hŒYThe program then exits 0 and request_key() deletes key V and returns key
U to the caller.”h]”hŒYThe program then exits 0 and request_key() deletes key V and returns key
U to the caller.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kvhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjæ  ubeh}”(h]”h ]”h"]”h$]”h&]”jj  Œarabic”jl  hjm  jn  uh1jä  hjà  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÞ  hŸh¶h KNhj¿  hžhubh¸)”}”(hX7  This also extends further.  If key W (step 7 above) didn't exist, key W would
be created uninstantiated, another auth key (X) would be created (as per step
3) and another copy of /sbin/request-key spawned (as per step 4); but the
context specified by auth key X will still be process A, as it was in auth key
V.”h]”hX9  This also extends further.  If key W (step 7 above) didnâ€™t exist, key W would
be created uninstantiated, another auth key (X) would be created (as per step
3) and another copy of /sbin/request-key spawned (as per step 4); but the
context specified by auth key X will still be process A, as it was in auth key
V.”…””}”(hj>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kyhj¿  hžhubh¸)”}”(hŒÚThis is because process A's keyrings can't simply be attached to
/sbin/request-key at the appropriate places because (a) execve will discard two
of them, and (b) it requires the same UID/GID/Groups all the way through.”h]”hŒÞThis is because process Aâ€™s keyrings canâ€™t simply be attached to
/sbin/request-key at the appropriate places because (a) execve will discard two
of them, and (b) it requires the same UID/GID/Groups all the way through.”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj¿  hžhubeh}”(h]”Œthe-process”ah ]”h"]”Œthe process”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KJubh¢)”}”(hhh]”(h§)”}”(hŒ$Negative Instantiation And Rejection”h]”hŒ$Negative Instantiation And Rejection”…””}”(hje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjb  hžhhŸh¶h K…ubh¸)”}”(hXC  Rather than instantiating a key, it is possible for the possessor of an
authorisation key to negatively instantiate a key that's under construction.
This is a short duration placeholder that causes any attempt at re-requesting
the key while it exists to fail with error ENOKEY if negated or the specified
error if rejected.”h]”hXE  Rather than instantiating a key, it is possible for the possessor of an
authorisation key to negatively instantiate a key thatâ€™s under construction.
This is a short duration placeholder that causes any attempt at re-requesting
the key while it exists to fail with error ENOKEY if negated or the specified
error if rejected.”…””}”(hjs  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K‡hjb  hžhubh¸)”}”(hŒThis is provided to prevent excessive repeated spawning of /sbin/request-key
processes for a key that will never be obtainable.”h]”hŒThis is provided to prevent excessive repeated spawning of /sbin/request-key
processes for a key that will never be obtainable.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khjb  hžhubh¸)”}”(hŒ¸Should the /sbin/request-key process exit anything other than 0 or die on a
signal, the key under construction will be automatically negatively
instantiated for a short amount of time.”h]”hŒ¸Should the /sbin/request-key process exit anything other than 0 or die on a
signal, the key under construction will be automatically negatively
instantiated for a short amount of time.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khjb  hžhubeh}”(h]”Œ$negative-instantiation-and-rejection”ah ]”h"]”Œ$negative instantiation and rejection”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K…ubh¢)”}”(hhh]”(h§)”}”(hŒThe Search Algorithm”h]”hŒThe Search Algorithm”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj¥  hžhhŸh¶h K–ubh¸)”}”(hŒEA search of any particular keyring proceeds in the following fashion:”h]”hŒEA search of any particular keyring proceeds in the following fashion:”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K˜hj¥  hžhubjß  )”}”(hX  1) When the key management code searches for a key (keyring_search_rcu) it
   firstly calls key_permission(SEARCH) on the keyring it's starting with,
   if this denies permission, it doesn't search further.

2) It considers all the non-keyring keys within that keyring and, if any key
   matches the criteria specified, calls key_permission(SEARCH) on it to see
   if the key is allowed to be found.  If it is, that key is returned; if
   not, the search continues, and the error code is retained if of higher
   priority than the one currently set.

3) It then considers all the keyring-type keys in the keyring it's currently
   searching.  It calls key_permission(SEARCH) on each keyring, and if this
   grants permission, it recurses, executing steps (2) and (3) on that
   keyring.
”h]”jå  )”}”(hhh]”(jê  )”}”(hŒÆWhen the key management code searches for a key (keyring_search_rcu) it
firstly calls key_permission(SEARCH) on the keyring it's starting with,
if this denies permission, it doesn't search further.
”h]”h¸)”}”(hŒÅWhen the key management code searches for a key (keyring_search_rcu) it
firstly calls key_permission(SEARCH) on the keyring it's starting with,
if this denies permission, it doesn't search further.”h]”hŒÉWhen the key management code searches for a key (keyring_search_rcu) it
firstly calls key_permission(SEARCH) on the keyring itâ€™s starting with,
if this denies permission, it doesnâ€™t search further.”…””}”(hjÏ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KšhjË  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjÈ  ubjê  )”}”(hXG  It considers all the non-keyring keys within that keyring and, if any key
matches the criteria specified, calls key_permission(SEARCH) on it to see
if the key is allowed to be found.  If it is, that key is returned; if
not, the search continues, and the error code is retained if of higher
priority than the one currently set.
”h]”h¸)”}”(hXF  It considers all the non-keyring keys within that keyring and, if any key
matches the criteria specified, calls key_permission(SEARCH) on it to see
if the key is allowed to be found.  If it is, that key is returned; if
not, the search continues, and the error code is retained if of higher
priority than the one currently set.”h]”hXF  It considers all the non-keyring keys within that keyring and, if any key
matches the criteria specified, calls key_permission(SEARCH) on it to see
if the key is allowed to be found.  If it is, that key is returned; if
not, the search continues, and the error code is retained if of higher
priority than the one currently set.”…””}”(hjç  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kžhjã  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjÈ  ubjê  )”}”(hŒàIt then considers all the keyring-type keys in the keyring it's currently
searching.  It calls key_permission(SEARCH) on each keyring, and if this
grants permission, it recurses, executing steps (2) and (3) on that
keyring.
”h]”h¸)”}”(hŒßIt then considers all the keyring-type keys in the keyring it's currently
searching.  It calls key_permission(SEARCH) on each keyring, and if this
grants permission, it recurses, executing steps (2) and (3) on that
keyring.”h]”hŒáIt then considers all the keyring-type keys in the keyring itâ€™s currently
searching.  It calls key_permission(SEARCH) on each keyring, and if this
grants permission, it recurses, executing steps (2) and (3) on that
keyring.”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K¤hjû  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjÈ  ubeh}”(h]”h ]”h"]”h$]”h&]”jj  j7  jl  hjm  jn  uh1jä  hjÄ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÞ  hŸh¶h Kšhj¥  hžhubh¸)”}”(hŒ¤The process stops immediately a valid key is found with permission granted to
use it.  Any error from a previous match attempt is discarded and the key is
returned.”h]”hŒ¤The process stops immediately a valid key is found with permission granted to
use it.  Any error from a previous match attempt is discarded and the key is
returned.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K©hj¥  hžhubh¸)”}”(hŒuWhen request_key() is invoked, if CONFIG_KEYS_REQUEST_CACHE=y, a per-task
one-key cache is first checked for a match.”h]”hŒuWhen request_key() is invoked, if CONFIG_KEYS_REQUEST_CACHE=y, a per-task
one-key cache is first checked for a match.”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K­hj¥  hžhubh¸)”}”(hŒaWhen search_process_keyrings() is invoked, it performs the following searches
until one succeeds:”h]”hŒaWhen search_process_keyrings() is invoked, it performs the following searches
until one succeeds:”…””}”(hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K°hj¥  hžhubjß  )”}”(hXÏ  1) If extant, the process's thread keyring is searched.

2) If extant, the process's process keyring is searched.

3) The process's session keyring is searched.

4) If the process has assumed the authority associated with a request_key()
   authorisation key then:

    a) If extant, the calling process's thread keyring is searched.

    b) If extant, the calling process's process keyring is searched.

    c) The calling process's session keyring is searched.
”h]”jå  )”}”(hhh]”(jê  )”}”(hŒ5If extant, the process's thread keyring is searched.
”h]”h¸)”}”(hŒ4If extant, the process's thread keyring is searched.”h]”hŒ6If extant, the processâ€™s thread keyring is searched.”…””}”(hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K³hjP  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjM  ubjê  )”}”(hŒ6If extant, the process's process keyring is searched.
”h]”h¸)”}”(hŒ5If extant, the process's process keyring is searched.”h]”hŒ7If extant, the processâ€™s process keyring is searched.”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kµhjh  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjM  ubjê  )”}”(hŒ+The process's session keyring is searched.
”h]”h¸)”}”(hŒ*The process's session keyring is searched.”h]”hŒ,The processâ€™s session keyring is searched.”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K·hj€  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjM  ubjê  )”}”(hX  If the process has assumed the authority associated with a request_key()
authorisation key then:

 a) If extant, the calling process's thread keyring is searched.

 b) If extant, the calling process's process keyring is searched.

 c) The calling process's session keyring is searched.
”h]”(h¸)”}”(hŒ`If the process has assumed the authority associated with a request_key()
authorisation key then:”h]”hŒ`If the process has assumed the authority associated with a request_key()
authorisation key then:”…””}”(hjœ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K¹hj˜  ubjß  )”}”(hŒ¹a) If extant, the calling process's thread keyring is searched.

b) If extant, the calling process's process keyring is searched.

c) The calling process's session keyring is searched.
”h]”jå  )”}”(hhh]”(jê  )”}”(hŒ=If extant, the calling process's thread keyring is searched.
”h]”h¸)”}”(hŒ<If extant, the calling process's thread keyring is searched.”h]”hŒ>If extant, the calling processâ€™s thread keyring is searched.”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K¼hj±  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hj®  ubjê  )”}”(hŒ>If extant, the calling process's process keyring is searched.
”h]”h¸)”}”(hŒ=If extant, the calling process's process keyring is searched.”h]”hŒ?If extant, the calling processâ€™s process keyring is searched.”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K¾hjÉ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hj®  ubjê  )”}”(hŒ3The calling process's session keyring is searched.
”h]”h¸)”}”(hŒ2The calling process's session keyring is searched.”h]”hŒ4The calling processâ€™s session keyring is searched.”…””}”(hjå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÀhjá  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jé  hj®  ubeh}”(h]”h ]”h"]”h$]”h&]”jj  jk  jl  hjm  jn  uh1jä  hjª  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÞ  hŸh¶h K¼hj˜  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jé  hjM  ubeh}”(h]”h ]”h"]”h$]”h&]”jj  j7  jl  hjm  jn  uh1jä  hjI  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÞ  hŸh¶h K³hj¥  hžhubh¸)”}”(hX  The moment one succeeds, all pending errors are discarded and the found key is
returned.  If CONFIG_KEYS_REQUEST_CACHE=y, then that key is placed in the
per-task cache, displacing the previous key.  The cache is cleared on exit or
just prior to resumption of userspace.”h]”hX  The moment one succeeds, all pending errors are discarded and the found key is
returned.  If CONFIG_KEYS_REQUEST_CACHE=y, then that key is placed in the
per-task cache, displacing the previous key.  The cache is cleared on exit or
just prior to resumption of userspace.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÂhj¥  hžhubh¸)”}”(hŒƒOnly if all these fail does the whole thing fail with the highest priority
error.  Note that several errors may have come from LSM.”h]”hŒƒOnly if all these fail does the whole thing fail with the highest priority
error.  Note that several errors may have come from LSM.”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÇhj¥  hžhubh¸)”}”(hŒThe error priority is::”h]”hŒThe error priority is:”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÊhj¥  hžhubhê)”}”(hŒ"EKEYREVOKED > EKEYEXPIRED > ENOKEY”h]”hŒ"EKEYREVOKED > EKEYEXPIRED > ENOKEY”…””}”hjA  sbah}”(h]”h ]”h"]”h$]”h&]”hùhúuh1héhŸh¶h KÌhj¥  hžhubh¸)”}”(hŒEACCES/EPERM are only returned on a direct search of a specific keyring where
the basal keyring does not grant Search permission.”h]”hŒEACCES/EPERM are only returned on a direct search of a specific keyring where
the basal keyring does not grant Search permission.”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÎhj¥  hžhubeh}”(h]”Œthe-search-algorithm”ah ]”h"]”Œthe search algorithm”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K–ubeh}”(h]”Œkey-request-service”ah ]”h"]”Œkey request service”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jj  jg  j_  j\  j¢  jŸ  jb  j_  uŒ	nametypes”}”(jj  ‰j_  ‰j¢  ‰jb  ‰uh}”(jg  h£j\  j¿  jŸ  jb  j_  j¥  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.