keyctl(2) System Calls Manual keyctl(2) NOM keyctl - Manipuler la gestion des cles du noyau BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) Sinon, les utilitaires de gestion de clefs Linux (libkeyutils, -lkeyutils); consultez VERSIONS. SYNOPSIS #include /* Definition des constantes KEY* */ #include /* Definition des constantes SYS_* */ #include long syscall(SYS_keyctl, int operation, unsigned long arg2, unsigned long arg3, unsigned long arg4, unsigned long arg5); Note : la glibc ne fournit pas d'enveloppe pour keyctl(), necessitant l'utilisation de syscall(2). DESCRIPTION keyctl() permet aux programmes de l'espace utilisateur de manipuler des cles. L'operation qu'effectue keyctl() depend de la valeur du parametre operation. Chacune de ces operations fait partie de l'enveloppe de la bibliotheque libkeyutils (fournie par le paquet keyutils) en tant que fonctions individuelles (indiquees ci-dessous) pour permettre au compilateur de verifier les types. Les valeurs autorisees pour operation sont : KEYCTL_GET_KEYRING_ID (depuis Linux 2.6.10) Associer l'identifiant d'une cle speciale a celui d'une cle reelle pour ce processus. Cette operation recherche la cle speciale dont l'identifiant est fourni dans arg2 (transmis a key_serial_t). Si la cle speciale est trouvee, l'identifiant de la cle reelle correspondante est renvoye en tant que resultat de la fonction. Les valeurs suivantes peuvent etre indiquees dans arg2 : KEY_SPEC_THREAD_KEYRING Pour indiquer le trousseau specifique au thread du thread appelant. Voir thread-keyring(7). KEY_SPEC_PROCESS_KEYRING Pour indiquer le trousseau specifique au processus de l'appelant. Voir process-keyring(7). KEY_SPEC_SESSION_KEYRING Pour indiquer le trousseau specifique a la session de l'appelant. Voir session-keyring(7). KEY_SPEC_USER_KEYRING Pour indiquer le trousseau specifique a l'UID de l'appelant. Voir user-keyring(7). KEY_SPEC_USER_SESSION_KEYRING Pour indiquer le trousseau specifique a la session de l'UID de l'appelant. Voir user-session-keyring(7). KEY_SPEC_REQKEY_AUTH_KEY (depuis Linux 2.6.16) Cela indique la cle d'autorisation creee par request_key(2) et passee au processus qu'il produit pour generer une cle. Cette cle n'est disponible que dans un programme a la maniere de request-key(8) ou une cle d'autorisation a ete passee par le noyau et cesse d'etre disponible lorsque la cle demandee a ete instanciee ; voir request_key(2). KEY_SPEC_REQUESTOR_KEYRING (depuis Linux 2.6.29) Cela indique l'identifiant de la cle pour le trousseau de destination request_key(2). Ce trousseau n'est disponible que dans un programme dans le style de request-key(8) ou une cle d'autorisation a ete passee par le noyau et cesse d'etre disponible une fois que la cle demandee a ete instanciee ; voir request_key(2). Si la cle indiquee dans arg2 n'existe pas, le comportement depend de la valeur de arg3 (diffusee dans int). Si arg3 contient une valeur non nulle -- et s'il est utile de le faire (comme pour rechercher un utilisateur, une session utilisateur ou une cle de session) --, une nouvelle cle est creee et son identifiant de cle reelle est renvoye en tant que resultat de la fonction. Sinon, l'operation echoue avec l'erreur ENOKEY. Si un identifiant de cle valable est indique dans arg2 et si la cle existe, cette operation renvoie simplement l'identifiant de la cle. Si la cle n'existe pas, l'appel echoue avec l'erreur ENOKEY. L'appelant doit avoir le droit search sur un trousseau pour qu'il soit trouvable. Les parametres arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_get_keyring_ID(3). KEYCTL_JOIN_SESSION_KEYRING (depuis Linux 2.6.10) Remplacer le trousseau de la session a laquelle le processus est rattache par un nouveau trousseau de session. Si arg2 vaut NULL, un trousseau anonyme dont la description est << _ses >> est cree et le processus est inscrit a ce trousseau en tant que trousseau de sa session, remplacant le trousseau de la session precedente. Sinon, arg2 (diffuse dans char *) est traite comme la description (le nom) d'un trousseau et le comportement est ainsi : - Si un trousseau ayant une description correspondante existe, le processus tentera de s'inscrire a ce trousseau en tant que trousseau de session si c'est possible ; sans quoi une erreur est renvoyee. Pour s'inscrire au trousseau, l'appelant doit avoir le droit search sur le trousseau. - Si un trousseau avec une description correspondante n'existe pas, un nouveau trousseau ayant la description indiquee est cree et le processus est inscrit a ce trousseau en tant que trousseau de session. Les parametres arg3, arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils par la fonction keyctl_join_session_keyring(3). KEYCTL_UPDATE (depuis Linux 2.6.10) Mettre a jour la charge utile des donnees d'une cle. Le parametre arg2 (diffuse sur key_serial_t) indique l'identifiant de la cle a mettre a jour. Le parametre arg3 (diffuse sur void *) pointe vers la nouvelle charge utile et arg4 (diffuse sur size_t) contient la taille de la nouvelle charge utile (en octets). L'appelant doit avoir les droits write sur la cle indiquee et le type de cle doit gerer les mises a jour. Une cle instanciee negativement (voir la description de KEYCTL_REJECT) peut etre instanciee positivement avec cette operation. Le parametre arg5 est ignore. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_update(3). KEYCTL_REVOKE (depuis Linux 2.6.10) Revoquer la cle dont l'identifiant est fourni dans arg2 (diffuse sur key_serial_t). La cle est vouee a aller a la poubelle ; elle ne sera plus trouvable et ne sera plus disponible pour de futures operations. Les futures tentatives d'utiliser la cle echoueront avec l'erreur EKEYREVOKED. L'appelant doit avoir les droits write ou setattr sur la cle. Les parametres arg3, arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_revoke(3). KEYCTL_CHOWN (depuis Linux 2.6.10) Changer le proprietaire (identifiant de l'utilisateur et du groupe) d'une cle. Le parametre arg2 (diffuse sur key_serial_t) contient l'identifiant de la cle. Le parametre arg3 (diffuse sur uid_t) contient l'identifiant du nouvel utilisateur (ou -1 s'il ne doit pas etre modifie). Le parametre arg4 (diffuse sur gid_t) contient l'identifiant du nouveau groupe (ou -1 s'il ne doit pas etre modifie). La cle doit accorder le droit setattr a l'appelant. Pour pouvoir modifier l'identifiant utilisateur ou utiliser un identifiant de groupe dont l'appelant n'est pas membre, l'appelant doit avoir la capacite CAP_SYS_ADMIN (voir capabilities(7)). Si l'identifiant utilisateur doit etre modifie, le nouvel utilisateur doit avoir un quota suffisant pour accepter la cle. La deduction du quota sera deplacee de l'ancien utilisateur vers le nouveau a condition que l'UID ait change. Le parametre arg5 est ignore. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_chown(3). KEYCTL_SETPERM (depuis Linux 2.6.10) Passer les droits de la cle dont l'identifiant est fourni dans le parametre arg2 (diffuse sur key_serial_t) a ceux fournis dans le parametre arg3 (diffuse sur key_perm_t). Si l'appelant n'a pas la capacite CAP_SYS_ADMIN, il ne peut modifier que les droits des cles qu'il possede. (Plus precisement, l'UID du systeme de fichiers de l'appelant doit correspondre a l'UID de la cle.) La cle doit accorder le droit setattr a l'appelant independamment de ses capacites. Les droits dans arg3 indiquent les masques des operations disponibles pour chacune des categories suivantes d'utilisateur : possessor (depuis Linux 2.6.14) Il s'agit des droits accordes a un processus possedant la cle (en tant qu'il est rattache a un des trousseaux du processus trouvables) ; voir keyrings(7). user Il s'agit du droit accorde a un processus dont l'identifiant utilisateur du systeme de fichiers correspond a celui de la cle. group Il s'agit du droit accorde au processus dont l'identifiant de groupe du systeme de fichiers ou un de ses identifiants de groupes supplementaires correspond a celui de la cle. other Il s'agit du droit accorde aux autres processus qui ne rentrent pas dans les categories user et group. Les categories user, group et other sont exclusives : si un processus rentre dans la categorie user, il ne recevra pas de droits dans la categorie group ; s'il rentre dans la categorie user ou group, il ne recevra aucun droit de la categorie other. La categorie possessor accorde des droits qui s'ajoutent a ceux accordes en vertu des categories user, group ou other. Chaque masque de droits pese huit bits, dont seuls six sont actuellement utilises. Les droits disponibles sont : view Droit de lire les attributs d'une cle. Ce droit est necessaire pour l'operation KEYCTL_DESCRIBE. Les bits de droit pour chaque categorie sont KEY_POS_VIEW, KEY_USR_VIEW, KEY_GRP_VIEW et KEY_OTH_VIEW. read Lire la charge utile d'une cle. Ce droit est necessaire pour l'operation KEYCTL_READ. Les bits de droit pour chaque categorie sont KEY_POS_READ, KEY_USR_READ, KEY_GRP_READ et KEY_OTH_READ. write Mettre a jour ou instancier une cle. Pour un trousseau, attacher ou detacher des cles d'un trousseau. Ce droit est necessaire pour les operations KEYCTL_UPDATE, KEYCTL_REVOKE, KEYCTL_CLEAR, KEYCTL_LINK et KEYCTL_UNLINK. Les bits des droits pour chaque categorie sont KEY_POS_WRITE, KEY_USR_WRITE, KEY_GRP_WRITE et KEY_OTH_WRITE. search Rechercher dans les trousseaux et rendre les cles trouvables. Les recherches ne peuvent parcourir des trousseaux imbriques que si les droits search y sont positionnes. Ce droit est necessaire pour les operations KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING, KEYCTL_SEARCH et KEYCTL_INVALIDATE. Les bits de droit pour chaque categorie sont KEY_POS_SEARCH, KEY_USR_SEARCH, KEY_GRP_SEARCH et KEY_OTH_SEARCH. link Rattacher une cle ou un trousseau. Ce droit est necessaire pour les operations KEYCTL_LINK et KEYCTL_SESSION_TO_PARENT. Les bits des droits pour cette categorie sont KEY_POS_LINK, KEY_USR_LINK, KEY_GRP_LINK et KEY_OTH_LINK. setattr (depuis Linux 2.6.15). Modifier un identifiant d'utilisateur, de groupe ou le masque de droits d'une cle. Ce droit est necessaire pour les operations KEYCTL_REVOKE, KEYCTL_CHOWN et KEYCTL_SETPERM. Les bits de droits pour chaque categorie sont KEY_POS_SETATTR, KEY_USR_SETATTR, KEY_GRP_SETATTR et KEY_OTH_SETATTR. Par commodite, les macros suivantes sont definies en tant que masques pour tous les bits de droits de chacune des categories de l'utilisateur : KEY_POS_ALL, KEY_USR_ALL, KEY_GRP_ALL et KEY_OTH_ALL. Les parametres arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_setperm(3). KEYCTL_DESCRIBE (depuis Linux 2.6.10) Obtenir une chaine decrivant les attributs d'une cle indiquee. L'identifiant de la cle a decrire est indique dans arg2 (diffuse sur key_serial_t). La chaine de description est renvoyee dans le tampon vers lequel pointe arg3 (diffuse sur char *) ; arg4 (diffuse sur size_t) indique la taille de ce tampon en octets. La cle doit accorder le droit view a l'appelant. La chaine renvoyee se termine par NULL et contient les informations suivantes sur la cle : type;uid;gid;perm;description Dans ce qui precede, type et description sont des chaines, uid et gid sont des chaines decimales et perm est un masque de droits hexadecimal. La chaine de description est ecrite dans le format suivant : %s;%d;%d;%08x;%s Note : l'objectif est d'etendre la chaine de description dans les futures versions du noyau. En particulier, le champ description ne contiendra pas de point-virgule ; elle doit etre analysee en partant de la fin pour chercher le dernier point-virgule. Cela permettra, a l'avenir, d'inserer des champs delimites avec des points-virgules. Une tentative d'ecrire dans le tampon n'a lieu que lorsque arg3 n'est pas NULL et quand la taille du tampon indiquee est assez grande pour accepter la chaine de description (y compris l'octet NULL final). Afin de determiner si la taille du tampon etait trop petite, verifiez que la valeur de retour de l'operation est superieure a arg4. Le parametre arg5 est ignore. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_describe(3). KEYCTL_CLEAR Vider le contenu (a savoir detacher les cles) d'un trousseau. L'identifiant de la cle (qui doit etre de type trousseau) est fourni dans arg2 (diffuse sur key_serial_t). L'appelant doit avoir le droit write sur le trousseau. Les parametres arg3, arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_clear(3). KEYCTL_LINK (depuis Linux 2.6.10) Creer un lien d'un trousseau vers une cle. La cle a rattacher est indiquee dans arg2 (diffuse sur key_serial_t) ; le trousseau est indique dans arg3 (diffuse sur key_serial_t). Si une cle du meme type et ayant la meme description se trouve deja rattachee au trousseau, elle est eliminee du trousseau. Avant de creer le rattachement, le noyau verifie la profondeur des trousseaux et renvoie les erreurs adequates si le rattachement cree une boucle ou si la profondeur des trousseaux serait trop importante (la limite de profondeur est definie par la constante KEYRING_SEARCH_MAX_DEPTH du noyau, fixee a 6, et elle est necessaire pour empecher les debordements de de la pile du noyau lors d'une recherche recursive de trousseaux). L'appelant doit avoir le droit link sur la cle a ajouter et celui write sur le trousseau. Les parametres arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_link(3). KEYCTL_UNLINK (depuis Linux 2.6.10) Supprimer une cle d'un trousseau. L'identifiant de la cle a detacher est indique dans arg2 (diffuse sur key_serial_t) ; l'identifiant du trousseau d'ou la cle doit etre detachee est indique dans arg3 (diffuse sur key_serial_t). Si la cle n'est pas rattachee au trousseau, cela produit une erreur. L'appelant doit avoir le droit write sur le trousseau d'ou doit etre detachee la cle. Si le dernier rattachement d'une cle est supprime, cette cle sera mise en destruction. Les parametres arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_unlink(3). KEYCTL_SEARCH (depuis Linux 2.6.10) Chercher une cle dans l'arborescence d'un trousseau, renvoyer son identifiant et, eventuellement, la rattacher a un trousseau indique. L'arborescence ou doit s'effectuer la recherche est indiquee en passant l'identifiant de la cle de tete a arg2 (diffuse sur key_serial_t). La recherche s'effectue en largeur et recursivement. Les parametres arg3 et arg4 indiquent la cle a rechercher : arg3 (diffuse en tant que char *) contient le type de cle (une chaine de caracteres se terminant par NULL et mesurant jusqu'a 32 octets en comptant l'octet NULL final), et arg4 (diffuse en tant que char *) contient la description de la cle (une chaine de caracteres se terminant par NULL et mesurant jusqu'a 4096 octets en comptant l'octet NULL final). Le trousseau d'origine doit autoriser l'appelant a search. Pendant la recherche recursive, seuls les trousseaux accordant le droit search a l'appelant seront explores. Seules les cles pour lesquelles l'appelant a le droit search seront trouvees. Si la cle est trouvee, son identifiant est renvoye en tant que resultat de la fonction. Si la cle est trouvee et si arg5 (diffuse sur key_serial_t) n'est pas zero, la cle est rattachee au trousseau indique dont l'identifiant est indique dans arg5, avec les memes contraintes et les memes regles que KEYCTL_LINK. Si le trousseau cible indique dans arg5 contient deja une cle rattachee du meme type et a la meme description, cet attachement sera remplace par un autre avec la cle trouvee avec cette operation. Plutot que des identifiants de trousseaux existants valables, les trousseaux d'origine (arg2) et cible (arg5) peuvent etre un des identifiants de trousseau de cles speciales indique dans KEYCTL_GET_KEYRING_ID. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_search(3). KEYCTL_READ (depuis Linux 2.6.10) Lire les donnees de la charge utile (payload) d'une cle. L'identifiant de la cle dont la charge utile va etre lue est indique dans arg2 (diffuse sur key_serial_t). Il peut s'agir de l'identifiant d'une cle existante ou un identifiant de cle speciale liste dans KEYCTL_GET_KEYRING_ID. La charge utile est mise dans le tampon vers lequel pointe arg3 (diffuse sur char *) ; la taille de ce tampon doit etre indiquee dans arg4 (diffuse sur size_t). Les donnees renvoyees seront traitees pour etre presentees en fonction du type de cle. Par exemple, un trousseau renverra un tableau d'entrees key_serial_t qui representent les identifiants de toutes les cles qui y sont rattachees. Le type de cle user renverra ses donnees telles quelles. Si un type de cle n'implemente pas cette fonction, l'operation echoue avec l'erreur EOPNOTSUPP. Si arg3 n'est pas NULL, autant de donnees que possible de la charge utile seront copiees dans le tampon. En cas de renvoi d'un succes, la valeur est toujours la taille totale des donnees de la charge utile. Pour savoir si le tampon etait de taille suffisante, verifiez que la valeur de retour est inferieure ou egale a celle fournie dans arg4. La cle doit accorder a l'appelant le droit read, ou bien lui accorder le droit search quand elle est recherchee depuis les trousseaux d'un processus (a savoir quand elle est detenue). Le parametre arg5 est ignore. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_read(3). KEYCTL_INSTANTIATE (depuis Linux 2.6.10) Instancier (positivement) une cle non instanciee avec une charge utile indiquee L'identifiant de la cle a instancier est fournie dans arg2 (diffusee sur key_serial_t). La charge utile de la cle est indiquee dans le tampon vers lequel pointe arg3 (diffuse sur void *) ; la taille de ce tampon est indiquee dans arg4 (diffusee sur size_t). La charge utile peut etre un pointeur NULL et la taille du tampon peut etre de 0 si cela est pris en charge par le type de cle (si c'est un trousseau, par exemple). L'operation peut echouer si les donnees de charge utile sont dans un mauvais format ou non valables pour toute autre raison. Si arg5 (diffuse sur key_serial_t) n'est pas zero, la cle instanciee est rattachee au trousseau dont l'identifiant a ete indique dans arg5, avec les memes contraintes et les memes regles que KEYCTL_LINK. L'appelant doit avoir la cle d'autorisation adequate, et une fois que la cle non instanciee a ete instanciee, la cle d'autorisation est revoquee. Autrement dit, cette operation n'est disponible qu'a partir d'un programme de style request-key(8). Voir request_key(2) pour une explication sur les cles non instanciees et l'instanciation de cles. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_instantiate(3). KEYCTL_NEGATE (depuis Linux 2.6.10) Instancier negativement une cle non instanciee. Cette operation est equivalente a l'appel : keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4); Le parametre arg5 est ignore. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_negate(3). KEYCTL_SET_REQKEY_KEYRING (depuis Linux 2.6.10) Definir le trousseau par defaut auquel les cles demandees implicitement seront rattachees pour ce thread et renvoyer la configuration precedente. Les requetes de cle implicites sont celles que des composants du noyau effectuent en interne, comme par exemple lors de l'ouverture de fichiers sur des systemes de fichiers AFS ou NFS. Le fait de definir un trousseau par defaut produit egalement des effets lors d'une demande de cle depuis l'espace utilisateur ; voir request_key(2) pour les details. Le parametre arg2 (diffuse sur int) doit contenir une des valeurs suivantes pour indiquer le nouveau trousseau par defaut : KEY_REQKEY_DEFL_NO_CHANGE Ne pas modifier le trousseau par defaut. Cela peut servir a rechercher le trousseau par defaut actuel (sans le modifier). KEY_REQKEY_DEFL_DEFAULT Cela selectionne le comportement par defaut qui consiste a utiliser le trousseau specifique au thread s'il y en a un, ou sinon celui specifique au processus s'il y en a un, ou bien celui specifique a la session s'il y en a un, ou sinon celui de la session specifique de l'identifiant utilisateur, ou celui specifique a l'utilisateur. KEY_REQKEY_DEFL_THREAD_KEYRING Utiliser le trousseau specifique du thread (thread-keyring(7)) en tant que nouveau trousseau par defaut. KEY_REQKEY_DEFL_PROCESS_KEYRING Utiliser le trousseau specifique au processus (process-keyring(7)) en tant que nouveau trousseau par defaut. KEY_REQKEY_DEFL_SESSION_KEYRING Utiliser le trousseau specifique a la session (session-keyring(7)) en tant que nouveau trousseau par defaut. KEY_REQKEY_DEFL_USER_KEYRING Utiliser le trousseau specifique a l'identifiant utilisateur (user-keyring(7)) en tant que nouveau trousseau par defaut. KEY_REQKEY_DEFL_USER_SESSION_KEYRING Utiliser le trousseau de la session specifique de l'identifiant utilisateur (user-session-keyring(7)) en tant que nouveau trousseau par defaut. KEY_REQKEY_DEFL_REQUESTOR_KEYRING (depuis Linux 2.6.29) Utiliser le trousseau du demandeur. Toutes les autres valeurs ne sont pas valables. Les parametres arg3, arg4 et arg5 sont ignores. Le parametre que controle cette operation est recupere par l'enfant de fork(2) et conserve durant un execve(2). Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_set_reqkey_keyring(3). KEYCTL_SET_TIMEOUT (depuis Linux 2.6.10) Definir un delai d'expiration sur une cle. L'identifiant de la cle est indique dans arg2 (diffuse sur key_serial_t). La valeur du delai, en seconde a partir de l'heure actuelle, est indiquee dans arg3 (diffuse sur unsigned int). Le delai se mesure par rapport a l'horloge en temps reel. L'indication d'une valeur de delai de 0 vide les delais existants de la cle. Le fichier /proc/keys affiche le temps restant avant l'expiration de chaque cle (il s'agit de la seule methode de recherche du temps de vie d'une cle). L'appelant doit avoir le droit setattr sur la cle ou detenir un jeton d'autorisation d'instanciation pour cette cle (voir request_key(2)). La cle et les liens vis-a-vis d'elle seront automatiquement mis a la poubelle apres le delai d'expiration. Les futurs essais d'y acceder echoueront avec l'erreur EKEYEXPIRED. Cette operation ne peut pas etre utilisee pour poser des limites a des cles revoquees, expirees ou instanciees negativement. Les parametres arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_set_timeout(3). KEYCTL_ASSUME_AUTHORITY (depuis Linux 2.6.10) Assumer (ou se debarrasser) de l'autorite pour le thread appelant pour instancier une cle. Ce parametre arg2 (diffuse sur key_serial_t) fait assumer l'autorite a un identifiant de cle autre que zero, ou retire l'autorite grace a la valeur 0. Si arg2 n'est pas zero, il indique un identifiant de cle non instanciee qui devra assumer l'autorite. Cette cle peut alors etre instanciee en utilisant KEYCTL_INSTANTIATE, KEYCTL_INSTANTIATE_IOV, KEYCTL_REJECT ou KEYCTL_NEGATE. Quand la cle a ete instanciee, le thread se voit automatiquement retirer le pouvoir d'instancier la cle. Une cle ne peut assumer une autorite que si le thread appelant a dans ses trousseaux la cle d'autorisation associee a la cle (autrement dit, l'operation KEYCTL_ASSUME_AUTHORITY n'est disponible qu'a partir d'un programme du style request-key(8) ; voir request_key(2) pour une explication sur la maniere dont cette operation est utilisee). L'appelant doit avoir le droit search sur la cle d'autorisation. Si la cle indiquee a une cle d'autorisation associee, l'identifiant de cette cle est renvoye. La cle d'autorisation peut etre lue (KEYCTL_READ) pour obtenir les informations d'appel transmises a request_key(2). Si l'identifiant fourni dans arg2 est 0, l'autorite actuellement assumee est retiree et la valeur 0 est renvoyee. Le mecanisme KEYCTL_ASSUME_AUTHORITY permet a un programme tel que requestkey(8) d'assumer l'autorite necessaire pour instancier une nouvelle cle non instanciee creee suite a un appel a request_key(2). Pour plus d'informations, voir request_key(2) et le fichier Documentation/security/keys-request-key.txt des sources du noyau. Les parametres arg3, arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_assume_authority(3). KEYCTL_GET_SECURITY (depuis Linux 2.6.26) Recuperer l'etiquette de securite LSM (Linux Security Module) de la cle indiquee. L'identifiant de la cle dont l'etiquette doit etre recuperee est indique dans arg2 (diffuse sur key_serial_t). L'etiquette de securite (qui se termine par un octet NULL) sera mis dans le tampon vers lequel pointe arg3 (diffuse sur char *) ; la taille du tampon doit etre fournie dans arg4 (diffusee sur size_t). Si arg3 est indique en tant que NULL ou si la taille du tampon indiquee dans arg4 est trop petite, toute la taille de la chaine de l'etiquette de securite (y compris l'octet NULL de fin) est renvoyee en tant que resultat de la fonction et rien n'est copie dans le tampon. L'appelant doit avoir le droit view sur la cle indiquee. La chaine de l'etiquette de securite renvoyee sera affichee sous la bonne forme sur le LSM en mode force. Par exemple, avec SELinux, elle peut ressembler a : unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 Si aucun LSM n'est en mode force, une chaine vide est placee dans le tampon. Le parametre arg5 est ignore. Cette operation est mise a disposition par libkeyutils a l'aide des fonctions keyctl_get_security(3) et keyctl_get_security_alloc(3). KEYCTL_SESSION_TO_PARENT (depuis Linux 2.6.32) Remplacer le trousseau de session auquel est enregistre le parent du processus appelant par celui du processus appelant. Le trousseau sera remplace dans le processus parent sur les prochains points de transition du parent entre l'espace noyau et l'espace utilisateur. Le trousseau doit exister et accorder le droit link a l'appelant. Le processus parent doit etre single-threaded et appartenir au meme utilisateur/groupe effectif que ce processus, et il ne doit pas etre set-user-ID ou set-group-ID. L'identifiant utilisateur du trousseau de la session existante du processus parent (s'il en existe un) et celui du trousseau de session de l'appelant doivent correspondre a celui de l'identifiant utilisateur effectif de l'appelant. Le fait que le processus parent soit touche par cette operation permet a un programme tel qu'un interpreteur de demarrer un processus enfant qui utilise cette operation pour modifier le trousseau de session de l'interpreteur (c'est ce que fait la commande new_session de keyctl(1)). Les parametres arg2, arg3, arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_session_to_parent(3). KEYCTL_REJECT (depuis Linux 2.6.39) Marquer une cle comme etant instanciee negativement et positionner une duree d'expiration sur la cle. Cette operation ajoute un supplement a l'operation KEYCTL_NEGATE ci-dessus. L'identifiant de la cle a instancier negativement est indique dans arg2 (diffuse sur key_serial_t). Le parametre arg3 (diffuse sur unsigned int) indique la duree de vie de la cle en seconde. Le parametre arg4 (diffuse sur unsigned int) indique l'erreur a renvoyer quand une recherche trouve cette cle ; generalement il s'agit de EKEYREJECTED, EKEYREVOKED ou EKEYEXPIRED. Si arg5 (diffuse sur key_serial_t) n'est pas nul, la cle instanciee negativement est rattachee au trousseau dont l'identifiant est indique dans arg5, avec les memes contraintes et les memes regles que KEYCTL_LINK. L'appelant doit avoir la cle d'autorisation adequate. Autrement dit, cette operation n'est disponible qu'a partir d'un programme dans le style request-key(8). Voir request_key(2). L'appelant doit avoir la cle d'autorisation adequate, et une fois que la cle non instanciee a ete instanciee, la cle d'autorisation est revoquee. Autrement dit, cette operation n'est disponible qu'a partir d'un programme de style request-key(8). Voir request_key(2) pour une explication sur les cles non instanciees et l'instanciation de cles. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_reject(3). KEYCTL_INSTANTIATE_IOV (depuis Linux 2.6.39) Instancier une cle non instanciee avec la charge utile indiquee a l'aide d'un vecteur de tampons. Cette operation est la meme que KEYCTL_INSTANTIATE, mais les donnees de la charge utile sont indiquees sous forme d'un tableau de structures iovec (voir iovec(3type)). Le pointeur vers le vecteur de charge utile est indique dans arg3 (diffuse en tant que const struct iovec *). Le nombre d'elements du vecteur est indique dans arg4 (diffuse en tant que unsigned int). arg2 (identifiant de cle) et arg5 (identifiant de trousseau) sont interpretes avec KEYCTL_INSTANTIATE. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_instantiate_iov(3). KEYCTL_INVALIDATE (depuis Linux 3.5) Marquer une cle comme non valable. L'identifiant de la cle a rendre non valable est indique dans arg2 (diffuse sur key_serial_t). Pour rendre une cle non valable, l'appelant doit avoir le droit search sur la cle. Cette operation marque la cle comme non valable et programme sa mise immediate a la corbeille. Le ramasse-miettes, supprime les cles non valables de tous les trousseaux et efface la cle quand son nombre de references atteint 0. Apres cette operation, cette cle sera ignoree par toutes les recherches, meme si elle n'est pas encore effacee. Les cles marquees comme non valables deviennent aussitot invisibles pour les operations de cle normales, bien qu'elle soient encore visibles dans /proc/keys (avec un drapeau << i >>) jusqu'a ce qu'elles soient totalement supprimees. Les parametres arg3, arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_invalidate(3). KEYCTL_GET_PERSISTENT (depuis Linux 3.13) Recuperer le trousseau persistant (persistent-keyring(7)) d'un utilisateur indique et le rattacher au trousseau indique. L'identifiant utilisateur est indique dans arg2 (diffuse sur uid_t). Si la valeur -1 est indiquee, l'identifiant de l'utilisateur reel de l'appelant est utilise. L'identifiant du trousseau de destination est indique dans arg3 (diffuse sur key_serial_t). L'appelant doit avoir la capacite CAP_SETUID dans son espace de noms utilisateur afin de recuperer le trousseau persistant pour un identifiant utilisateur qui ne correspond pas a l'identifiant utilisateur reel ou effectif de l'appelant. Si l'appel reussit, un lien vers le trousseau persistant est ajoute au trousseau dont l'identifiant a ete indique dans arg3. L'appelant doit avoir le droit write sur le trousseau. Le trousseau persistant sera cree par le noyau s'il n'existe pas encore. Chaque fois que l'operation KEYCTL_GET_PERSISTENT est effectuee, le trousseau persistant aura un delai d'expiration reinitialise a la valeur dans : /proc/sys/kernel/keys/persistent_keyring_expiry Lorsque le delai est atteint, le trousseau persistant sera supprime et son contenu pourra etre collecte par le ramasse-miettes. Des trousseaux persistants ont ete ajoutes dans Linux 3.13. Les parametres arg4 et arg5 sont ignores. Cette operation est mise a disposition par libkeyutils a l'aide de la fonction keyctl_get_persistent(3). KEYCTL_DH_COMPUTE (depuis Linux 4.7) Calculer la cle secrete Diffie-Hellman partagee ou la cle publique, en appliquant eventuellement une fonction de derivation de cle (KDF) au resultat. Le parametre arg2 est un pointeur vers un ensemble de parametres contenant les numeros de serie de trois cles << utilisateur >> utilises dans le calcul Diffie-Hellman, empaquetes dans une structure de la forme suivante : struct keyctl_dh_params { int32_t private; /* La cle privee locale */ int32_t prime; /* Le nombre premier, connue des deux cotes */ int32_t base; /* L'entier de base : soit un generateur partage, soit la cle publique distante */ }; Chacune des trois cles indiquees dans cette structure doit accorder le droit read a l'appelant. Les charges utiles de ces cles sont utilisees pour calculer le resultat Diffie-Hellman ainsi : base ^ private mod prime Si la base est le generateur partage, le resultat est la cle publique locale. Si la base est la cle publique distante, le resultat est le code secret partage. Le parametre arg3 (diffuse sur char *) pointe vers un tampon ou est mis le resultat du calcul. La taille de ce tampon est indiquee dans arg4 (diffuse sur size_t). Le tampon doit etre assez grand pour accueillir les donnees de sortie, sans quoi une erreur est renvoyee. Si arg4 vaut zero, le tampon n'est pas utilise et l'operation renvoie la taille minimale requise du tampon (a savoir la longueur du nombre premier). Les calculs Diffie-Hellman peuvent etre effectues dans l'espace utilisateur mais exigent une bibliotheque multiprecision d'entiers (MPI). Le deplacement de l'implementation dans le noyau donne acces a l'implementation MPI du noyau et permet d'acceder a la securisation et a l'acceleration materielle. L'ajout de la prise en charge du calcul DH a l'appel systeme keyctl() a ete considere comme convenable grace a l'utilisation de l'algorithme DH pour faire deriver les cles partagees ; cela permet aussi au type de cle de determiner l'implementation DH adequate (logicielle ou materielle). Si le parametre arg5 vaut NULL, le resultat DH lui-meme est renvoye. Sinon, (depuis Linux 4.12), il s'agit d'un pointeur vers une structure qui indique les parametres de l'operation KDF a appliquer : struct keyctl_kdf_params { char *hashname; /* Nom de l'algorithm de hachage */ char *otherinfo; /* SP800-56A OtherInfo */ __u32 otherinfolen; /* Taille des donnees otherinfo */ __u32 __spare[8]; /* Reserve */ }; Le champ hashname est une chaine se terminant par NULL qui indique un nom de hachage (disponible dans l'API de chiffrement du noyau ; la liste des hachages disponibles est plutot difficile a examiner ; veuillez vous reporter a la documentation de la << Kernel Crypto API Architecture >> pour des informations sur la maniere dont les noms de hachage sont construits, et aux sources et a la configuration de votre noyau concernant les chiffrements et les modeles de type CRYPTO_ALG_TYPE_SHASH disponibles) a appliquer au resultat DH dans l'operation KDF. Le champ otherinfo consiste dans des donnees OtherInfo comme decrit dans la section 5.8.1.2 de SP800-56A et il est specifique a l'algorithme. Ces donnees sont concatenees avec le resultat de l'operation DH et elles sont fournies comme entree de l'operation KDF. Leur taille est fournie dans le champ otherinfolen et limitee a la constante KEYCTL_KDF_MAX_OI_LEN definie dans security/keys/internal.h a la valeur 64. Le champ __spare est actuellement inusite. Il etait ignore jusqu'a Linux 4.13 (mais il est encore visible par l'utilisateur puisqu'il est copie dans le noyau) et il devrait contenir des zeros depuis Linux 4.13. L'implementation KDF se conforme a SP800-56A et a SP800-108 (le compteur KDF). Cette operation est mise a disposition par libkeyutils (a partir de libkeyutils 1.5.10 jusqu'a aujourd'hui) a l'aide de la fonction keyctl_dh_compute(3) et de keyctl_dh_compute_alloc(3). KEYCTL_RESTRICT_KEYRING (depuis Linux 4.12) Appliquer une restriction de rattachement de cle a un trousseau dont l'identifiant est fourni dans arg2 (diffuse sur key_serial_t). L'appelant doit avoir le droit setattr sur la cle. Si arg3 vaut NULL, toute tentative d'ajout au trousseau est bloquee ; sinon il contient un pointeur vers une chaine contenant le nom du type de cle et arg4 contient un pointeur vers une chaine contenant la restriction specifique au type de cle. A partir de Linux 4.12, seul le type << asymmetric >> a des restrictions definies : builtin_trusted N'autoriser que les cles signees par une cle rattachee au trousseau interne (<< .builtin_trusted_keys >>). builtin_and_secondary_trusted N'autoriser que les cles signees par une cle rattachee a un trousseau secondaire (<< .secondary_trusted_keys >>) ou, par extension, a une cle du trousseau interne, puisque le deuxieme est lie au premier. key_or_keyring:key key_or_keyring:key:chain Si key indique l'identifiant d'une cle de type << asymmetric >>, seules les cles signees par cette cle sont autorisees. Si key indique l'identifiant d'un trousseau, seules les cles signees par une cle rattachee a ce trousseau sont autorisees. Si << :chain >> est indique, les cles signees par une cle rattachee au trousseau de destination (c'est-a-dire le trousseau dont l'identifiant est indique dans le parametre arg2) sont aussi autorisees. Remarquez qu'une restriction ne peut etre configuree qu'une fois pour le trousseau indique ; une fois qu'une restriction est positionnee, elle ne peut pas etre contournee. Le parametre arg5 est ignore. VALEUR RENVOYEE Pour qu'un appel reussisse, le code de retour depend de l'operation : KEYCTL_GET_KEYRING_ID L'identifiant du trousseau demande. KEYCTL_JOIN_SESSION_KEYRING L'identifiant du trousseau de la session qu'on vient de rejoindre. KEYCTL_DESCRIBE La taille de la description (comprenant l'octet NULL de fin) independamment de la taille du tampon fournie. KEYCTL_SEARCH L'identifiant de la cle trouvee. KEYCTL_READ La quantite de donnees disponibles dans la cle, independamment de la taille du tampon fournie. KEYCTL_SET_REQKEY_KEYRING L'identifiant du trousseau par defaut precedent auquel ont ete rattachees implicitement les cles sollicitees (un parmi KEY_REQKEY_DEFL_USER_*). KEYCTL_ASSUME_AUTHORITY 0 si l'identifiant donne valait 0, ou l'identifiant de la cle d'autorisation correspondant a la cle indiquee, si un identifiant de cle autre que zero a ete fourni. KEYCTL_GET_SECURITY La taille de la chaine de l'etiquette de securite LSM (y compris l'octet NULL de fin), independamment de la taille du tampon fourni. KEYCTL_GET_PERSISTENT L'identifiant du trousseau persistant. KEYCTL_DH_COMPUTE Le nombre d'octets copies dans le tampon ou, si arg4 vaut 0, la taille du tampon necessaire. Toutes les autres operations Zero. En cas d'erreur, la valeur de retour est -1 et errno est definie pour preciser l'erreur. ERREURS EACCES L'operation demandee n'etait pas autorisee. EAGAIN operation etait KEYCTL_DH_COMPUTE et une erreur s'est produite lors de l'initialisation du module de chiffrement. EDEADLK operation etait KEYCTL_LINK et le rattachement demande conduirait a une boucle. EDEADLK operation etait KEYCTL_RESTRICT_KEYRING et la restriction de trousseau demandee aboutirait a une boucle. EDQUOT Le quota de cles de l'utilisateur appelant serait depasse si la cle etait creee ou ajoutee au trousseau. EEXIST operation etait KEYCTL_RESTRICT_KEYRING et le trousseau fourni dans le parametre arg2 comporte deja une restriction. EFAULT operation etait KEYCTL_DH_COMPUTE et une des actions suivantes a echoue : - copie de la struct keyctl_dh_params, fournie dans le parametre arg2, depuis l'espace utilisateur ; - copie de la struct keyctl_kdf_params, fournie dans l'argument non NULL arg5, depuis l'espace utilisateur (si le noyau gere l'operation KDF lors du resultat de l'operation DH) ; - copie des donnees vers lesquelles pointe le champ hashname de la struct keyctl_kdf_params a partir de l'espace utilisateur ; - copie des donnees vers lesquelles pointe le champ otherinfo de la struct keyctl_kdf_params depuis l'espace utilisateur si le champ otherinfolen n'etait pas zero ; - copie du resultat vers l'espace utilisateur. EINVAL operation etait KEYCTL_SETPERM et un bit de droit non valable a ete indique dans arg3. EINVAL operation etait KEYCTL_SEARCH et la taille de la description (comprenant l'octet NULL de fin) depassait 4096 octets. EINVAL la taille de la chaine (y compris l'octet NULL final) indiquee dans arg3 (le type de cle) ou dans arg4 (la description de la cle) depassait les limites (respectivement 32 et 4096 octets). EINVAL (avant Linux 4.12) operation etait KEYCTL_DH_COMPUTE, le parametre arg5 n'etait pas NULL. EINVAL operation etait KEYCTL_DH_COMPUTE et la taille de l'empreinte numerique de l'algorithme de hachage fourni est de zero. EINVAL operation etait KEYCTL_DH_COMPUTE et la taille du tampon fournie n'est pas suffisante pour contenir le resultat. Mettez 0 en tant que taille de tampon pour obtenir la taille minimale du tampon. EINVAL operation etait KEYCTL_DH_COMPUTE et le nom de hachage fourni dans le champ hashname de la struct keyctl_kdf_params vers laquelle pointe le parametre arg5 est trop grand (la limite est specifique a l'implementation et varie entre les versions du noyau, mais elle est consideree comme suffisante pour tous les noms d'algorithmes valables). EINVAL operation etait KEYCTL_DH_COMPUTE et le champ __spare de la struct keyctl_kdf_params fournie dans le parametre arg5 contient des valeurs autres que zero. EKEYEXPIRED Une cle expiree a ete trouvee ou specifiee. EKEYREJECTED Une cle rejetee a ete trouvee ou specifiee. EKEYREVOKED Une cle revoquee a ete trouvee ou specifiee. ELOOP operation etait KEYCTL_LINK et le rattachement demande ferait depasser la profondeur maximale d'imbrication des trousseaux. EMSGSIZE operation etait KEYCTL_DH_COMPUTE et la longueur du tampon depasse KEYCTL_KDF_MAX_OUTPUT_LEN (qui est actuellement de 1024) ou le champ otherinfolen de la struct keyctl_kdf_parms fournie dans arg5 depasse KEYCTL_KDF_MAX_OI_LEN (qui est actuellement de 64). ENFILE (avant Linux 3.13) operation etait KEYCTL_LINK et le trousseau est complet (avant Linux 3.13, l'espace disponible de stockage de rattachements de trousseaux etait limite a une seule page memoire ; depuis Linux 3.13, il n'y a pas de limite fixee). ENOENT operation etait KEYCTL_UNLINK et la cle a detacher n'est pas rattachee au trousseau. ENOENT operation etait KEYCTL_DH_COMPUTE et l'algorithme de hachage indique dans le champ hashname de la struct keyctl_kdf_params vers laquelle pointe le parametre arg5 n'a pas ete trouve. ENOENT operation etait KEYCTL_RESTRICT_KEYRING et le type fourni dans le parametre arg3 ne gere pas la definition de restrictions de rattachement de cles. ENOKEY Aucune cle correspondante n'a ete trouvee, ou une cle non valable a ete specifiee. ENOKEY La valeur KEYCTL_GET_KEYRING_ID etait indiquee dans operation, la cle indiquee dans arg2 n'existait pas et arg3 valait zero (ce qui veut dire ne pas creer de cle si elle n'existe pas). ENOMEM Une des routines de l'allocation memoire du noyau a echoue lors de l'execution de l'appel systeme. ENOTDIR Une cle de type trousseau etait attendue mais l'identifiant d'une cle de type different a ete fourni. EOPNOTSUPP operation etait KEYCTL_READ et le type de cle ne gere pas la lecture (par exemple, le type est << login >>). EOPNOTSUPP operation etait KEYCTL_UPDATE et le type de cle ne gere pas les mises a jour. EOPNOTSUPP operation etait KEYCTL_RESTRICT_KEYRING, le type fourni dans le parametre arg3 etait << asymmetric >>, et la cle indiquee dans la specification de la restriction fournie dans arg4 a un autre type que << asymmetric >> ou << keyring >>. EPERM operation etait KEYCTL_GET_PERSISTENT, arg2 indiquait un identifiant utilisateur different de celui de l'utilisateur reel ou effectif du thread appelant, et l'appelant n'avait pas la capacite CAP_SETUID. EPERM operation etait KEYCTL_SESSION_TO_PARENT et : soit tous les identifiants utilisateur (ou de groupe) du processus parent ne correspondent pas a celui effectif du processus appelant ; soit l'identifiant utilisateur du trousseau de session du parent, ou celui du trousseau de session de l'appelant, ne correspondait pas a l'identifiant de l'utilisateur effectif de l'appelant ; soit le processus parent se compose de plus d'un thread ; soit le processus parent est init(1) ou un thread du noyau. ETIMEDOUT operation etait KEYCTL_DH_COMPUTE et l'initialisation des modules de chiffrement a depasse le delai. VERSIONS Une enveloppe est fournie dans la bibliotheque libkeyutils. (Le paquet accompagnant fournit le fichier d'en-tete .) Cependant, plutot que d'utiliser cet appel systeme directement, vous voudrez probablement utiliser les fonctions de la bibliotheque mentionnees dans les descriptions des operations individuelles ci-dessus. STANDARDS Linux. HISTORIQUE Linux 2.6.10. EXEMPLES Le programme ci-dessous fournit un sous-ensemble de fonctions du programme request-key(8) fourni par le paquet keyutils. Pour information, le programme enregistre diverses informations dans un fichier journal. Comme indique dans request_key(2), le programme request-key(8) est appele avec les parametres de la ligne de commande qui decrivent une cle a instancier. Le programme exemple recupere et enregistre ces arguments. Le programme endosse l'autorite d'instancier la cle demandee, puis il instancie cette cle. La session d'interpreteur suivante montre l'utilisation de ce programme. Dans la session, nous compilons le programme, puis nous l'utilisons pour remplacer temporairement le programme request-key(8) standard (remarquez que la desactivation temporaire du programme standard request-key(8) peut ne pas etre sure sur certains systemes). Tant que notre programme exemple est installe, nous utilisons le programme exemple present dans request_key(2) pour demander une cle. $ cc -o key_instantiate key_instantiate.c -lkeyutils $ sudo mv /sbin/request-key /sbin/request-key.backup $ sudo cp key_instantiate /sbin/request-key $ ./t_request_key user mykey somepayloaddata L'identifiant de cle est 20d035bf $ sudo mv /sbin/request-key.backup /sbin/request-key En regardant le fichier journal cree par ce programme, on peut voir les parametres de la ligne de commande fournis a notre programme exemple : $ cat /tmp/key_instantiate.log Time: Mon Nov 7 13:06:47 2016 Command line arguments: argv[0]: /sbin/request-key operation: create key_to_instantiate: 20d035bf UID: 1000 GID: 1000 thread_keyring: 0 process_keyring: 0 session_keyring: 256e6a6 Les dernieres lignes de la sortie ci-dessus montrent que le programme exemple a pu recuperer : - la description de la cle a instanciee, qui incluait le nom de la cle (mykey) ; - la charge utile de la cle d'autorisation, qui consistait dans des donnees (somepayloaddata) passees a request_key(2) ; - le trousseau de destination indique dans l'appel a request_key(2) ; - la description de la cle d'autorisation ou on peut voir que le nom de la cle correspond a l'identifiant de celle a instancier (20d035bf). Le programme exemple dans request_key(2) indiquait le trousseau de destination en tant que KEY_SPEC_SESSION_KEYRING. En examinant le contenu de /proc/keys, on peut voir que cela a ete transcrit dans l'identifiant du trousseau de destination (0256e6a6) affiche dans le fichier journal ci-dessus ; on peut aussi voir la cle nouvellement creee dont le nom est mykey et l'identifiant est 20d035bf. $ cat /proc/keys | egrep 'mykey|256e6a6' 0256e6a6 I--Q--- 194 perm 3f030000 1000 1000 keyring _ses: 3 20d035bf I--Q--- 1 perm 3f010000 1000 1000 user mykey: 16 Source du programme /* key_instantiate.c */ #include #include #include #include #include #include #include #include #ifndef KEY_SPEC_REQUESTOR_KEYRING #define KEY_SPEC_REQUESTOR_KEYRING (-8) #endif int main(int argc, char *argv[]) { int akp_size; /* Taille de auth_key_payload */ int auth_key; char dbuf[256]; char auth_key_payload[256]; char *operation; FILE *fp; gid_t gid; uid_t uid; time_t t; key_serial_t key_to_instantiate, dest_keyring; key_serial_t thread_keyring, process_keyring, session_keyring; if (argc != 8) { fprintf(stderr, "Usage : %s op key uid gid thread_keyring " "process_keyring session_keyring\n", argv[0]); exit(EXIT_FAILURE); } fp = fopen("/tmp/key_instantiate.log", "w"); if (fp == NULL) exit(EXIT_FAILURE); setbuf(fp, NULL); t = time(NULL); fprintf(fp, "Time: %s\n", ctime(&t)); /* * Le noyau passe un ensemble fixe de parametres au programme * qu'il execute ; les recuperer. */ operation = argv[1]; key_to_instantiate = atoi(argv[2]); uid = atoi(argv[3]); gid = atoi(argv[4]); thread_keyring = atoi(argv[5]); process_keyring = atoi(argv[6]); session_keyring = atoi(argv[7]); fprintf(fp, "Parametres de la ligne de commande :\n"); fprintf(fp, " argv[0]: %s\n", argv[0]); fprintf(fp, " operation: %s\n", operation); fprintf(fp, " key_to_instantiate: %jx\n", (uintmax_t) key_to_instantiate); fprintf(fp, " UID: %jd\n", (intmax_t) uid); fprintf(fp, " GID: %jd\n", (intmax_t) gid); fprintf(fp, " thread_keyring: %jx\n", (uintmax_t) thread_keyring); fprintf(fp, " process_keyring: %jx\n", (uintmax_t) process_keyring); fprintf(fp, " session_keyring: %jx\n", (uintmax_t) session_keyring); fprintf(fp, "\n"); /* * Assumer l'autorite pour instancier la cle nommee dans argv[2]. */ if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == -1) { fprintf(fp, "KEYCTL_ASSUME_AUTHORITY a echoue : %s\n", strerror(errno)); exit(EXIT_FAILURE); } /* * Recuperer la description de la cle a instancier. */ if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate, dbuf, sizeof(dbuf)) == -1) { fprintf(fp, "KEYCTL_DESCRIBE a echoue : %s\n", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Description de cle : %s\n", dbuf); /* * Recuperer la charge utile de la cle d'autorisation, qui est en fait * les donnees d'appel (callout) donnees a request_key(). */ akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY, auth_key_payload, sizeof(auth_key_payload)); if (akp_size == -1) { fprintf(fp, "KEYCTL_READ a echoue : %s\n", strerror(errno)); exit(EXIT_FAILURE); } auth_key_payload[akp_size] = '\0'; fprintf(fp, "Charge utile de la cle d'auth : %s\n", auth_key_payload); /* * Par interet, recuperer l'identifiant de la cle d'autorisation et * l'afficher. */ auth_key = keyctl(KEYCTL_GET_KEYRING_ID, KEY_SPEC_REQKEY_AUTH_KEY); if (auth_key == -1) { fprintf(fp, "KEYCTL_GET_KEYRING_ID a echoue : %s\n", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Identifiant de la cle d'auth : %jx\n", (uintmax_t) auth_key); /* * Recuperer l'identifiant de cle pour le trousseau de destination * request_key(2). */ dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID, KEY_SPEC_REQUESTOR_KEYRING); if (dest_keyring == -1) { fprintf(fp, "KEYCTL_GET_KEYRING_ID a echoue : %s\n", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Trousseau de destination : %jx\n", (uintmax_t) dest_keyring); /* * Recuperer la description de la cle d'autorisation. Cela nous permet * de voir le type de cle, l'identifiant utilisateur et de groupe, les * droits et la description (nom) de la cle. Entre autres choses, * on verra que le nom de la cle est une chaine hexadecimale representant * l'identifiant de la cle a instancier. */ if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY, dbuf, sizeof(dbuf)) == -1) { fprintf(fp, "KEYCTL_DESCRIBE a echoue : %s\n", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Description de la cle d'auth : %s\n", dbuf); /* * Instancier la cle en utilisant les donnees de l'appel (callout) * fournies dans la charge utile de la cle d'autorisation. */ if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate, auth_key_payload, akp_size + 1, dest_keyring) == -1) { fprintf(fp, "KEYCTL_INSTANTIATE a echoue : %s\n", strerror(errno)); exit(EXIT_FAILURE); } exit(EXIT_SUCCESS); } VOIR AUSSI keyctl(1), add_key(2), request_key(2), keyctl(3), keyctl_assume_authority(3), keyctl_chown(3), keyctl_clear(3), keyctl_describe(3), keyctl_describe_alloc(3), keyctl_dh_compute(3), keyctl_dh_compute_alloc(3), keyctl_get_keyring_ID(3), keyctl_get_persistent(3), keyctl_get_security(3), keyctl_get_security_alloc(3), keyctl_instantiate(3), keyctl_instantiate_iov(3), keyctl_invalidate(3), keyctl_join_session_keyring(3), keyctl_link(3), keyctl_negate(3), keyctl_read(3), keyctl_read_alloc(3), keyctl_reject(3), keyctl_revoke(3), keyctl_search(3), keyctl_session_to_parent(3), keyctl_set_reqkey_keyring(3), keyctl_set_timeout(3), keyctl_setperm(3), keyctl_unlink(3), keyctl_update(3), recursive_key_scan(3), recursive_session_key_scan(3), capabilities(7), credentials(7), keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user_namespaces(7), user-session-keyring(7), request-key(8) Les fichiers sources du noyau Documentation/security/keys/ (ou avant Linux 4.13, dans le fichier Documentation/security/keys.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 1 novembre 2023 keyctl(2)