ИМЯ

add_key - добавить ключ в систему управления ключами ядра

LIBRARY

Standard C library (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);

Замечание: В glibc нет обёрточной функции для данного системного вызова; смотрите ЗАМЕЧАНИЯ.

ОПИСАНИЕ

Вызов add_key() создаёт или обновляет ключ заданного типа type с описанием description, конструирует его с полезными данными payload и длиной plen, присоединяет его к заданной связке ключей keyring и возвращает его серийный номер.

Ключ может быть отклонён, если его данные представлены в неправильном формате или возникла другая ошибка.

Если в указываемой связке ключей keyring уже есть ключ с таким же type и description то, если тип ключа это поддерживает, ключ будет обновлён, а не создан заново; если нет, то будет создан новый ключ (с другим идентификатором) и он вытеснит ссылку на существующий ключ из связки.

Связка ключей keyring может задаваться серийным номером действующей связки ключей, для которой у вызывающего есть права на запись. Или же это может быть один из следующих специальных идентификаторов связок ключей:

KEY_SPEC_THREAD_KEYRING

Связка ключей вызывающей нити (thread-keyring(7)).

KEY_SPEC_PROCESS_KEYRING

Связка ключей вызывающего процесса (process-keyring(7)).

KEY_SPEC_SESSION_KEYRING

Связка ключей сеанса вызывающего (session-keyring(7)).

KEY_SPEC_USER_KEYRING

Связка ключей по UID вызывающего (user-keyring(7)).

KEY_SPEC_USER_SESSION_KEYRING

Связка ключей по UID сеанса вызывающего (user-session-keyring(7)).

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

On success, add_key() returns the serial number of the key it created or updated. On error, -1 is returned and errno is set to indicate the error.

ОШИБКИ

EACCES

Изменение связки ключей пользователю недоступно.

EDQUOT

Квота на ключи для данного пользователя была бы превышена, если бы этот ключ создался или был бы прицеплен в связку ключей.

EFAULT

Значение одного или нескольких полей из type, description и payload указывают вне доступного адресного пространства процесса.

EINVAL

Размер строки (включая конечный байт null), заданной в type или description, превышает ограничение (32 байта и 4096 байт, соответственно).

EINVAL

Некорректное значение полезных данных.

EINVAL

Значение type равно "logon", но значение description не начинается строкой-префиксом в виде "service:".

EKEYEXPIRED

Срок службы связки ключей истёк.

EKEYREVOKED

Связка ключей отозвана.

ENOKEY

Связка ключей не существует.

ENOMEM

Недостаточно памяти для создания ключа.

EPERM

The type started with a period ('.'). Key types that begin with a period are reserved to the implementation.

EPERM

type was "keyring" and the description started with a period ('.'). Keyrings with descriptions (names) that begin with a period are reserved to the implementation.

СТАНДАРТЫ

Linux.

ИСТОРИЯ

Linux 2.6.10.

ЗАМЕЧАНИЯ

glibc does not provide a wrapper for this system call. A wrapper is provided in the libkeyutils library. (The accompanying package provides the <keyutils.h> header file.) When employing the wrapper in that library, link with -lkeyutils.

ПРИМЕРЫ

Программа, представленная ниже, создаёт ключ с типом, описанием и полезными данными, указанными в аргументах командной строки, и и цепляет этот ключ в связку ключей сеанса. Пример работы программы:

$ ./a.out user mykey "Some payload"
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, "Usage: %s type description payload\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("Key ID is %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)

Файлы исходного кода ядра Documentation/security/keys/core.rst и Documentation/keys/request-key.rst (или, до Linux 4.13, файлы Documentation/security/keys.txt и Documentation/security/keys-request-key.txt).

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Dmitry Bolkhovskikh <d20052005@yandex.ru> и Yuri Kozlov <yuray@komyakino.ru>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.