request_key(2) System Calls Manual request_key(2) NOM request_key - Demander une cle au gestionnaire de cles du noyau BIBLIOTHEQUE Utilitaires de gestion de clefs Linux (libkeyutils, -lkeyutils) SYNOPSIS #include key_serial_t request_key(const char *type, const char *description, const char *_Nullable callout_info, key_serial_t dest_keyring); DESCRIPTION request_key() essaie de trouver une cle d'un type donne, qui correspond a la description (au nom) specifiee. Si aucune cle n'a pu etre trouvee, la cle peut etre creee. Si la cle a ete trouvee ou creee, request_key() la rattache au trousseau dont l'identifiant est indique dans dest_keyring et il renvoie le numero de serie de la cle. request_key() cherche une cle correspondant aux criteres d'abord recursivement a l'interieur des trousseaux attaches au processus appelant, dans l'ordre suivant : trousseau specifique au thread, trousseau specifique au processus, et enfin le trousseau de session. Si request_key() est appele depuis un programme lui-meme appele par request_key() au nom d'un autre processus afin de generer une cle, alors les trousseaux de cet autre processus seront ensuite parcourus en utilisant les identifiants d'utilisateur, de groupe, du groupe supplementaire et le contexte de securite de ce processus. La recherche dans l'arborescence d'un trousseau est de type parcours en largeur : une correspondance est d'abord recherchee avec toutes les cles d'un trousseau avant de chercher dans les trousseaux trouves dans ce trousseau. Seules les cles et seuls les trousseaux pour lesquels le processus a l'autorisation search peuvent etre examines. Si aucune cle n'est trouvee et si callout est NULL, l'appel echoue avec l'erreur ENOKEY. Si aucune cle n'est trouvee et si callout n'est pas NULL, le noyau essaie d'appeler un programme de l'espace utilisateur pour instancier la cle. Les details sont donnes ci-dessous. Le numero de serie dest_keyring peut etre celui d'un trousseau valable sur lequel l'appelant possede les droits en ecriture ou il peut s'agir d'un des identifiants de trousseau special suivants : KEY_SPEC_THREAD_KEYRING Cela indique le trousseau specifique au thread de l'appelant (voir thread-keyring(7)). KEY_SPEC_PROCESS_KEYRING Cela indique le trousseau specifique au processus de l'appelant (voir process-keyring(7)). KEY_SPEC_SESSION_KEYRING Cela indique le trousseau specifique a la session de l'appelant (voir session-keyring(7)). KEY_SPEC_USER_KEYRING Cela indique le trousseau specifique a l'UID de l'appelant (voir user-keyring(7)). KEY_SPEC_USER_SESSION_KEYRING Cela indique le trousseau specifique a la session de l'UID de l'appelant (voir user-session-keyring(7)). Quand dest_keyring est indique comme 0 et qu'aucune construction de cle n'ait ete effectuee, aucune edition de liens supplementaire n'est effectuee. Sinon, si dest_keyring est 0 et si une nouvelle cle est construite, la nouvelle cle sera attachee au trousseau par defaut. Plus precisement, quand le noyau essaie de determiner le trousseau auquel rattacher la cle nouvellement creee, il essaie les trousseaux les uns a la suite des autres, en commencant par celui defini par l'operation KEYCTL_SET_REQKEY_KEYRING de keyctl(2), puis en continuant dans l'ordre ci-dessous jusqu'a ce qu'il trouve le premier trousseau existant : - Le trousseau du demandeur (KEY_REQKEY_DEFL_REQUESTOR_KEYRING depuis Linux 2.6.29). - Le trousseau specifique au thread (KEY_REQKEY_DEFL_THREAD_KEYRING ; voir thread-keyring(7)). - Le trousseau specifique au processus (KEY_REQKEY_DEFL_PROCESS_KEYRING ; voir process-keyring(7)). - Le trousseau specifique a la session (KEY_REQKEY_DEFL_SESSION_KEYRING ; voir session-keyring(7)). - Le trousseau de la session associe a l'identifiant utilisateur du processus (KEY_REQKEY_DEFL_USER_SESSION_KEYRING ; voir user-session-keyring(7)). Ce trousseau est cense toujours exister. - Le trousseau specifique a l'identifiant utilisateur (KEY_REQKEY_DEFL_USER_KEYRING ; voir user-keyring(7)). Ce trousseau est toujours cense exister. Si l'operation KEYCTL_SET_REQKEY_KEYRING de keyctl(2) indique KEY_REQKEY_DEFL_DEFAULT (ou si aucune operation KEYCTL_SET_REQKEY_KEYRING n'est effectuee), le noyau cherche un trousseau a partir du debut de la liste. Demander l'instanciation d'une cle dans l'espace utilisateur Si le noyau ne peut pas trouver de cle correspondant a type et a description et si callout n'est pas NULL, le noyau essaie d'appeler un programme de l'espace utilisateur pour instancier une cle au type et a la description donnes. Dans ce cas, les etapes suivantes sont suivies : (1) Le noyau cree une cle non instanciee, U, du type et de la description demandes. (2) Le noyau cree une cle d'autorisation, V, qui se rapporte a la cle U, et enregistre les faits que l'appelant de request_key() est : (2.1) le contexte dans lequel la cle U doit etre instanciee et securisee et (2.2) le contexte a partir duquel les requetes associees a la cle peuvent etre honorees. La cle d'autorisation est construite comme suit : - Le type de cle est << .request_key_auth >>. - Les identifiants utilisateur et de groupe de la cle sont les memes que ceux du systeme de fichiers correspondant du processus a l'origine de la demande. - La cle accorde le droit de visibilite, lecture et de recherche au detenteur de la cle ainsi que celui de visibilite a l'utilisateur de la cle. - La description (son nom) de la cle est la chaine hexadecimale representant l'identifiant de la cle a instancier dans le programme a l'origine de la demande. - La charge utile de la cle est recuperee a partir des donnees indiquees dans callout_info. - En interne, le noyau enregistre aussi l'identifiant de processus de la request_key() appelee. (3) Le noyau cree un processus qui execute un service de l'espace utilisateur tel que request-key(8) avec un nouveau trousseau de session contenant un lien vers la cle d'autorisation, V. Ce programme est fourni avec les options suivantes en ligne de commande : [0] La chaine << /sbin/request-key >>. [1] << create >> (indiquant qu'une cle doit etre creee). [2] L'identifiant de la cle a instancier. [3] L'identifiant utilisateur du systeme de fichiers de l'appelant de request_key(). [4] L'identifiant de groupe du systeme de fichiers de l'appelant de request_key(). [5] L'identifiant du trousseau du thread de l'appelant de request_key(). Il peut etre zero si le trousseau n'a pas ete cree. [6] L'identifiant du trousseau du processus de l'appelant de request_key(). Il peut etre zero si le trousseau n'a pas ete cree. [7] L'identifiant du trousseau de session de l'appelant de request_key(). Note : chacune des options de la ligne de commande etant un identifiant de cle est encode en decimal (contrairement aux identifiants de cle affiches dans /proc/keys, affiches en valeurs hexadecimales). (4) Le programme genere dans l'etape precedente : - Assume l'autorite pour instancier la cle U en utilisant l'operation KEYCTL_ASSUME_AUTHORITY de keyctl(2) (generalement a l'aide de la fonction keyctl_assume_authority(3)). - Obtient les donnees de l'appel a partir de la charge utile de la cle d'autorisation V (en utilisant l'operation KEYCTL_READ de keyctl(2) (ou plus generalement, la fonction keyctl_read(3)) avec une valeur d'identifiant de cle de KEY_SPEC_REQKEY_AUTH_KEY). - Instancie la cle (ou execute un autre programme pour faire cette tache), en indiquant la charge utile et le trousseau de destination (on peut acceder a celui indique par le demandeur lors de l'appel request_key() en utilisant l'identifiant de cle special KEY_SPEC_REQUESTOR_KEYRING). L'instanciation est effectuee en utilisant l'operation KEYCTL_INSTANTIATE de keyctl(2) (ou plus generalement, la fonction keyctl_instantiate(3)). A ce moment, l'appel request_key() se termine et le programme a l'origine de la demande peut continuer son execution. Si ces etapes ne reussissent pas, une erreur ENOKEY sera renvoyee a l'appelant de request_key() et une cle temporaire et instanciee de maniere negative sera installee sur le trousseau indique par dest_keyring. Elle expirera apres quelques secondes mais elle permettra aux appels suivants a request_key() d'echouer jusqu'a ce qu'elles reussissent. Le but de cette cle instanciee negativement est d'empecher des processus (potentiellement differents) d'effectuer des demandes repetees (qui requierent des appels request-key(8) couteux) pour une cle qui ne peut pas etre instanciee positivement (pour l'instant). Une fois que la cle a ete instanciee, la cle d'autorisation (KEY_SPEC_REQKEY_AUTH_KEY) est revoquee et le trousseau de destination (KEY_SPEC_REQUESTOR_KEYRING) n'est plus accessible au programme request-key(8). Si une cle est creee, qu'elle soit valable ou instanciee negativement, elle remplacera toute autre cle possedant le meme type et la meme description dans le trousseau indique dans dest_keyring. VALEUR RENVOYEE En cas de succes, request_key() renvoie le numero de serie de la cle trouvee ou creee. En cas d'erreur, la valeur -1 est renvoyee et errno est positionne pour indiquer l'erreur. ERREURS EACCES Le trousseau n'etait pas disponible pour pouvoir etre modifie par l'utilisateur. EDQUOT Le quota de cles de cet utilisateur serait depasse si la cle etait creee ou ajoutee au trousseau. EFAULT Le type, la description ou la callout_info pointe en dehors de l'espace d'adressage accessible au processus. EINTR La requete a ete interrompue par un signal ; voir signal(7). EINVAL La longueur de la chaine (y compris l'octet NULL final) specifie dans type ou description a depasse la limite (respectivement 32 et 4096 octets). EINVAL La taille de la cle (octet NULL final inclus) indiquee dans callout_info depassait la taille de la page du systeme. EKEYEXPIRED Une cle expiree a ete trouvee, mais aucun remplacement n'a pu etre obtenu. EKEYREJECTED La tentative de generer une nouvelle cle a ete rejetee. EKEYREVOKED Une cle revoquee a ete trouvee, mais aucun remplacement n'a pu etre obtenu. ENOKEY Aucune cle correspondante n'a ete trouvee. ENOMEM Il n'y a pas assez de memoire pour creer une cle. EPERM Le parametre type commencait par un point ('.'). STANDARDS Linux. HISTORIQUE Linux 2.6.10. La possibilite d'instancier des cles a la demande a ete ajoutee dans Linux 2.6.13. EXEMPLES Le programme ci-dessous montre l'utilisation de request_key(). Les parametres type, description et callout_info pour l'appel systeme sont recuperes a partir des valeurs fournies dans les options de la ligne de commande. L'appel indique le trousseau de session en tant que trousseau cible. Pour montrer ce programme, on cree d'abord une entree adequate dans /etc/request-key.conf. $ sudo sh # echo 'creation utilisateur mtk:* * /bin/keyctl instantiate %k %c %S' \ > /etc/request-key.conf # exit Cette entree indique que lorsqu'une nouvelle cle << utilisateur >> avec le prefixe << mtk: >> doit etre instanciee, la tache doit etre effectuee par l'operation instantiate de la commande keyctl(1). Les parametres fournis a l'operation instantiate sont : l'identifiant de la cle non instanciee (%k), les donnees de l'appel fournies a l'appel request_key() (%c) et le trousseau de session (%S) du demandeur (a savoir l'appelant de request_key()). Consulter request-key.conf(5) pour les details de ces specificateurs %. Puis on lance le programme et on verifie que le contenu de /proc/keys pour verifier que la cle demandee a ete instanciee : $ ./t_request_key user mtk:key1 "Payload data" $ grep '2dddaf50' /proc/keys 2dddaf50 I--Q--- 1 perm 3f010000 1000 1000 user mtk:key1: 12 Pour un autre exemple d'utilisation de ce programme, voir keyctl(2). Source du programme /* t_request_key.c */ #include #include #include #include int main(int argc, char *argv[]) { key_serial_t key; if (argc != 4) { fprintf(stderr, "Utilisation : %s type description donnees-appel\n", argv[0]); exit(EXIT_FAILURE); } key = request_key(argv[1], argv[2], argv[3], KEY_SPEC_SESSION_KEYRING); if (key == -1) { perror("request_key"); exit(EXIT_FAILURE); } printf("L'identifiant de la cle est %jx\n", (uintmax_t) key); exit(EXIT_SUCCESS); } VOIR AUSSI keyctl(1), add_key(2), keyctl(2), keyctl(3), capabilities(7), keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user-session-keyring(7), request-key(8) Les fichiers Documentation/security/keys/core.rst et Documentation/keys/request-key.rst des sources du noyau (ou, avant Linux 4.13, Documentation/security/keys.txt et Documentation/security/keys-request-key.txt). TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Philippe MENGUAL Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 request_key(2)