.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. .\" Written by David Howells (dhowells@redhat.com) .\" and Copyright (C) 2016 Michael Kerrisk .\" .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) .\" This program is free software; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License .\" as published by the Free Software Foundation; either version .\" 2 of the License, or (at your option) any later version. .\" %%%LICENSE_END .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH REQUEST_KEY 2 "1 novembre 2020" Linux "Gestion des clés sous Linux" .SH NOM request_key \- Demander une clé au gestionnaire de clés du noyau .SH SYNOPSIS .nf \fB#include \fP \fB#include \fP .PP \fBkey_serial_t request_key(const char *\fP\fItype\fP\fB, const char *\fP\fIdescription\fP\fB,\fP \fB const char *\fP\fIcallout_info\fP\fB,\fP \fB key_serial_t \fP\fIdest_keyring\fP\fB);\fP .fi .PP Aucune enveloppe n'est fournie pour la glibc pour cet appel système\ ; voir les NOTES. .SH DESCRIPTION \fBrequest_key\fP() essaie de trouver une clé d'un \fItype\fP donné, qui correspond à la \fIdescription\fP (au nom) spécifiée. Si aucune clé n'a pu être trouvée, la clé peut être créée. Si la clé a été trouvée ou créée, \fBrequest_key\fP() la rattache au trousseau dont l'identifiant est indiqué dans \fIdest_keyring\fP et il renvoie le numéro de série de la clé. .PP \fBrequest_key\fP() cherche une clé correspondant aux critères d'abord récursivement à l'intérieur des trousseaux attachés au processus appelant, dans l'ordre suivant\ : trousseau spécifique au thread, trousseau spécifique au processus, et enfin le trousseau de session. .PP .\" David Howells: we can then have an arbitrarily long sequence .\" of "recursive" request-key upcalls. There is no limit, other .\" than number of PIDs, etc. Si \fBrequest_key\fP() est appelé depuis un programme lui\-même appelé par \fBrequest_key\fP() au nom d'un autre processus afin de générer une clé, alors les trousseaux de cet autre processus seront ensuite parcourus en utilisant les identifiants d’utilisateur, de groupe, du groupe supplémentaire et le contexte de sécurité de ce processus. .PP La recherche dans l'arborescence d'un trousseau est de type parcours en largeur\ : une correspondance est d'abord recherchée avec toutes les clés d'un trousseau avant de chercher dans les trousseaux trouvés dans ce trousseau. Seules les clés et seuls les trousseaux pour lesquels le processus a l'autorisation \fIsearch\fP peuvent être examinés. .PP Si aucune clé n'est trouvée et si \fIcallout\fP est NULL, l'appel échoue avec l'erreur \fBENOKEY\fP. .PP Si aucune clé n'est trouvée et si \fIcallout\fP n'est pas NULL, le noyau essaie d'appeler un programme de l'espace utilisateur pour instancier la clé. Les détails sont donnés ci\-dessous. .PP Le numéro de série \fIdest_keyring\fP peut être celui d'un trousseau valable sur lequel l'appelant possède les droits en écriture ou il peut s'agir d'un des identifiants de trousseau spécial suivants\ : .TP \fBKEY_SPEC_THREAD_KEYRING\fP Cela indique le trousseau spécifique au thread de l'appelant (voir \fBthread\-keyring\fP(7)). .TP \fBKEY_SPEC_PROCESS_KEYRING\fP Cela indique le trousseau spécifique au processus de l'appelant (voir \fBprocess\-keyring\fP(7)). .TP \fBKEY_SPEC_SESSION_KEYRING\fP Cela indique le trousseau spécifique à la session de l'appelant (voir \fBsession\-keyring\fP(7)). .TP \fBKEY_SPEC_USER_KEYRING\fP Cela indique le trousseau spécifique à l'UID de l'appelant (voir \fBuser\-keyring\fP(7)). .TP \fBKEY_SPEC_USER_SESSION_KEYRING\fP Cela indique le trousseau spécifique à la session de l'UID de l'appelant (voir \fBuser\-session\-keyring\fP(7)). .PP Quand \fIdest_keyring\fP est indiqué comme \fB0\fP et qu'aucune construction de clé n'ait été effectuée, aucune édition de liens supplémentaire n'est effectuée. .PP Sinon, si \fIdest_keyring\fP est \fB0\fP et si une nouvelle clé est construite, la nouvelle clé sera attachée au trousseau par défaut. Plus précisément, quand le noyau essaie de déterminer le trousseau auquel rattacher la clé nouvellement créée, il essaie les trousseaux les uns à la suite des autres, en commençant par celui défini par l'opération \fBKEYCTL_SET_REQKEY_KEYRING\fP de \fBkeyctl\fP(2), puis en continuant dans l'ordre ci\-dessous jusqu'à ce qu'il trouve le premier trousseau existant\ : .IP " \(bu" 3 .\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 .\" FIXME .\" Actually, is the preceding point correct? .\" If I understand correctly, we'll only get here if .\" 'dest_keyring' is zero, in which case KEY_REQKEY_DEFL_REQUESTOR_KEYRING .\" won't refer to a keyring. Have I misunderstood? Le trousseau du demandeur (\fBKEY_REQKEY_DEFL_REQUESTOR_KEYRING\fP depuis Linux 2.6.29). .IP " \(bu" Le trousseau spécifique au thread (\fBKEY_REQKEY_DEFL_THREAD_KEYRING\fP\ ; voir \fBthread\-keyring\fP(7)). .IP " \(bu" Le trousseau spécifique au processus (\fBKEY_REQKEY_DEFL_PROCESS_KEYRING\fP\ ; voir \fBprocess\-keyring\fP(7)). .IP " \(bu" Le trousseau spécifique à la session (\fBKEY_REQKEY_DEFL_SESSION_KEYRING\fP\ ; voir \fBsession\-keyring\fP(7)). .IP " \(bu" Le trousseau de la session associé à l'identifiant utilisateur du processus (\fBKEY_REQKEY_DEFL_USER_SESSION_KEYRING\fP\ ; voir \fBuser\-session\-keyring\fP(7)). Ce trousseau est censé toujours exister. .IP " \(bu" .\" mtk: Are there circumstances where the user sessions and UID-specific .\" keyrings do not exist? .\" .\" David Howells: .\" The uid keyrings don't exist until someone tries to access them - .\" at which point they're both created. When you log in, pam_keyinit .\" creates a link to your user keyring in the session keyring it just .\" created, thereby creating the user and user-session keyrings. .\" .\" and David elaborated that "access" means: .\" .\" It means lookup_user_key() was passed KEY_LOOKUP_CREATE. So: .\" .\" add_key() - destination keyring .\" request_key() - destination keyring .\" KEYCTL_GET_KEYRING_ID - if create arg is true .\" KEYCTL_CLEAR .\" KEYCTL_LINK - both args .\" KEYCTL_SEARCH - destination keyring .\" KEYCTL_CHOWN .\" KEYCTL_SETPERM .\" KEYCTL_SET_TIMEOUT .\" KEYCTL_INSTANTIATE - destination keyring .\" KEYCTL_INSTANTIATE_IOV - destination keyring .\" KEYCTL_NEGATE - destination keyring .\" KEYCTL_REJECT - destination keyring .\" KEYCTL_GET_PERSISTENT - destination keyring .\" .\" will all create a keyring under some circumstances. Whereas the rest, .\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't. Le trousseau spécifique à l'identifiant utilisateur (\fBKEY_REQKEY_DEFL_USER_KEYRING\fP\ ; voir \fBuser\-keyring\fP(7)). Ce trousseau est toujours censé exister. .PP .\" Si l'opération \fBKEYCTL_SET_REQKEY_KEYRING\fP de \fBkeyctl\fP(2) indique \fBKEY_REQKEY_DEFL_DEFAULT\fP (ou si aucune opération \fBKEYCTL_SET_REQKEY_KEYRING\fP n'est effectuée), le noyau cherche un trousseau à partir du début de la liste. .SS "Demander l'instanciation d'une clé dans l'espace utilisateur" Si le noyau ne peut pas trouver de clé correspondant à \fItype\fP et à \fIdescription\fP et si \fIcallout\fP n'est pas NULL, le noyau essaie d'appeler un programme de l'espace utilisateur pour instancier une clé au \fItype\fP et à la \fIdescription\fP donnés. Dans ce cas, les étapes suivantes sont suivies\ : .IP a) 4 Le noyau crée une clé non instanciée, U, du \fItype\fP et de la \fIdescription\fP demandés. .IP b) .\" struct request_key_auth, defined in security/keys/internal.h Le noyau crée une clé d'autorisation, V, qui se rapporte à la clé U, et enregistre les faits que l'appelant de \fBrequest_key\fP() est\ : .RS .IP (1) 4 le contexte dans lequel la clé U doit être instanciée et sécurisée et .IP (2) le contexte à partir duquel les requêtes associées à la clé peuvent être honorées. .RE .IP La clé d'autorisation est construite comme suit\ : .RS .IP * 3 Le type de clé est \fI«\ .request_key_auth\ »\fP. .IP * Les identifiants utilisateur et de groupe de la clé sont les mêmes que ceux du système de fichiers correspondant du processus à l'origine de la demande. .IP * La clé accorde le droit de \fIvisibilité\fP, \fIlecture\fP et de \fIrecherche\fP au détenteur de la clé ainsi que celui de \fIvisibilité\fP à l'utilisateur de la clé. .IP * La description (son nom) de la clé est la chaîne hexadécimale représentant l'identifiant de la clé à instancier dans le programme à l'origine de la demande. .IP * La charge utile de la clé est récupérée à partir des données indiquées dans \fIcallout_info\fP. .IP * En interne, le noyau enregistre aussi l'identifiant de processus de la \fBrequest_key\fP() appelée. .RE .IP c) .\" The request\-key(8) program can be invoked in circumstances *other* than .\" when triggered by request_key(2). For example, upcalls from places such .\" as the DNS resolver. Le noyau crée un processus qui exécute un service de l'espace utilisateur tel que \fBrequest\-key\fP(8) avec un nouveau trousseau de session contenant un lien vers la clé d'autorisation, V. .IP Ce programme est fourni avec les options suivantes en ligne de commande\ : .RS .IP [0] 4 La chaîne \fI«\ /sbin/request\-key\ »\fP. .IP [1] \fI«\ create\ »\fP (indiquant qu'une clé doit être créée). .IP [2] L'identifiant de la clé à instancier. .IP [3] L'identifiant utilisateur du système de fichiers de l'appelant de \fBrequest_key\fP(). .IP [4] L'identifiant de groupe du système de fichiers de l'appelant de \fBrequest_key\fP(). .IP [5] L'identifiant du trousseau du thread de l’appelant de \fBrequest_key\fP(). Il peut être zéro si le trousseau n'a pas été créé. .IP [6] L'identifiant du trousseau du processus de l'appelant de \fBrequest_key\fP(). Il peut être zéro si le trousseau n'a pas été créé. .IP [7] L'identifiant du trousseau de session de l'appelant de \fBrequest_key\fP(). .RE .IP \fINote\fP\ : chacune des options de la ligne de commande étant un identifiant de clé est encodé en \fIdécimal\fP (contrairement aux identifiants de clé affichés dans \fI/proc/keys\fP, affichés en valeurs hexadécimales). .IP d) Le programme généré dans l'étape précédente\ : .RS .IP * 3 Assume l'autorité pour instancier la clé U en utilisant l'opération \fBKEYCTL_ASSUME_AUTHORITY\fP de \fBkeyctl\fP(2) (généralement à l'aide de la fonction \fBkeyctl_assume_authority\fP(3)). .IP * Obtient les données de l'appel à partir de la charge utile de la clé d'autorisation V (en utilisant l'opération \fBKEYCTL_READ\fP de \fBkeyctl\fP(2) (ou plus généralement, la fonction \fBkeyctl_read\fP(3)) avec une valeur d'identifiant de clé de \fBKEY_SPEC_REQKEY_AUTH_KEY\fP). .IP * .\" Should an instantiating program be using KEY_SPEC_REQUESTOR_KEYRING? .\" I couldn't find a use in the keyutils git repo. .\" According to David Howells: .\" * This feature is provided, but not used at the moment. .\" * A key added to that ring is then owned by the requester Instancie la clé (ou exécute un autre programme pour faire cette tâche), en indiquant la charge utile et le trousseau de destination (on peut accéder à celui indiqué par le demandeur lors de l'appel \fBrequest_key\fP() en utilisant l'identifiant de clé spécial \fBKEY_SPEC_REQUESTOR_KEYRING\fP). L'instanciation est effectuée en utilisant l'opération \fBKEYCTL_INSTANTIATE\fP de \fBkeyctl\fP(2) (ou plus généralement, la fonction \fBkeyctl_instantiate\fP(3)). À ce moment, l'appel \fBrequest_key\fP() se termine et le programme à l'origine de la demande peut continuer son exécution. .RE .PP Si ces étapes ne réussissent pas, une erreur \fBENOKEY\fP sera renvoyée à l'appelant de \fBrequest_key\fP() et une clé temporaire et instanciée de manière négative sera installée sur le trousseau indiqué par \fIdest_keyring\fP. Elle expirera après quelques secondes mais elle permettra aux appels suivants à \fBrequest_key\fP() d'échouer jusqu'à ce qu'elles réussissent. Le but de cette clé instanciée négativement est d'empêcher des processus (potentiellement différents) d'effectuer des demandes répétées (qui requièrent des appels \fBrequest\-key\fP(8) coûteux) pour une clé qui ne peut pas être instanciée positivement (pour l'instant). .PP Une fois que la clé a été instanciée, la clé d'autorisation (\fBKEY_SPEC_REQKEY_AUTH_KEY\fP) est révoquée et le trousseau de destination (\fBKEY_SPEC_REQUESTOR_KEYRING\fP) n'est plus accessible au programme \fBrequest\-key\fP(8). .PP Si une clé est créée, qu'elle soit valable ou instanciée négativement, elle remplacera toute autre clé possédant le même type et la même description dans le trousseau indiqué dans \fIdest_keyring\fP. .SH "VALEUR RENVOYÉE" En cas de succès, \fBrequest_key\fP() renvoie le numéro de série de la clé trouvée ou créée. En cas d'erreur, la valeur \fB\-1\fP est renvoyée et \fIerrno\fP est positionné pour indiquer la cause de l'erreur. .SH ERREURS .TP \fBEACCES\fP Le trousseau n'était pas disponible pour pouvoir être modifié par l'utilisateur. .TP \fBEDQUOT\fP Le quota de clés de cet utilisateur serait dépassé si la clé était créée ou ajoutée au trousseau. .TP \fBEFAULT\fP Le \fItype\fP, la \fIdescription\fP ou la \fIcallout_info\fP pointe en dehors de l'espace d'adressage accessible au processus. .TP \fBEINTR\fP La requête a été interrompue par un signal\ ; voir \fBsignal\fP(7). .TP \fBEINVAL\fP La taille de la clé (octet NULL final inclus) indiquée dans \fItype\fP ou \fIdescription\fP dépassait la limite (respectivement 32 et 4096 octets). .TP \fBEINVAL\fP La taille de la clé (octet NULL final inclus) indiquée dans \fIcallout_info\fP dépassait la taille de la page du système. .TP \fBEKEYEXPIRED\fP Une clé expirée a été trouvée, mais aucun remplacement n'a pu être obtenu. .TP \fBEKEYREJECTED\fP La tentative de générer une nouvelle clé a été rejetée. .TP \fBEKEYREVOKED\fP Une clé révoquée a été trouvée, mais aucun remplacement n'a pu être obtenu. .TP \fBENOKEY\fP Aucune clé correspondante n'a été trouvée. .TP \fBENOMEM\fP Il n'y a pas assez de mémoire pour créer une clé. .TP \fBEPERM\fP Le paramètre \fItype\fP commençait par un point (\(aq.\(aq). .SH VERSIONS .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a Cet appel système est apparu pour la première fois dans Linux 2.6.10. La possibilité d'instancier des clés à la demande a été ajoutée dans Linux 2.6.13. .SH CONFORMITÉ Cet appel système est une extension Linux non standard. .SH NOTES Aucune enveloppe n'est fournie par la glibc pour cet appel système. Une enveloppe est fournie dans le paquet \fIlibkeyutils\fP. Si vous utilisez l'enveloppe de cette bibliothèque, éditez un lien avec \fI\-lkeyutils\fP. .SH EXEMPLES Le programme ci\-dessous montre l'utilisation de \fBrequest_key\fP(). Les paramètres \fItype\fP, \fIdescription\fP et \fIcallout_info\fP pour l'appel système sont récupérés à partir des valeurs fournies dans les options de la ligne de commande. L'appel indique le trousseau de session en tant que trousseau cible. .PP Pour montrer ce programme, on crée d'abord une entrée adéquate dans \fI/etc/request\-key.conf\fP. .PP .in +4n .EX $ sudo sh # \fBecho \(aqcréation utilisateur mtk:* * /bin/keyctl instantiate %k %c %S\(aq \e\fP \fB> /etc/request\-key.conf\fP # \fBexit\fP .EE .in .PP Cette entrée indique que lorsqu'une nouvelle clé «\ utilisateur\ » avec le préfixe «\ mtk:\ » doit être instanciée, la tâche doit être effectuée par l'opération \fBinstantiate\fP de la commande \fBkeyctl\fP(1). Les paramètres fournis à l'opération \fBinstantiate\fP sont\ : l'identifiant de la clé non instanciée (\fI%k\fP), les données de l'appel fournies à l'appel \fBrequest_key\fP() (\fI%c\fP) et le trousseau de session (\fI%S\fP) du demandeur (à savoir l'appelant de \fBrequest_key\fP()). Consulter \fBrequest\-key.conf\fP(5) pour les détails de ces spécificateurs \fI%\fP. .PP Puis on lance le programme et on vérifie que le contenu de \fI/proc/keys\fP pour vérifier que la clé demandée a été instanciée\ : .PP .in +4n .EX $ \fB./t_request_key user mtk:key1 "Payload data"\fP $ \fBgrep \(aq2dddaf50\(aq /proc/keys\fP 2dddaf50 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mtk:key1: 12 .EE .in .PP Pour un autre exemple d'utilisation de ce programme, voir \fBkeyctl\fP(2). .SS "Source du programme" \& .EX /* t_request_key.c */ #include #include #include #include #include #include int main(int argc, char *argv[]) { key_serial_t key; if (argc != 4) { fprintf(stderr, "Utilisation\ : %s type description données\-appel\en", 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 clé est %jx\en", (uintmax_t) key); exit(EXIT_SUCCESS); } .EE .SH "VOIR AUSSI" .ad l .nh \fBkeyctl\fP(1), \fBadd_key\fP(2), \fBkeyctl\fP(2), \fBkeyctl\fP(3), \fBcapabilities\fP(7), \fBkeyrings\fP(7), \fBkeyutils\fP(7), \fBpersistent\-keyring\fP(7), \fBprocess\-keyring\fP(7), \fBsession\-keyring\fP(7), \fBthread\-keyring\fP(7), \fBuser\-keyring\fP(7), \fBuser\-session\-keyring\fP(7), \fBrequest\-key\fP(8) .PP .\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 .\" commit 3db38ed76890565772fcca3279cc8d454ea6176b Les fichiers \fIDocumentation/security/keys/core.rst\fP et \fIDocumentation/keys/request\-key.rst\fP des sources du noyau (ou, avant Linux 4.13, les fichiers \fIDocumentation/security/keys.txt\fP et \fIDocumentation/security/keys\-request\-key.txt\fP). .SH COLOPHON Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à l'adresse \%https://www.kernel.org/doc/man\-pages/. .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier , David Prévot et Jean-Philippe MENGUAL . Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à .MT debian-l10n-french@lists.debian.org .ME .