add_key - Ajouter une clé au gestionnaire de clés du noyau
Bibliothèque C standard (
libc,
-lc)
#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.
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
nouvelle.
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'appelant ( 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)).
Le
type de clé est une chaîne qui indique le type de la
clé. En interne, 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 trousseau, 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 utilisateur. 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 assez 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).
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.
- 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 processus.
- 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.
Cet appel système est apparu pour la première fois dans
Linux 2.6.10.
Cet appel système est une extension Linux non standard.
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.
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
#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);
}
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).
La traduction française de cette page de manuel a été
créée par Christophe Blaess
<
https://www.blaess.fr/christophe/>, Stéphan Rafin
<
[email protected]>, Thierry Vignaud
<
[email protected]>, François Micaux, Alain Portal
<
[email protected]>, Jean-Philippe Guérard
<
[email protected]>, Jean-Luc Coulon (f5ibh)
<
[email protected]>, Julien Cristau
<
[email protected]>, Thomas Huriaux <
[email protected]>,
Nicolas François <
[email protected]>, Florentin
Duneau <
[email protected]>, Simon Paillard
<
[email protected]>, Denis Barbier
<
[email protected]>, David Prévot <
[email protected]> et
Jean-Philippe MENGUAL <
[email protected]>
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 à
[email protected]