ОБЗОР
#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
- Изменение связки ключей пользователю недоступно.