| request_key(2) | System Calls Manual | request_key(2) |
request_key - Demander une clé au gestionnaire de clés du noyau
Utilitaires de gestion de clefs Linux (libkeyutils, -lkeyutils)
#include <keyutils.h>
key_serial_t request_key(const char *type, const char *description,
const char *_Nullable callout_info,
key_serial_t dest_keyring);
request_key() essaie de trouver une clé d'un type donné, qui correspond à la description (au nom) spécifiée. Si aucune clé n'a pu être trouvée, la clé peut être créée. Si la clé a été trouvée ou créée, request_key() la rattache au trousseau dont l'identifiant est indiqué dans dest_keyring et il renvoie le numéro de série de la clé.
request_key() cherche une clé correspondant aux critères d'abord récursivement à l'intérieur des trousseaux attachés au processus appelant, dans l'ordre suivant : trousseau spécifique au thread, trousseau spécifique au processus, et enfin le trousseau de session.
Si request_key() est appelé depuis un programme lui-même appelé par request_key() au nom d'un autre processus afin de générer une clé, alors les trousseaux de cet autre processus seront ensuite parcourus en utilisant les identifiants d’utilisateur, de groupe, du groupe supplémentaire et le contexte de sécurité de ce processus.
La recherche dans l'arborescence d'un trousseau est de type parcours en largeur : une correspondance est d'abord recherchée avec toutes les clés d'un trousseau avant de chercher dans les trousseaux trouvés dans ce trousseau. Seules les clés et seuls les trousseaux pour lesquels le processus a l'autorisation search peuvent être examinés.
Si aucune clé n'est trouvée et si callout est NULL, l'appel échoue avec l'erreur ENOKEY.
Si aucune clé n'est trouvée et si callout n'est pas NULL, le noyau essaie d'appeler un programme de l'espace utilisateur pour instancier la clé. Les détails sont donnés ci-dessous.
Le numéro de série dest_keyring peut être celui d'un trousseau valable sur lequel l'appelant possède les droits en écriture ou il peut s'agir d'un des identifiants de trousseau spécial suivants :
Quand dest_keyring est indiqué comme 0 et qu'aucune construction de clé n'ait été effectuée, aucune édition de liens supplémentaire n'est effectuée.
Sinon, si dest_keyring est 0 et si une nouvelle clé est construite, la nouvelle clé sera attachée au trousseau par défaut. Plus précisément, quand le noyau essaie de déterminer le trousseau auquel rattacher la clé nouvellement créée, il essaie les trousseaux les uns à la suite des autres, en commençant par celui défini par l'opération KEYCTL_SET_REQKEY_KEYRING de keyctl(2), puis en continuant dans l'ordre ci-dessous jusqu'à ce qu'il trouve le premier trousseau existant :
Si l'opération KEYCTL_SET_REQKEY_KEYRING de keyctl(2) indique KEY_REQKEY_DEFL_DEFAULT (ou si aucune opération KEYCTL_SET_REQKEY_KEYRING n'est effectuée), le noyau cherche un trousseau à partir du début de la liste.
Si le noyau ne peut pas trouver de clé correspondant à type et à description et si callout n'est pas NULL, le noyau essaie d'appeler un programme de l'espace utilisateur pour instancier une clé au type et à la description donnés. Dans ce cas, les étapes suivantes sont suivies :
Si ces étapes ne réussissent pas, une erreur ENOKEY sera renvoyée à l'appelant de request_key() et une clé temporaire et instanciée de manière négative sera installée sur le trousseau indiqué par dest_keyring. Elle expirera après quelques secondes mais elle permettra aux appels suivants à request_key() d'échouer jusqu'à ce qu'elles réussissent. Le but de cette clé instanciée négativement est d'empêcher des processus (potentiellement différents) d'effectuer des demandes répétées (qui requièrent des appels request-key(8) coûteux) pour une clé qui ne peut pas être instanciée positivement (pour l'instant).
Une fois que la clé a été instanciée, la clé d'autorisation (KEY_SPEC_REQKEY_AUTH_KEY) est révoquée et le trousseau de destination (KEY_SPEC_REQUESTOR_KEYRING) n'est plus accessible au programme request-key(8).
Si une clé est créée, qu'elle soit valable ou instanciée négativement, elle remplacera toute autre clé possédant le même type et la même description dans le trousseau indiqué dans dest_keyring.
En cas de succès, request_key() renvoie le numéro de série de la clé trouvée ou créée. En cas d'erreur, la valeur -1 est renvoyée et errno est positionné pour indiquer l'erreur.
Cet appel système est apparu pour la première fois dans Linux 2.6.10. La possibilité d'instancier des clés à la demande a été ajoutée dans Linux 2.6.13.
Cet appel système est une extension Linux non standard.
Le programme ci-dessous montre l'utilisation de request_key(). Les paramètres type, description et callout_info pour l'appel système sont récupérés à partir des valeurs fournies dans les options de la ligne de commande. L'appel indique le trousseau de session en tant que trousseau cible.
Pour montrer ce programme, on crée d'abord une entrée adéquate dans /etc/request-key.conf.
$ sudo sh # echo 'création utilisateur mtk:* * /bin/keyctl instantiate %k %c %S' \
> /etc/request-key.conf # exit
Cette entrée indique que lorsqu'une nouvelle clé « utilisateur » avec le préfixe « mtk: » doit être instanciée, la tâche doit être effectuée par l'opération instantiate de la commande keyctl(1). Les paramètres fournis à l'opération instantiate sont : l'identifiant de la clé non instanciée (%k), les données de l'appel fournies à l'appel request_key() (%c) et le trousseau de session (%S) du demandeur (à savoir l'appelant de request_key()). Consulter request-key.conf(5) pour les détails de ces spécificateurs %.
Puis on lance le programme et on vérifie que le contenu de /proc/keys pour vérifier que la clé demandée a été instanciée :
$ ./t_request_key user mtk:key1 "Payload data" $ grep '2dddaf50' /proc/keys 2dddaf50 I--Q--- 1 perm 3f010000 1000 1000 user mtk:key1: 12
Pour un autre exemple d'utilisation de ce programme, voir keyctl(2).
/* t_request_key.c */
#include <keyutils.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
key_serial_t key;
if (argc != 4) {
fprintf(stderr, "Utilisation : %s type description données-appel\n",
argv[0]);
exit(EXIT_FAILURE);
}
key = request_key(argv[1], argv[2], argv[3],
KEY_SPEC_SESSION_KEYRING);
if (key == -1) {
perror("request_key");
exit(EXIT_FAILURE);
}
printf("L'identifiant de la clé est %jx\n", (uintmax_t) key);
exit(EXIT_SUCCESS);
}
keyctl(1), add_key(2), keyctl(2), keyctl(3), capabilities(7), keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user-session-keyring(7), request-key(8)
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 <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 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.
| 5 février 2023 | Pages du manuel de Linux 6.03 |