ИМЯ¶

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

СИНТАКСИС¶

#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);

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

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

При успешном выполнении add_key() возвращается серийный номер созданного или изменённого ключа. При ошибке возвращается -1, а в errno содержится код ошибки.

ОШИБКИ¶

EACCES

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

EDQUOT

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

EFAULT

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

EINVAL

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

EINVAL

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

EINVAL

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

EKEYEXPIRED

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

EKEYREVOKED

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

ENOKEY

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

ENOMEM

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

EPERM

Значение type начинается с точки ('.'). Типы ключей, начинающиеся с точки, зарезервированы для использования в реализации.

EPERM

Значение type равно "keyring" и description начинается с точки ('.'). Связки ключей с описаниями (именами), которые начинаются с точки, зарезервированы для использования реализацией.

ВЕРСИИ¶

Этот системный вызов впервые появился в Linux 2.6.10.

СООТВЕТСТВИЕ СТАНДАРТАМ¶

Этот системный вызов является нестандартным расширением Linux.

ЗАМЕЧАНИЯ¶

В glibc нет обёрточной функции для этого системного вызова. Такая функция предоставляется пакетом libkeyutils. Для работы с функцией подключите библиотеку с помощью -lkeyutils.

ПРИМЕРЫ¶

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

$ ./a.out user mykey "Some payload"
ID ключа = 64a4dca
$ grep '64a4dca' /proc/keys
064a4dca I--Q---    1 perm 3f010000  1000  1000 user    mykey: 12

#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, "Использование: %s тип описание полезные_данные\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).

ЗАМЕЧАНИЯ¶

Эта страница является частью проекта Linux man-pages версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу https://www.kernel.org/doc/man-pages/.

ПЕРЕВОД¶

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

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

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