ИМЯ¶

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

ОБЗОР¶

#include <keyutils.h>

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

ОПИСАНИЕ¶

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

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

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

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

KEY_SPEC_THREAD_KEYRING

Задаёт связку ключей нити вызывающего процесса.

KEY_SPEC_PROCESS_KEYRING

Задаёт связку ключей процесса.

KEY_SPEC_SESSION_KEYRING

Задаёт связку ключей сеанса вызывающего процесса.

KEY_SPEC_USER_KEYRING

Задаёт связку ключей по UID вызывающего процесса.

KEY_SPEC_USER_SESSION_KEYRING

Задаёт связку ключей по UID сеанса вызывающего процесса.

ТИПЫ КЛЮЧЕЙ¶

В ядре кода управления ключами есть несколько типов; они могут указываться в этой функции:

user

Ключи определённых пользователем типов могут содержать двоичный набор произвольных данных, а в description можно указывать любую произвольную строку, хотя предпочтительнее, чтобы описание начиналось со строки, представляющей службу, для которой предназначен ключ и двоеточие (например, afs:mykey). Для ключей этого типа значение payload может быть пустым или NULL.

keyring

Связки ключей — это специальный тип ключей, который может содержать ссылки на цепочки других ключей любого типа. Если данный интерфейс используется для создания связки ключей, то payload должен быть NULL, а plen — ноль.

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

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

ОШИБКИ¶

ENOKEY

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

EKEYEXPIRED

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

EKEYREVOKED

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

EINVAL

Неправильные дополнительные данные.

ENOMEM

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

EDQUOT

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

EACCES

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

КОМПОНОВКА¶

Хотя это и системный вызов Linux, его нет в libc, но его можно найти в libkeyutils. При сборке программы компоновщику нужно указать параметр -lkeyutils.

СМОТРИТЕ ТАКЖЕ¶

keyctl(1), keyctl(2), request_key(2)