add_key(2) System Calls Manual add_key(2) NOM add_key - Ajouter une cle au gestionnaire de cles du noyau BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include key_serial_t add_key(const char *type, const char *description, const void payload[.plen], size_t plen, key_serial_t keyring); Note : il n'existe pas d'enveloppe pour cet appel systeme dans la glibc ; voir NOTES. DESCRIPTION add_key() cree ou met a jour une cle ayant un type et une description donnes, l'instancie avec une charge utile (payload) de longueur plen, l'attache au trousseau (keyring) specifie, et renvoie son numero de serie. La cle peut etre rejetee si les donnees fournies sont dans un mauvais format ou si elles sont non valables de toute autre facon. Si le trousseau (keyring) de destination contient deja une cle avec ce type et cette description, alors, si le type de la cle le permet, cette cle sera mise a jour au lieu de creer une nouvelle cle. Dans le cas contraire, une nouvelle cle sera creee, et le trousseau sera mis a jour pour remplacer le lien vers l'ancienne cle par un lien vers la nouvelle. Le numero de serie du trousseau de destination peut etre celui d'un trousseau valable sur lequel l'appelant a le droit d'ecriture. Il peut aussi etre un des identifiants speciaux suivants : KEY_SPEC_THREAD_KEYRING Cela specifie le trousseau specifique aux processus legers (thread-keyring(7)) de l'appelant. KEY_SPEC_PROCESS_KEYRING Cela specifie le trousseau specifique aux processus de l'appelant (process-keyring(7)). KEY_SPEC_SESSION_KEYRING Cela specifie le trousseau specifique a la session de l'appelant (session-keyring(7)). KEY_SPEC_USER_KEYRING Cela specifie le trousseau specifique a l'UID de l'appelant (user-keyring(7)). KEY_SPEC_USER_SESSION_KEYRING Cela specifie le trousseau specifique a la session de l'UID de l'appelant (user-session-keyring(7)). Types de cle Le type de cle est une chaine qui indique le type de la cle. En interne, le noyau definit un certain nombre de types de cle disponibles au coeur du systeme de gestion des cles. Parmi les types disponibles pour l'utilisateur que vous pouvez specifier comme parametre type de add_key(), se trouvent : "keyring" Les trousseaux (keyring) sont des types de cle speciaux qui peuvent contenir des liens vers des sequences d'autres cles de tout type. Si cette interface est utilisee pour creer un trousseau, alors l'argument payload doit valoir NULL, et plen doit etre zero. "user" Il s'agit d'un type de cle generaliste dont la charge utile peut etre lue et mise a jour par des applications de l'espace utilisateur. La cle est entierement conservee dans la memoire du noyau. La charge utile pour les cles de ce type est un bloc de donnees de votre choix jusqu'a 32 767 octets. "logon" (depuis Linux 3.3) Ce type de cle est pour l'essentiel le meme que user, mais il ne permet pas de lire la cle. Cela convient pour stocker les charges utiles dont vous ne voulez pas que l'utilisateur puisse lire. Ce type de cle analyse une description en profondeur pour garantir qu'elle est qualifiee par le prefixe d'un << service >>, en verifiant que la description contient un << : >> precede d'autres caracteres. "big_key" (depuis Linux 3.13) Ce type de cle est similaire a user, mais il peut contenir une charge utile jusqu'a 1 MiO. Si la charge utile de la cle est assez grande, elle peut etre stockee, chiffree, dans tmpfs (qui peut etre mis sur l'espace d'echange) et non dans la memoire du noyau. Pour plus de details sur ces types de cle, voir keyrings(7). VALEUR RENVOYEE En cas de succes, add_key() renvoie le numero de serie de la cle creee ou mise a jour. En cas d'erreur, -1 est renvoye et errno est positionne pour indiquer l'erreur. ERREURS EACCES Le trousseau n'etait pas disponible pour pouvoir etre modifie par l'utilisateur. EDQUOT Le quota de cles de cet utilisateur serait depasse si la cle etait creee ou ajoutee au trousseau. EFAULT Un ou plusieurs type, description et payload (charge utile) pointent a l'exterieur de l'espace d'adresses accessible au processus. EINVAL La longueur de la chaine (y compris l'octet NULL final) specifie dans type ou description a depasse la limite (respectivement 32 et 4096 octets). EINVAL La charge utile (payload) n'est pas valable. EINVAL type etait logon et la description n'etait pas qualifiee avec une chaine de prefixes sous la forme service:. EKEYEXPIRED Le trousseau a expire. EKEYREVOKED Le trousseau a ete revoque. ENOKEY Le trousseau n'existe pas. ENOMEM Il n'y a pas assez de memoire pour creer une cle. EPERM type commencait par un point (<< . >>). Les types de cle commencant par un point sont reserves a l'implementation. EPERM type valait keyring et la description commencait par un point (<< . >>). Les trousseaux dont les descriptions (noms) commencant par un point sont reserves a l'implementation. STANDARDS Linux. HISTORIQUE Linux 2.6.10. NOTES Aucune enveloppe n'est fournie pour cet appel systeme dans la glibc. Une enveloppe est fournie dans le paquet libkeyutils (le paquet qui l'accompagne fournit le fichier d'en-tete ). Quand vous utilisez l'enveloppe de cette bibliotheque, liez-la avec -lkeyutils. EXEMPLES Le programme ci-dessous cree une cle dont le type, la description et la charge utile sont indiques dans les parametres de la ligne de commande, puis il lie la cle au trousseau de la session. La session d'interpreteur suivante montre l'utilisation du programme : $ ./a.out user mykey "Une charge utile" L'identifiant de la cle est is 64a4dca $ grep '64a4dca' /proc/keys 064a4dca I--Q--- 1 perm 3f010000 1000 1000 user mykey: 12 Source du programme #include #include #include #include #include int main(int argc, char *argv[]) { key_serial_t key; if (argc != 4) { fprintf(stderr, "Utilisation : %s type description charge_utile\n", argv[0]); exit(EXIT_FAILURE); } key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]), KEY_SPEC_SESSION_KEYRING); if (key == -1) { perror("add_key"); exit(EXIT_FAILURE); } printf("L'identifiant de la cle est %jx\n", (uintmax_t) key); exit(EXIT_SUCCESS); } VOIR AUSSI keyctl(1), keyctl(2), request_key(2), keyctl(3), keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user-session-keyring(7) Les fichiers Documentation/security/keys/core.rst et Documentation/keys/request-key.rst des sources du noyau (ou, avant Linux 4.13, Documentation/security/keys.txt et Documentation/security/keys-request-key.txt). TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Philippe MENGUAL Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 add_key(2)