add_key(2) System Calls Manual add_key(2)
NOM
add_key - Ajouter une clé au gestionnaire de clés du noyau
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#include <keyutils.h>
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 système dans la
glibc ; voir NOTES.
DESCRIPTION
add_key() crée ou met à jour une clé ayant un type et une description
donnés, l'instancie avec une charge utile (payload) de longueur plen,
l'attache au trousseau (keyring) spécifié, et renvoie son numéro de sé-
rie.
La clé peut être rejetée si les données fournies sont dans un mauvais
format ou si elles sont non valables de toute autre façon.
Si le trousseau (keyring) de destination contient déjà une clé avec ce
type et cette description, alors, si le type de la clé le permet, cette
clé sera mise à jour au lieu de créer une nouvelle clé. Dans le cas
contraire, une nouvelle clé sera créée, et le trousseau sera mis à jour
pour remplacer le lien vers l'ancienne clé par un lien vers la nou-
velle.
Le numéro de série du trousseau de destination peut être celui d'un
trousseau valable sur lequel l'appelant a le droit d'écriture. Il peut
aussi être un des identifiants spéciaux suivants :
KEY_SPEC_THREAD_KEYRING
Cela spécifie le trousseau spécifique aux processus légers
(thread-keyring(7)) de l'appelant.
KEY_SPEC_PROCESS_KEYRING
Cela spécifie le trousseau spécifique aux processus de l'appe-
lant (process-keyring(7)).
KEY_SPEC_SESSION_KEYRING
Cela spécifie le trousseau spécifique à la session de l'appelant
(session-keyring(7)).
KEY_SPEC_USER_KEYRING
Cela spécifie le trousseau spécifique à l'UID de l'appelant
(user-keyring(7)).
KEY_SPEC_USER_SESSION_KEYRING
Cela spécifie le trousseau spécifique à la session de l'UID de
l'appelant (user-session-keyring(7)).
Types de clé
Le type de clé est une chaîne qui indique le type de la clé. En in-
terne, le noyau définit un certain nombre de types de clé disponibles
au cœur du système de gestion des clés. Parmi les types disponibles
pour l'utilisateur que vous pouvez spécifier comme paramètre type de
add_key(), se trouvent :
"keyring"
Les trousseaux (keyring) sont des types de clé spéciaux qui
peuvent contenir des liens vers des séquences d'autres clés de
tout type. Si cette interface est utilisée pour créer un trous-
seau, alors l'argument payload doit valoir NULL, et plen doit
être zéro.
"user" Il s'agit d'un type de clé généraliste dont la charge utile peut
être lue et mise à jour par des applications de l'espace utili-
sateur. La clé est entièrement conservée dans la mémoire du
noyau. La charge utile pour les clés de ce type est un bloc de
données de votre choix jusqu'à 32 767 octets.
"logon" (depuis Linux 3.3)
Ce type de clé est pour l'essentiel le même que user, mais il ne
permet pas de lire la clé. Cela convient pour stocker les
charges utiles dont vous ne voulez pas que l'utilisateur puisse
lire.
Ce type de clé analyse une description en profondeur pour garantir
qu'elle est qualifiée par le préfixe d'un « service », en vérifiant que
la description contient un « : » précédé d’autres caractères.
"big_key" (depuis Linux 3.13)
Ce type de clé est similaire à user, mais il peut contenir une
charge utile jusqu'à 1 MiO. Si la charge utile de la clé est as-
sez grande, elle peut être stockée, chiffrée, dans tmpfs (qui
peut être mis sur l'espace d'échange) et non dans la mémoire du
noyau.
Pour plus de détails sur ces types de clé, voir keyrings(7).
VALEUR RENVOYÉE
En cas de succès, add_key() renvoie le numéro de série de la clé créée
ou mise à jour. En cas d'erreur, -1 est renvoyé et errno est positionné
pour indiquer l'erreur.
ERREURS
EACCES Le trousseau n'était pas disponible pour pouvoir être modifié
par l'utilisateur.
EDQUOT Le quota de clés de cet utilisateur serait dépassé si la clé
était créée ou ajoutée au trousseau.
EFAULT Un ou plusieurs type, description et payload (charge utile)
pointent à l'extérieur de l'espace d'adresses accessible au pro-
cessus.
EINVAL La longueur de la chaîne (y compris l'octet NULL final) spécifié
dans type ou description a dépassé la limite (respectivement 32
et 4096 octets).
EINVAL La charge utile (payload) n’est pas valable.
EINVAL type était logon et la description n'était pas qualifiée avec
une chaîne de préfixes sous la forme service:.
EKEYEXPIRED
Le trousseau a expiré.
EKEYREVOKED
Le trousseau a été révoqué.
ENOKEY Le trousseau n'existe pas.
ENOMEM Il n'y a pas assez de mémoire pour créer une clé.
EPERM type commençait par un point (« . »). Les types de clé commen-
çant par un point sont réservés à l'implémentation.
EPERM type valait keyring et la description commençait par un point
(« . »). Les trousseaux dont les descriptions (noms) commençant
par un point sont réservés à l'implémentation.
VERSIONS
Cet appel système est apparu pour la première fois dans Linux 2.6.10.
STANDARDS
Cet appel système est une extension Linux non standard.
NOTES
Aucune enveloppe n'est fournie pour cet appel système dans la glibc.
Une enveloppe est fournie dans le paquet libkeyutils (le paquet qui
l'accompagne fournit le fichier d'en-tête <keyutils.h>). Quand vous
utilisez l'enveloppe de cette bibliothèque, liez-la avec -lkeyutils.
EXEMPLES
Le programme ci-dessous crée une clé dont le type, la description et la
charge utile sont indiqués dans les paramètres de la ligne de commande,
puis il lie la clé au trousseau de la session. La session d'interpré-
teur suivante montre l'utilisation du programme :
$ ./a.out user mykey "Une charge utile"
Key ID is 64a4dca
$ grep '64a4dca' /proc/keys
064a4dca I--Q--- 1 perm 3f010000 1000 1000 user mykey: 12
Source du programme
#include <keyutils.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
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(
exit(EXIT_FAILURE);
}
printf("L'identifiant de la clé 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 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
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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.03 5 février 2023 add_key(2)
Generated by dwww version 1.15 on Sat Jun 29 01:32:45 CEST 2024.