Provided by: manpages-fr-dev_4.13-4_all bug

NOM

       add_key - Ajouter une clé au gestionnaire de clés du noyau

SYNOPSIS

       #include <sys/types.h>
       #include <keyutils.h>

       key_serial_t add_key(const char *type, const char *description,
                            const void *payload, size_t plen,
                            key_serial_t keyring);

       Aucune enveloppe n'est fournie pour la glibc pour cet appel système ; voir les 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 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)).

   Types de clé
       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).

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,
       la valeur -1 est renvoyée et errno contient un code d'erreur approprié.

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 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.

VERSIONS

       Cet appel système est apparu pour la première fois dans Linux 2.6.10.

CONFORMITÉ

       Cet appel système est une extension Linux non standard.

NOTES

       Aucune enveloppe n'est fournie pour cet appel système dans glibc.  Une  enveloppe  est  fournie  dans  le
       paquet libkeyutils. 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 <sys/types.h>
       #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("add_key");
               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).

COLOPHON

       Cette page fait partie de la publication 5.10 du projet man-pages Linux. Une description du projet et des
       instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à
       l'adresse https://www.kernel.org/doc/man-pages/.

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 ⟨⟩.