Provided by: manpages-fr-dev_4.26.0-1_all 
NOM
keyctl - Manipuler la gestion des clés du noyau
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
Sinon, les utilitaires de gestion de clefs Linux (libkeyutils, -lkeyutils); consultez VERSIONS.
SYNOPSIS
#include <linux/keyctl.h> /* Définition des constantes KEY* */
#include <sys/syscall.h> /* Définition des constantes SYS_* */
#include <unistd.h>
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(), nécessitant l'utilisation de syscall(2).
DESCRIPTION
keyctl() permet aux programmes de l'espace utilisateur de manipuler des clés.
L'opération qu'effectue keyctl() dépend de la valeur du paramètre operation. Chacune de ces opérations
fait partie de l'enveloppe de la bibliothèque libkeyutils (fournie par le paquet keyutils) en tant que
fonctions individuelles (indiquées ci-dessous) pour permettre au compilateur de vérifier les types.
Les valeurs autorisées pour operation sont :
KEYCTL_GET_KEYRING_ID (depuis Linux 2.6.10)
Associer l'identifiant d'une clé spéciale à celui d'une clé réelle pour ce processus.
Cette opération recherche la clé spéciale dont l'identifiant est fourni dans arg2 (transmis à
key_serial_t). Si la clé spéciale est trouvée, l'identifiant de la clé réelle correspondante est
renvoyé en tant que résultat de la fonction. Les valeurs suivantes peuvent être indiquées dans
arg2 :
KEY_SPEC_THREAD_KEYRING
Pour indiquer le trousseau spécifique au thread du thread appelant. Voir thread-keyring(7).
KEY_SPEC_PROCESS_KEYRING
Pour indiquer le trousseau spécifique au processus de l'appelant. Voir process-keyring(7).
KEY_SPEC_SESSION_KEYRING
Pour indiquer le trousseau spécifique à la session de l'appelant. Voir session-keyring(7).
KEY_SPEC_USER_KEYRING
Pour indiquer le trousseau spécifique à l'UID de l'appelant. Voir user-keyring(7).
KEY_SPEC_USER_SESSION_KEYRING
Pour indiquer le trousseau spécifique à 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 clé d'autorisation créée par request_key(2) et passée au processus qu'il
produit pour générer une clé. Cette clé n'est disponible que dans un programme à la manière
de request-key(8) où une clé d'autorisation a été passée par le noyau et cesse d’être
disponible lorsque la clé demandée a été instanciée ; voir request_key(2).
KEY_SPEC_REQUESTOR_KEYRING (depuis Linux 2.6.29)
Cela indique l'identifiant de la clé pour le trousseau de destination request_key(2). Ce
trousseau n'est disponible que dans un programme dans le style de request-key(8) où une clé
d'autorisation a été passée par le noyau et cesse d’être disponible une fois que la clé
demandée a été instanciée ; voir request_key(2).
Si la clé indiquée dans arg2 n'existe pas, le comportement dépend de la valeur de arg3 (diffusée
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 clé de session) —, une nouvelle clé est
créée et son identifiant de clé réelle est renvoyé en tant que résultat de la fonction. Sinon,
l'opération échoue avec l'erreur ENOKEY.
Si un identifiant de clé valable est indiqué dans arg2 et si la clé existe, cette opération
renvoie simplement l'identifiant de la clé. Si la clé n'existe pas, l'appel échoue avec l'erreur
ENOKEY.
L'appelant doit avoir le droit search sur un trousseau pour qu’il soit trouvable.
Les paramètres arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à 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 à laquelle le processus est rattaché par un nouveau trousseau
de session.
Si arg2 vaut NULL, un trousseau anonyme dont la description est « _ses » est créé et le processus
est inscrit à ce trousseau en tant que trousseau de sa session, remplaçant le trousseau de la
session précédente.
Sinon, arg2 (diffusé dans char *) est traité 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
à ce trousseau en tant que trousseau de session si c'est possible ; sans quoi une erreur est
renvoyée. 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 indiquée est créé et le processus est inscrit à ce trousseau en tant que trousseau
de session.
Les paramètres arg3, arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils par la fonction
keyctl_join_session_keyring(3).
KEYCTL_UPDATE (depuis Linux 2.6.10)
Mettre à jour la charge utile des données d'une clé.
Le paramètre arg2 (diffusé sur key_serial_t) indique l'identifiant de la clé à mettre à jour. Le
paramètre arg3 (diffusé sur void *) pointe vers la nouvelle charge utile et arg4 (diffusé sur
size_t) contient la taille de la nouvelle charge utile (en octets).
L'appelant doit avoir les droits write sur la clé indiquée et le type de clé doit gérer les mises
à jour.
Une clé instanciée négativement (voir la description de KEYCTL_REJECT) peut être instanciée
positivement avec cette opération.
Le paramètre arg5 est ignoré.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_update(3).
KEYCTL_REVOKE (depuis Linux 2.6.10)
Révoquer la clé dont l'identifiant est fourni dans arg2 (diffusé sur key_serial_t). La clé est
vouée à aller à la poubelle ; elle ne sera plus trouvable et ne sera plus disponible pour de
futures opérations. Les futures tentatives d'utiliser la clé échoueront avec l'erreur EKEYREVOKED.
L'appelant doit avoir les droits write ou setattr sur la clé.
Les paramètres arg3, arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_revoke(3).
KEYCTL_CHOWN (depuis Linux 2.6.10)
Changer le propriétaire (identifiant de l'utilisateur et du groupe) d'une clé.
Le paramètre arg2 (diffusé sur key_serial_t) contient l'identifiant de la clé. Le paramètre arg3
(diffusé sur uid_t) contient l'identifiant du nouvel utilisateur (ou -1 s'il ne doit pas être
modifié). Le paramètre arg4 (diffusé sur gid_t) contient l'identifiant du nouveau groupe (ou -1
s'il ne doit pas être modifié).
La clé doit accorder le droit setattr à 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 capacité CAP_SYS_ADMIN (voir
capabilities(7)).
Si l'identifiant utilisateur doit être modifié, le nouvel utilisateur doit avoir un quota
suffisant pour accepter la clé. La déduction du quota sera déplacée de l’ancien utilisateur vers
le nouveau à condition que l’UID ait changé.
Le paramètre arg5 est ignoré.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_chown(3).
KEYCTL_SETPERM (depuis Linux 2.6.10)
Passer les droits de la clé dont l'identifiant est fourni dans le paramètre arg2 (diffusé sur
key_serial_t) à ceux fournis dans le paramètre arg3 (diffusé sur key_perm_t).
Si l'appelant n'a pas la capacité CAP_SYS_ADMIN, il ne peut modifier que les droits des clés qu'il
possède. (Plus précisément, l’UID du système de fichiers de l’appelant doit correspondre à l’UID
de la clé.)
La clé doit accorder le droit setattr à l'appelant indépendamment de ses capacités.
Les droits dans arg3 indiquent les masques des opérations disponibles pour chacune des catégories
suivantes d'utilisateur :
possessor (depuis Linux 2.6.14)
Il s'agit des droits accordés à un processus possédant la clé (en tant qu'il est rattaché à
un des trousseaux du processus trouvables) ; voir keyrings(7).
user Il s'agit du droit accordé à un processus dont l'identifiant utilisateur du système de
fichiers correspond à celui de la clé.
group Il s'agit du droit accordé au processus dont l'identifiant de groupe du système de fichiers
ou un de ses identifiants de groupes supplémentaires correspond à celui de la clé.
other Il s'agit du droit accordé aux autres processus qui ne rentrent pas dans les catégories
user et group.
Les catégories user, group et other sont exclusives : si un processus rentre dans la catégorie
user, il ne recevra pas de droits dans la catégorie group ; s'il rentre dans la catégorie user ou
group, il ne recevra aucun droit de la catégorie other.
La catégorie possessor accorde des droits qui s'ajoutent à ceux accordés en vertu des catégories
user, group ou other.
Chaque masque de droits pèse huit bits, dont seuls six sont actuellement utilisés. Les droits
disponibles sont :
view Droit de lire les attributs d'une clé.
Ce droit est nécessaire pour l'opération KEYCTL_DESCRIBE.
Les bits de droit pour chaque catégorie sont KEY_POS_VIEW, KEY_USR_VIEW, KEY_GRP_VIEW et
KEY_OTH_VIEW.
read Lire la charge utile d'une clé.
Ce droit est nécessaire pour l'opération KEYCTL_READ.
Les bits de droit pour chaque catégorie sont KEY_POS_READ, KEY_USR_READ, KEY_GRP_READ et
KEY_OTH_READ.
write Mettre à jour ou instancier une clé. Pour un trousseau, attacher ou détacher des clés d'un
trousseau.
Ce droit est nécessaire pour les opérations KEYCTL_UPDATE, KEYCTL_REVOKE, KEYCTL_CLEAR,
KEYCTL_LINK et KEYCTL_UNLINK.
Les bits des droits pour chaque catégorie sont KEY_POS_WRITE, KEY_USR_WRITE, KEY_GRP_WRITE
et KEY_OTH_WRITE.
search Rechercher dans les trousseaux et rendre les clés trouvables. Les recherches ne peuvent
parcourir des trousseaux imbriqués que si les droits search y sont positionnés.
Ce droit est nécessaire pour les opérations KEYCTL_GET_KEYRING_ID,
KEYCTL_JOIN_SESSION_KEYRING, KEYCTL_SEARCH et KEYCTL_INVALIDATE.
Les bits de droit pour chaque catégorie sont KEY_POS_SEARCH, KEY_USR_SEARCH, KEY_GRP_SEARCH
et KEY_OTH_SEARCH.
link Rattacher une clé ou un trousseau.
Ce droit est nécessaire pour les opérations KEYCTL_LINK et KEYCTL_SESSION_TO_PARENT.
Les bits des droits pour cette catégorie 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 clé.
Ce droit est nécessaire pour les opérations KEYCTL_REVOKE, KEYCTL_CHOWN et KEYCTL_SETPERM.
Les bits de droits pour chaque catégorie sont KEY_POS_SETATTR, KEY_USR_SETATTR,
KEY_GRP_SETATTR et KEY_OTH_SETATTR.
Par commodité, les macros suivantes sont définies en tant que masques pour tous les bits de droits
de chacune des catégories de l'utilisateur : KEY_POS_ALL, KEY_USR_ALL, KEY_GRP_ALL et KEY_OTH_ALL.
Les paramètres arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_setperm(3).
KEYCTL_DESCRIBE (depuis Linux 2.6.10)
Obtenir une chaîne décrivant les attributs d'une clé indiquée.
L'identifiant de la clé à décrire est indiqué dans arg2 (diffusé sur key_serial_t). La chaîne de
description est renvoyée dans le tampon vers lequel pointe arg3 (diffusé sur char *) ; arg4
(diffusé sur size_t) indique la taille de ce tampon en octets.
La clé doit accorder le droit view à l'appelant.
La chaîne renvoyée se termine par NULL et contient les informations suivantes sur la clé :
type;uid;gid;perm;description
Dans ce qui précède, type et description sont des chaînes, uid et gid sont des chaînes décimales
et perm est un masque de droits hexadécimal. La chaîne de description est écrite dans le format
suivant :
%s;%d;%d;%08x;%s
Note : l'objectif est d'étendre la chaîne de description dans les futures versions du noyau. En
particulier, le champ description ne contiendra pas de point-virgule ; elle doit être analysée en
partant de la fin pour chercher le dernier point-virgule. Cela permettra, à l'avenir, d'insérer
des champs délimités avec des points-virgules.
Une tentative d'écrire dans le tampon n'a lieu que lorsque arg3 n'est pas NULL et quand la taille
du tampon indiquée est assez grande pour accepter la chaîne de description (y compris l'octet NULL
final). Afin de déterminer si la taille du tampon était trop petite, vérifiez que la valeur de
retour de l'opération est supérieure à arg4.
Le paramètre arg5 est ignoré.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_describe(3).
KEYCTL_CLEAR
Vider le contenu (à savoir détacher les clés) d'un trousseau.
L'identifiant de la clé (qui doit être de type trousseau) est fourni dans arg2 (diffusé sur
key_serial_t).
L'appelant doit avoir le droit write sur le trousseau.
Les paramètres arg3, arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_clear(3).
KEYCTL_LINK (depuis Linux 2.6.10)
Créer un lien d'un trousseau vers une clé.
La clé à rattacher est indiquée dans arg2 (diffusé sur key_serial_t) ; le trousseau est indiqué
dans arg3 (diffusé sur key_serial_t).
Si une clé du même type et ayant la même description se trouve déjà rattachée au trousseau, elle
est éliminée du trousseau.
Avant de créer le rattachement, le noyau vérifie la profondeur des trousseaux et renvoie les
erreurs adéquates si le rattachement crée une boucle ou si la profondeur des trousseaux serait
trop importante (la limite de profondeur est définie par la constante KEYRING_SEARCH_MAX_DEPTH du
noyau, fixée à 6, et elle est nécessaire pour empêcher les débordements de de la pile du noyau
lors d'une recherche récursive de trousseaux).
L'appelant doit avoir le droit link sur la clé à ajouter et celui write sur le trousseau.
Les paramètres arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_link(3).
KEYCTL_UNLINK (depuis Linux 2.6.10)
Supprimer une clé d'un trousseau.
L'identifiant de la clé à détacher est indiqué dans arg2 (diffusé sur key_serial_t) ;
l'identifiant du trousseau d'où la clé doit être détachée est indiqué dans arg3 (diffusé sur
key_serial_t).
Si la clé n'est pas rattachée au trousseau, cela produit une erreur.
L'appelant doit avoir le droit write sur le trousseau d'où doit être détachée la clé.
Si le dernier rattachement d'une clé est supprimé, cette clé sera mise en destruction.
Les paramètres arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_unlink(3).
KEYCTL_SEARCH (depuis Linux 2.6.10)
Chercher une clé dans l'arborescence d'un trousseau, renvoyer son identifiant et, éventuellement,
la rattacher à un trousseau indiqué.
L'arborescence où doit s'effectuer la recherche est indiquée en passant l'identifiant de la clé de
tête à arg2 (diffusé sur key_serial_t). La recherche s'effectue en largeur et récursivement.
Les paramètres arg3 et arg4 indiquent la clé à rechercher : arg3 (diffusé en tant que char *)
contient le type de clé (une chaîne de caractères se terminant par NULL et mesurant jusqu'à
32 octets en comptant l'octet NULL final), et arg4 (diffusé en tant que char *) contient la
description de la clé (une chaîne de caractères se terminant par NULL et mesurant jusqu'à
4096 octets en comptant l'octet NULL final).
Le trousseau d'origine doit autoriser l'appelant à search. Pendant la recherche récursive, seuls
les trousseaux accordant le droit search à l'appelant seront explorés. Seules les clés pour
lesquelles l'appelant a le droit search seront trouvées.
Si la clé est trouvée, son identifiant est renvoyé en tant que résultat de la fonction.
Si la clé est trouvée et si arg5 (diffusé sur key_serial_t) n'est pas zéro, la clé est rattachée
au trousseau indiqué dont l'identifiant est indiqué dans arg5, avec les mêmes contraintes et les
mêmes règles que KEYCTL_LINK. Si le trousseau cible indiqué dans arg5 contient déjà une clé
rattachée du même type et à la même description, cet attachement sera remplacé par un autre avec
la clé trouvée avec cette opération.
Plutôt que des identifiants de trousseaux existants valables, les trousseaux d'origine (arg2) et
cible (arg5) peuvent être un des identifiants de trousseau de clés spéciales indiqué dans
KEYCTL_GET_KEYRING_ID.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_search(3).
KEYCTL_READ (depuis Linux 2.6.10)
Lire les données de la charge utile (payload) d'une clé.
L'identifiant de la clé dont la charge utile va être lue est indiqué dans arg2 (diffusé sur
key_serial_t). Il peut s'agir de l'identifiant d'une clé existante ou un identifiant de clé
spéciale listé dans KEYCTL_GET_KEYRING_ID.
La charge utile est mise dans le tampon vers lequel pointe arg3 (diffusé sur char *) ; la taille
de ce tampon doit être indiquée dans arg4 (diffusé sur size_t).
Les données renvoyées seront traitées pour être présentées en fonction du type de clé. Par
exemple, un trousseau renverra un tableau d'entrées key_serial_t qui représentent les identifiants
de toutes les clés qui y sont rattachées. Le type de clé user renverra ses données telles quelles.
Si un type de clé n'implémente pas cette fonction, l'opération échoue avec l'erreur EOPNOTSUPP.
Si arg3 n'est pas NULL, autant de données que possible de la charge utile seront copiées dans le
tampon. En cas de renvoi d'un succès, la valeur est toujours la taille totale des données de la
charge utile. Pour savoir si le tampon était de taille suffisante, vérifiez que la valeur de
retour est inférieure ou égale à celle fournie dans arg4.
La clé doit accorder à l'appelant le droit read, ou bien lui accorder le droit search quand elle
est recherchée depuis les trousseaux d'un processus (à savoir quand elle est détenue).
Le paramètre arg5 est ignoré.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_read(3).
KEYCTL_INSTANTIATE (depuis Linux 2.6.10)
Instancier (positivement) une clé non instanciée avec une charge utile indiquée
L'identifiant de la clé à instancier est fournie dans arg2 (diffusée sur key_serial_t).
La charge utile de la clé est indiquée dans le tampon vers lequel pointe arg3 (diffusé sur
void *) ; la taille de ce tampon est indiquée dans arg4 (diffusée sur size_t).
La charge utile peut être un pointeur NULL et la taille du tampon peut être de 0 si cela est pris
en charge par le type de clé (si c'est un trousseau, par exemple).
L'opération peut échouer si les données de charge utile sont dans un mauvais format ou non
valables pour toute autre raison.
Si arg5 (diffusé sur key_serial_t) n'est pas zéro, la clé instanciée est rattachée au trousseau
dont l'identifiant a été indiqué dans arg5, avec les mêmes contraintes et les mêmes règles que
KEYCTL_LINK.
L'appelant doit avoir la clé d'autorisation adéquate, et une fois que la clé non instanciée a été
instanciée, la clé d'autorisation est révoquée. Autrement dit, cette opération n'est disponible
qu'à partir d'un programme de style request-key(8). Voir request_key(2) pour une explication sur
les clés non instanciées et l'instanciation de clés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction
keyctl_instantiate(3).
KEYCTL_NEGATE (depuis Linux 2.6.10)
Instancier négativement une clé non instanciée.
Cette opération est équivalente à l'appel :
keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
Le paramètre arg5 est ignoré.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_negate(3).
KEYCTL_SET_REQKEY_KEYRING (depuis Linux 2.6.10)
Définir le trousseau par défaut auquel les clés demandées implicitement seront rattachées pour ce
thread et renvoyer la configuration précédente. Les requêtes de clé implicites sont celles que des
composants du noyau effectuent en interne, comme par exemple lors de l'ouverture de fichiers sur
des systèmes de fichiers AFS ou NFS. Le fait de définir un trousseau par défaut produit également
des effets lors d'une demande de clé depuis l'espace utilisateur ; voir request_key(2) pour les
détails.
Le paramètre arg2 (diffusé sur int) doit contenir une des valeurs suivantes pour indiquer le
nouveau trousseau par défaut :
KEY_REQKEY_DEFL_NO_CHANGE
Ne pas modifier le trousseau par défaut. Cela peut servir à rechercher le trousseau par
défaut actuel (sans le modifier).
KEY_REQKEY_DEFL_DEFAULT
Cela sélectionne le comportement par défaut qui consiste à utiliser le trousseau spécifique
au thread s'il y en a un, ou sinon celui spécifique au processus s'il y en a un, ou bien
celui spécifique à la session s'il y en a un, ou sinon celui de la session spécifique de
l'identifiant utilisateur, ou celui spécifique à l'utilisateur.
KEY_REQKEY_DEFL_THREAD_KEYRING
Utiliser le trousseau spécifique du thread (thread-keyring(7)) en tant que nouveau
trousseau par défaut.
KEY_REQKEY_DEFL_PROCESS_KEYRING
Utiliser le trousseau spécifique au processus (process-keyring(7)) en tant que nouveau
trousseau par défaut.
KEY_REQKEY_DEFL_SESSION_KEYRING
Utiliser le trousseau spécifique à la session (session-keyring(7)) en tant que nouveau
trousseau par défaut.
KEY_REQKEY_DEFL_USER_KEYRING
Utiliser le trousseau spécifique à l'identifiant utilisateur (user-keyring(7)) en tant que
nouveau trousseau par défaut.
KEY_REQKEY_DEFL_USER_SESSION_KEYRING
Utiliser le trousseau de la session spécifique de l'identifiant utilisateur
(user-session-keyring(7)) en tant que nouveau trousseau par défaut.
KEY_REQKEY_DEFL_REQUESTOR_KEYRING (depuis Linux 2.6.29)
Utiliser le trousseau du demandeur.
Toutes les autres valeurs ne sont pas valables.
Les paramètres arg3, arg4 et arg5 sont ignorés.
Le paramètre que contrôle cette opération est récupéré par l'enfant de fork(2) et conservé durant
un execve(2).
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction
keyctl_set_reqkey_keyring(3).
KEYCTL_SET_TIMEOUT (depuis Linux 2.6.10)
Définir un délai d'expiration sur une clé.
L'identifiant de la clé est indiqué dans arg2 (diffusé sur key_serial_t). La valeur du délai, en
seconde à partir de l'heure actuelle, est indiquée dans arg3 (diffusé sur unsigned int). Le délai
se mesure par rapport à l'horloge en temps réel.
L'indication d'une valeur de délai de 0 vide les délais existants de la clé.
Le fichier /proc/keys affiche le temps restant avant l'expiration de chaque clé (il s'agit de la
seule méthode de recherche du temps de vie d'une clé).
L'appelant doit avoir le droit setattr sur la clé ou détenir un jeton d'autorisation
d’instanciation pour cette clé (voir request_key(2)).
La clé et les liens vis-à-vis d'elle seront automatiquement mis à la poubelle après le délai
d'expiration. Les futurs essais d'y accéder échoueront avec l'erreur EKEYEXPIRED.
Cette opération ne peut pas être utilisée pour poser des limites à des clés révoquées, expirées ou
instanciées négativement.
Les paramètres arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction
keyctl_set_timeout(3).
KEYCTL_ASSUME_AUTHORITY (depuis Linux 2.6.10)
Assumer (ou se débarrasser) de l'autorité pour le thread appelant pour instancier une clé.
Ce paramètre arg2 (diffusé sur key_serial_t) fait assumer l'autorité à un identifiant de clé autre
que zéro, ou retire l'autorité grâce à la valeur 0.
Si arg2 n'est pas zéro, il indique un identifiant de clé non instanciée qui devra assumer
l'autorité. Cette clé peut alors être instanciée en utilisant KEYCTL_INSTANTIATE,
KEYCTL_INSTANTIATE_IOV, KEYCTL_REJECT ou KEYCTL_NEGATE. Quand la clé a été instanciée, le thread
se voit automatiquement retirer le pouvoir d'instancier la clé.
Une clé ne peut assumer une autorité que si le thread appelant a dans ses trousseaux la clé
d'autorisation associée à la clé (autrement dit, l'opération KEYCTL_ASSUME_AUTHORITY n'est
disponible qu'à partir d'un programme du style request-key(8) ; voir request_key(2) pour une
explication sur la manière dont cette opération est utilisée). L'appelant doit avoir le droit
search sur la clé d'autorisation.
Si la clé indiquée a une clé d'autorisation associée, l'identifiant de cette clé est renvoyé. La
clé d'autorisation peut être lue (KEYCTL_READ) pour obtenir les informations d'appel transmises à
request_key(2).
Si l'identifiant fourni dans arg2 est 0, l'autorité actuellement assumée est retirée et la valeur
0 est renvoyée.
Le mécanisme KEYCTL_ASSUME_AUTHORITY permet à un programme tel que requestkey(8) d'assumer
l'autorité nécessaire pour instancier une nouvelle clé non instanciée créée suite à un appel à
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 paramètres arg3, arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction
keyctl_assume_authority(3).
KEYCTL_GET_SECURITY (depuis Linux 2.6.26)
Récupérer l'étiquette de sécurité LSM (Linux Security Module) de la clé indiquée.
L'identifiant de la clé dont l'étiquette doit être récupérée est indiqué dans arg2 (diffusé sur
key_serial_t). L'étiquette de sécurité (qui se termine par un octet NULL) sera mis dans le tampon
vers lequel pointe arg3 (diffusé sur char *) ; la taille du tampon doit être fournie dans arg4
(diffusée sur size_t).
Si arg3 est indiqué en tant que NULL ou si la taille du tampon indiquée dans arg4 est trop petite,
toute la taille de la chaîne de l'étiquette de sécurité (y compris l'octet NULL de fin) est
renvoyée en tant que résultat de la fonction et rien n'est copié dans le tampon.
L'appelant doit avoir le droit view sur la clé indiquée.
La chaîne de l'étiquette de sécurité renvoyée sera affichée sous la bonne forme sur le LSM en mode
force. Par exemple, avec SELinux, elle peut ressembler à :
unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
Si aucun LSM n'est en mode force, une chaîne vide est placée dans le tampon.
Le paramètre arg5 est ignoré.
Cette opération est mise à disposition par libkeyutils à 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 enregistré le parent du processus appelant par celui
du processus appelant.
Le trousseau sera remplacé 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 à l'appelant. Le processus parent doit être
single-threaded et appartenir au même utilisateur/groupe effectif que ce processus, et il ne doit
pas être 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 à celui de l'identifiant utilisateur effectif de l'appelant.
Le fait que le processus parent soit touché par cette opération permet à un programme tel qu'un
interpréteur de démarrer un processus enfant qui utilise cette opération pour modifier le
trousseau de session de l'interpréteur (c'est ce que fait la commande new_session de keyctl(1)).
Les paramètres arg2, arg3, arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction
keyctl_session_to_parent(3).
KEYCTL_REJECT (depuis Linux 2.6.39)
Marquer une clé comme étant instanciée négativement et positionner une durée d'expiration sur la
clé. Cette opération ajoute un supplément à l'opération KEYCTL_NEGATE ci-dessus.
L'identifiant de la clé à instancier négativement est indiqué dans arg2 (diffusé sur
key_serial_t). Le paramètre arg3 (diffusé sur unsigned int) indique la durée de vie de la clé en
seconde. Le paramètre arg4 (diffusé sur unsigned int) indique l'erreur à renvoyer quand une
recherche trouve cette clé ; généralement il s'agit de EKEYREJECTED, EKEYREVOKED ou EKEYEXPIRED.
Si arg5 (diffusé sur key_serial_t) n'est pas nul, la clé instanciée négativement est rattachée au
trousseau dont l'identifiant est indiqué dans arg5, avec les mêmes contraintes et les mêmes règles
que KEYCTL_LINK.
L'appelant doit avoir la clé d'autorisation adéquate. Autrement dit, cette opération n'est
disponible qu'à partir d'un programme dans le style request-key(8). Voir request_key(2).
L'appelant doit avoir la clé d'autorisation adéquate, et une fois que la clé non instanciée a été
instanciée, la clé d'autorisation est révoquée. Autrement dit, cette opération n'est disponible
qu'à partir d'un programme de style request-key(8). Voir request_key(2) pour une explication sur
les clés non instanciées et l'instanciation de clés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction keyctl_reject(3).
KEYCTL_INSTANTIATE_IOV (depuis Linux 2.6.39)
Instancier une clé non instanciée avec la charge utile indiquée à l'aide d'un vecteur de tampons.
Cette opération est la même que KEYCTL_INSTANTIATE, mais les données de la charge utile sont
indiquées sous forme d'un tableau de structures iovec (voir iovec(3type)).
Le pointeur vers le vecteur de charge utile est indiqué dans arg3 (diffusé en tant que const
struct iovec *). Le nombre d'éléments du vecteur est indiqué dans arg4 (diffusé en tant que
unsigned int).
arg2 (identifiant de clé) et arg5 (identifiant de trousseau) sont interprétés avec
KEYCTL_INSTANTIATE.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction
keyctl_instantiate_iov(3).
KEYCTL_INVALIDATE (depuis Linux 3.5)
Marquer une clé comme non valable.
L'identifiant de la clé à rendre non valable est indiqué dans arg2 (diffusé sur key_serial_t).
Pour rendre une clé non valable, l'appelant doit avoir le droit search sur la clé.
Cette opération marque la clé comme non valable et programme sa mise immédiate à la corbeille. Le
ramasse-miettes, supprime les clés non valables de tous les trousseaux et efface la clé quand son
nombre de références atteint 0. Après cette opération, cette clé sera ignorée par toutes les
recherches, même si elle n'est pas encore effacée.
Les clés marquées comme non valables deviennent aussitôt invisibles pour les opérations de clé
normales, bien qu'elle soient encore visibles dans /proc/keys (avec un drapeau « i ») jusqu'à ce
qu'elles soient totalement supprimées.
Les paramètres arg3, arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction
keyctl_invalidate(3).
KEYCTL_GET_PERSISTENT (depuis Linux 3.13)
Récupérer le trousseau persistant (persistent-keyring(7)) d'un utilisateur indiqué et le rattacher
au trousseau indiqué.
L'identifiant utilisateur est indiqué dans arg2 (diffusé sur uid_t). Si la valeur -1 est indiquée,
l'identifiant de l'utilisateur réel de l'appelant est utilisé. L'identifiant du trousseau de
destination est indiqué dans arg3 (diffusé sur key_serial_t).
L'appelant doit avoir la capacité CAP_SETUID dans son espace de noms utilisateur afin de récupérer
le trousseau persistant pour un identifiant utilisateur qui ne correspond pas à l'identifiant
utilisateur réel ou effectif de l'appelant.
Si l'appel réussit, un lien vers le trousseau persistant est ajouté au trousseau dont
l'identifiant a été indiqué dans arg3.
L'appelant doit avoir le droit write sur le trousseau.
Le trousseau persistant sera créé par le noyau s'il n'existe pas encore.
Chaque fois que l'opération KEYCTL_GET_PERSISTENT est effectuée, le trousseau persistant aura un
délai d'expiration réinitialisé à la valeur dans :
/proc/sys/kernel/keys/persistent_keyring_expiry
Lorsque le délai est atteint, le trousseau persistant sera supprimé et son contenu pourra être
collecté par le ramasse-miettes.
Des trousseaux persistants ont été ajoutés dans Linux 3.13.
Les paramètres arg4 et arg5 sont ignorés.
Cette opération est mise à disposition par libkeyutils à l'aide de la fonction
keyctl_get_persistent(3).
KEYCTL_DH_COMPUTE (depuis Linux 4.7)
Calculer la clé secrète Diffie-Hellman partagée ou la clé publique, en appliquant éventuellement
une fonction de dérivation de clé (KDF) au résultat.
Le paramètre arg2 est un pointeur vers un ensemble de paramètres contenant les numéros de série de
trois clés « utilisateur » utilisés dans le calcul Diffie-Hellman, empaquetés dans une structure
de la forme suivante :
struct keyctl_dh_params {
int32_t private; /* La clé privée locale */
int32_t prime; /* Le nombre premier, connue des deux côtés */
int32_t base; /* L'entier de base : soit un générateur partagé,
soit la clé publique distante */
};
Chacune des trois clés indiquées dans cette structure doit accorder le droit read à l'appelant.
Les charges utiles de ces clés sont utilisées pour calculer le résultat Diffie-Hellman ainsi :
base ^ private mod prime
Si la base est le générateur partagé, le résultat est la clé publique locale. Si la base est la
clé publique distante, le résultat est le code secret partagé.
Le paramètre arg3 (diffusé sur char *) pointe vers un tampon où est mis le résultat du calcul. La
taille de ce tampon est indiquée dans arg4 (diffusé sur size_t).
Le tampon doit être assez grand pour accueillir les données de sortie, sans quoi une erreur est
renvoyée. Si arg4 vaut zéro, le tampon n'est pas utilisé et l'opération renvoie la taille minimale
requise du tampon (à savoir la longueur du nombre premier).
Les calculs Diffie-Hellman peuvent être effectués dans l'espace utilisateur mais exigent une
bibliothèque multiprécision d'entiers (MPI). Le déplacement de l'implémentation dans le noyau
donne accès à l'implémentation MPI du noyau et permet d'accéder à la sécurisation et à
l'accélération matérielle.
L'ajout de la prise en charge du calcul DH à l'appel système keyctl() a été considéré comme
convenable grâce à l'utilisation de l'algorithme DH pour faire dériver les clés partagées ; cela
permet aussi au type de clé de déterminer l'implémentation DH adéquate (logicielle ou matérielle).
Si le paramètre arg5 vaut NULL, le résultat DH lui-même est renvoyé. Sinon, (depuis Linux 4.12),
il s'agit d'un pointeur vers une structure qui indique les paramètres de l'opération KDF à
appliquer :
struct keyctl_kdf_params {
char *hashname; /* Nom de l'algorithm de hachage */
char *otherinfo; /* SP800-56A OtherInfo */
__u32 otherinfolen; /* Taille des données otherinfo */
__u32 __spare[8]; /* Réservé */
};
Le champ hashname est une chaîne se terminant par NULL qui indique un nom de hachage (disponible
dans l'API de chiffrement du noyau ; la liste des hachages disponibles est plutôt difficile à
examiner ; veuillez vous reporter à la documentation de la « Kernel Crypto API Architecture » pour
des informations sur la manière dont les noms de hachage sont construits, et aux sources et à la
configuration de votre noyau concernant les chiffrements et les modèles de type
CRYPTO_ALG_TYPE_SHASH disponibles) à appliquer au résultat DH dans l'opération KDF.
Le champ otherinfo consiste dans des données OtherInfo comme décrit dans la section 5.8.1.2 de
SP800-56A et il est spécifique à l'algorithme. Ces données sont concaténées avec le résultat de
l'opération DH et elles sont fournies comme entrée de l'opération KDF. Leur taille est fournie
dans le champ otherinfolen et limitée à la constante KEYCTL_KDF_MAX_OI_LEN définie dans
security/keys/internal.h à la valeur 64.
Le champ __spare est actuellement inusité. Il était ignoré jusqu'à Linux 4.13 (mais il est encore
visible par l'utilisateur puisqu'il est copié dans le noyau) et il devrait contenir des zéros
depuis Linux 4.13.
L'implémentation KDF se conforme à SP800-56A et à SP800-108 (le compteur KDF).
Cette opération est mise à disposition par libkeyutils (à partir de libkeyutils 1.5.10 jusqu'à
aujourd'hui) à 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 clé à un trousseau dont l'identifiant est fourni dans
arg2 (diffusé sur key_serial_t). L'appelant doit avoir le droit setattr sur la clé. Si arg3 vaut
NULL, toute tentative d'ajout au trousseau est bloquée ; sinon il contient un pointeur vers une
chaîne contenant le nom du type de clé et arg4 contient un pointeur vers une chaîne contenant la
restriction spécifique au type de clé. À partir de Linux 4.12, seul le type « asymmetric » a des
restrictions définies :
builtin_trusted
N'autoriser que les clés signées par une clé rattachée au trousseau interne
(« .builtin_trusted_keys »).
builtin_and_secondary_trusted
N'autoriser que les clés signées par une clé rattachée à un trousseau secondaire
(« .secondary_trusted_keys ») ou, par extension, à une clé du trousseau interne, puisque le
deuxième est lié au premier.
key_or_keyring:key
key_or_keyring:key:chain
Si key indique l'identifiant d'une clé de type « asymmetric », seules les clés signées par
cette clé sont autorisées.
Si key indique l'identifiant d'un trousseau, seules les clés signées par une clé rattachée
à ce trousseau sont autorisées.
Si « :chain » est indiqué, les clés signées par une clé rattachée au trousseau de
destination (c'est-à-dire le trousseau dont l'identifiant est indiqué dans le paramètre
arg2) sont aussi autorisées.
Remarquez qu'une restriction ne peut être configurée qu'une fois pour le trousseau indiqué ; une
fois qu'une restriction est positionnée, elle ne peut pas être contournée.
Le paramètre arg5 est ignoré.
VALEUR RENVOYÉE
Pour qu'un appel réussisse, le code de retour dépend de l'opération :
KEYCTL_GET_KEYRING_ID
L'identifiant du trousseau demandé.
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) indépendamment de la taille du tampon
fournie.
KEYCTL_SEARCH
L'identifiant de la clé trouvée.
KEYCTL_READ
La quantité de données disponibles dans la clé, indépendamment de la taille du tampon fournie.
KEYCTL_SET_REQKEY_KEYRING
L'identifiant du trousseau par défaut précédent auquel ont été rattachées implicitement les clés
sollicitées (un parmi KEY_REQKEY_DEFL_USER_*).
KEYCTL_ASSUME_AUTHORITY
0 si l'identifiant donné valait 0, ou l'identifiant de la clé d'autorisation correspondant à la
clé indiquée, si un identifiant de clé autre que zéro a été fourni.
KEYCTL_GET_SECURITY
La taille de la chaîne de l'étiquette de sécurité LSM (y compris l'octet NULL de fin),
indépendamment de la taille du tampon fourni.
KEYCTL_GET_PERSISTENT
L'identifiant du trousseau persistant.
KEYCTL_DH_COMPUTE
Le nombre d'octets copiés dans le tampon ou, si arg4 vaut 0, la taille du tampon nécessaire.
Toutes les autres opérations :
Zéro.
En cas d'erreur, la valeur de retour est -1 et errno est définie pour préciser l'erreur.
ERREURS
EACCES L'opération demandée n'était pas autorisée.
EAGAIN operation était KEYCTL_DH_COMPUTE et une erreur s'est produite lors de l'initialisation du module
de chiffrement.
EDEADLK
operation était KEYCTL_LINK et le rattachement demandé conduirait à une boucle.
EDEADLK
operation était KEYCTL_RESTRICT_KEYRING et la restriction de trousseau demandée aboutirait à une
boucle.
EDQUOT Le quota de clés de l'utilisateur appelant serait dépassé si la clé était créée ou ajoutée au
trousseau.
EEXIST operation était KEYCTL_RESTRICT_KEYRING et le trousseau fourni dans le paramètre arg2 comporte
déjà une restriction.
EFAULT operation était KEYCTL_DH_COMPUTE et une des actions suivantes a échoué :
- copie de la struct keyctl_dh_params, fournie dans le paramètre 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 gère l'opération KDF lors du résultat de l'opération DH) ;
- copie des données vers lesquelles pointe le champ hashname de la struct keyctl_kdf_params à
partir de l'espace utilisateur ;
- copie des données vers lesquelles pointe le champ otherinfo de la struct keyctl_kdf_params
depuis l'espace utilisateur si le champ otherinfolen n'était pas zéro ;
- copie du résultat vers l'espace utilisateur.
EINVAL operation était KEYCTL_SETPERM et un bit de droit non valable a été indiqué dans arg3.
EINVAL operation était KEYCTL_SEARCH et la taille de la description (comprenant l'octet NULL de fin)
dépassait 4096 octets.
EINVAL la taille de la chaîne (y compris l'octet NULL final) indiquée dans arg3 (le type de clé) ou dans
arg4 (la description de la clé) dépassait les limites (respectivement 32 et 4096 octets).
EINVAL (avant Linux 4.12)
operation était KEYCTL_DH_COMPUTE, le paramètre arg5 n'était pas NULL.
EINVAL operation était KEYCTL_DH_COMPUTE et la taille de l’empreinte numérique de l'algorithme de hachage
fourni est de zéro.
EINVAL operation était KEYCTL_DH_COMPUTE et la taille du tampon fournie n'est pas suffisante pour
contenir le résultat. Mettez 0 en tant que taille de tampon pour obtenir la taille minimale du
tampon.
EINVAL operation était KEYCTL_DH_COMPUTE et le nom de hachage fourni dans le champ hashname de la struct
keyctl_kdf_params vers laquelle pointe le paramètre arg5 est trop grand (la limite est spécifique
à l'implémentation et varie entre les versions du noyau, mais elle est considérée comme suffisante
pour tous les noms d'algorithmes valables).
EINVAL operation était KEYCTL_DH_COMPUTE et le champ __spare de la struct keyctl_kdf_params fournie dans
le paramètre arg5 contient des valeurs autres que zéro.
EKEYEXPIRED
Une clé expirée a été trouvée ou spécifiée.
EKEYREJECTED
Une clé rejetée a été trouvée ou spécifiée.
EKEYREVOKED
Une clé révoquée a été trouvée ou spécifiée.
ELOOP operation était KEYCTL_LINK et le rattachement demandé ferait dépasser la profondeur maximale
d’imbrication des trousseaux.
EMSGSIZE
operation était KEYCTL_DH_COMPUTE et la longueur du tampon dépasse KEYCTL_KDF_MAX_OUTPUT_LEN (qui
est actuellement de 1024) ou le champ otherinfolen de la struct keyctl_kdf_parms fournie dans arg5
dépasse KEYCTL_KDF_MAX_OI_LEN (qui est actuellement de 64).
ENFILE (avant Linux 3.13)
operation était KEYCTL_LINK et le trousseau est complet (avant Linux 3.13, l'espace disponible de
stockage de rattachements de trousseaux était limité à une seule page mémoire ; depuis Linux 3.13,
il n'y a pas de limite fixée).
ENOENT operation était KEYCTL_UNLINK et la clé à détacher n'est pas rattachée au trousseau.
ENOENT operation était KEYCTL_DH_COMPUTE et l'algorithme de hachage indiqué dans le champ hashname de la
struct keyctl_kdf_params vers laquelle pointe le paramètre arg5 n'a pas été trouvé.
ENOENT operation était KEYCTL_RESTRICT_KEYRING et le type fourni dans le paramètre arg3 ne gère pas la
définition de restrictions de rattachement de clés.
ENOKEY Aucune clé correspondante n'a été trouvée, ou une clé non valable a été spécifiée.
ENOKEY La valeur KEYCTL_GET_KEYRING_ID était indiquée dans operation, la clé indiquée dans arg2
n'existait pas et arg3 valait zéro (ce qui veut dire ne pas créer de clé si elle n'existe pas).
ENOMEM Une des routines de l'allocation mémoire du noyau a échoué lors de l'exécution de l'appel système.
ENOTDIR
Une clé de type trousseau était attendue mais l'identifiant d'une clé de type différent a été
fourni.
EOPNOTSUPP
operation était KEYCTL_READ et le type de clé ne gère pas la lecture (par exemple, le type est
« login »).
EOPNOTSUPP
operation était KEYCTL_UPDATE et le type de clé ne gère pas les mises à jour.
EOPNOTSUPP
operation était KEYCTL_RESTRICT_KEYRING, le type fourni dans le paramètre arg3 était
« asymmetric », et la clé indiquée dans la spécification de la restriction fournie dans arg4 a un
autre type que « asymmetric » ou « keyring ».
EPERM operation était KEYCTL_GET_PERSISTENT, arg2 indiquait un identifiant utilisateur différent de
celui de l'utilisateur réel ou effectif du thread appelant, et l'appelant n'avait pas la capacité
CAP_SETUID.
EPERM operation était KEYCTL_SESSION_TO_PARENT et : soit tous les identifiants utilisateur (ou de
groupe) du processus parent ne correspondent pas à 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 à 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 était KEYCTL_DH_COMPUTE et l'initialisation des modules de chiffrement a dépassé le
délai.
VERSIONS
Une enveloppe est fournie dans la bibliothèque libkeyutils. (Le paquet accompagnant fournit le fichier
d'en-tête <keyutils.h>.) Cependant, plutôt que d'utiliser cet appel système directement, vous voudrez
probablement utiliser les fonctions de la bibliothèque mentionnées dans les descriptions des opérations
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 indiqué dans request_key(2), le programme request-key(8) est appelé avec les paramètres de la ligne
de commande qui décrivent une clé à instancier. Le programme exemple récupère et enregistre ces
arguments. Le programme endosse l'autorité d'instancier la clé demandée, puis il instancie cette clé.
La session d'interpréteur 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 désactivation temporaire du programme standard request-key(8) peut ne pas être sure sur
certains systèmes). Tant que notre programme exemple est installé, nous utilisons le programme exemple
présent dans request_key(2) pour demander une clé.
$ 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 clé est 20d035bf
$ sudo mv /sbin/request-key.backup /sbin/request-key
En regardant le fichier journal créé par ce programme, on peut voir les paramètres de la ligne de
commande fournis à 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 dernières lignes de la sortie ci-dessus montrent que le programme exemple a pu récupérer :
- la description de la clé à instanciée, qui incluait le nom de la clé (mykey) ;
- la charge utile de la clé d'autorisation, qui consistait dans des données (somepayloaddata) passées à
request_key(2) ;
- le trousseau de destination indiqué dans l'appel à request_key(2) ;
- la description de la clé d'autorisation où on peut voir que le nom de la clé correspond à
l'identifiant de celle à 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 été transcrit
dans l'identifiant du trousseau de destination (0256e6a6) affiché dans le fichier journal ci-dessus ; on
peut aussi voir la clé nouvellement créée 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 <errno.h>
#include <keyutils.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <time.h>
#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 paramètres au programme
* qu'il exécute ; les récupérer.
*/
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, "Paramètres 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'autorité pour instancier la clé nommée dans argv[2].
*/
if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == -1) {
fprintf(fp, "KEYCTL_ASSUME_AUTHORITY a échoué : %s\n",
strerror(errno));
exit(EXIT_FAILURE);
}
/*
* Récupérer la description de la clé à instancier.
*/
if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
dbuf, sizeof(dbuf)) == -1) {
fprintf(fp, "KEYCTL_DESCRIBE a échoué : %s\n", strerror(errno));
exit(EXIT_FAILURE);
}
fprintf(fp, "Description de clé : %s\n", dbuf);
/*
* Récupérer la charge utile de la clé d'autorisation, qui est en fait
* les données d'appel (callout) données à 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 échoué : %s\n", strerror(errno));
exit(EXIT_FAILURE);
}
auth_key_payload[akp_size] = '\0';
fprintf(fp, "Charge utile de la clé d'auth : %s\n", auth_key_payload);
/*
* Par intérêt, récupérer l'identifiant de la clé 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 échoué : %s\n",
strerror(errno));
exit(EXIT_FAILURE);
}
fprintf(fp, "Identifiant de la clé d'auth : %jx\n", (uintmax_t) auth_key);
/*
* Récupérer l'identifiant de clé 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 échoué : %s\n",
strerror(errno));
exit(EXIT_FAILURE);
}
fprintf(fp, "Trousseau de destination : %jx\n", (uintmax_t) dest_keyring);
/*
* Récupérer la description de la clé d'autorisation. Cela nous permet
* de voir le type de clé, l'identifiant utilisateur et de groupe, les
* droits et la description (nom) de la clé. Entre autres choses,
* on verra que le nom de la clé est une chaîne hexadécimale représentant
* l'identifiant de la clé à instancier.
*/
if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
dbuf, sizeof(dbuf)) == -1)
{
fprintf(fp, "KEYCTL_DESCRIBE a échoué : %s\n", strerror(errno));
exit(EXIT_FAILURE);
}
fprintf(fp, "Description de la clé d'auth : %s\n", dbuf);
/*
* Instancier la clé en utilisant les données de l'appel (callout)
* fournies dans la charge utile de la clé d'autorisation.
*/
if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
auth_key_payload, akp_size + 1, dest_keyring) == -1)
{
fprintf(fp, "KEYCTL_INSTANTIATE a échoué : %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 française de cette page de manuel a été créée par Christophe Blaess
<https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud
<tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard
<fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau
<jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François
<nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard
<simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot
<david@tilapin.org> et Jean-Philippe MENGUAL <jpmengual@debian.org>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License
version 3 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 à
debian-l10n-french@lists.debian.org.
Pages du manuel de Linux 6.9.1 15 juin 2024 keyctl(2)