keyctl(2) System Calls Manual keyctl(2) NOM keyctl - Manipuler la gestion des cles du noyau BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include /* Definition des constantes KEY* */ #include /* Definition des constantes SYS_* */ #include long syscall(SYS_keyctl, int op, ...); DESCRIPTION keyctl() permet aux programmes de l'espace utilisateur de manipuler des cles. L'operation qu'effectue keyctl() depend de la valeur du parametre op. Chacune de ces operations fait partie de l'enveloppe de la bibliotheque libkeyutils (fournie par le paquet keyutils) en tant que fonctions individuelles (voir keyctl(3)) pour permettre au compilateur de verifier les types. Les valeurs autorisees pour op sont : KEYCTL_GET_KEYRING_ID(2const) KEYCTL_JOIN_SESSION_KEYRING(2const) KEYCTL_UPDATE(2const) KEYCTL_REVOKE(2const) KEYCTL_CHOWN(2const) KEYCTL_SETPERM(2const) KEYCTL_DESCRIBE(2const) KEYCTL_CLEAR(2const) KEYCTL_LINK(2const) KEYCTL_UNLINK(2const) KEYCTL_SEARCH(2const) KEYCTL_READ(2const) KEYCTL_INSTANTIATE(2const) KEYCTL_INSTANTIATE_IOV(2const) KEYCTL_NEGATE(2const) KEYCTL_REJECT(2const) KEYCTL_SET_REQKEY_KEYRING(2const) KEYCTL_SET_TIMEOUT(2const) KEYCTL_ASSUME_AUTHORITY(2const) KEYCTL_GET_SECURITY(2const) KEYCTL_SESSION_TO_PARENT(2const) KEYCTL_INVALIDATE(2const) KEYCTL_GET_PERSISTENT(2const) KEYCTL_DH_COMPUTE(2const) KEYCTL_RESTRICT_KEYRING(2const) VALEUR RENVOYEE Pour qu'un appel reussisse, le code de retour depend de l'operation. 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. EDQUOT Le quota de cles de l'utilisateur appelant serait depasse si la cle etait creee ou ajoutee au trousseau. 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). 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. ENOKEY Aucune cle correspondante n'a ete trouvee, ou une cle non valable a ete specifiee. 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. 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. NORMES 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; Key ID is 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 Key description: user;1000;1000;3f010000;mykey Auth key payload: somepayloaddata Destination keyring: 256e6a6 Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf 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; /* Size of 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)); /* * The kernel passes a fixed set of arguments to the program * that it execs; fetch them. */ 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, "Command line arguments:\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"); /* * Assume the authority to instantiate the key named in argv[2]. */ if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == -1) { fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\n", strerror(errno)); exit(EXIT_FAILURE); } /* * Fetch the description of the key that is to be instantiated. */ if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate, dbuf, sizeof(dbuf)) == -1) { fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Key description: %s\n", dbuf); /* * Fetch the payload of the authorization key, which is * actually the callout data given to 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 failed: %s\n", strerror(errno)); exit(EXIT_FAILURE); } auth_key_payload[akp_size] = '\0'; fprintf(fp, "Auth key payload: %s\n", auth_key_payload); /* * For interest, get the ID of the authorization key and * display it. */ auth_key = keyctl(KEYCTL_GET_KEYRING_ID, KEY_SPEC_REQKEY_AUTH_KEY); if (auth_key == -1) { fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Auth key ID: %jx\n", (uintmax_t) auth_key); /* * Fetch key ID for the request_key(2) destination keyring. */ dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID, KEY_SPEC_REQUESTOR_KEYRING); if (dest_keyring == -1) { fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Destination keyring: %jx\n", (uintmax_t) dest_keyring); /* * Fetch the description of the authorization key. This * allows us to see the key type, UID, GID, permissions, * and description (name) of the key. Among other things, * we will see that the name of the key is a hexadecimal * string representing the ID of the key to be instantiated. */ if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY, dbuf, sizeof(dbuf)) == -1) { fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Auth key description: %s\n", dbuf); /* * Instantiate the key using the callout data that was supplied * in the payload of the authorization key. */ if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate, auth_key_payload, akp_size + 1, dest_keyring) == -1) { fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\n", strerror(errno)); exit(EXIT_FAILURE); } exit(EXIT_SUCCESS); } VOIR AUSSI keyctl(1), add_key(2), request_key(2), keyctl(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) The kernel source files under Documentation/security/keys/. 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.18 8 fevrier 2026 keyctl(2)