Man page - add_key(2)

Packages contains this manual

Package: manpages-dev
apt-get install manpages-dev

Manuals in package:

Available languages:

en fr ja ru

Manual

add_key

НАИМЕНОВАНИЕ
БИБЛИОТЕКА
ОБЗОР
ОПИСАНИЕ
Типы ключей
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
ОШИБКИ
СТАНДАРТЫ
ИСТОРИЯ
ПРИМЕЧАНИЯ
ПРИМЕРЫ
Исходный код программы
СМОТРИТЕ ТАКЖЕ
ПЕРЕВОД

НАИМЕНОВАНИЕ

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

БИБЛИОТЕКА

Стандартная библиотека языка C ( 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)).

Типы ключей

Значение type ключа представляет собой строку, которой определяется тип ключа. Внутри ядра определено несколько типов ключей, которые доступны в ядре кода управления ключами. В пользовательском пространстве в аргументе type при вызове add_key () можно использовать следующие значения:
"keyring"

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

"user"

Тип ключа общего назначения, чьи полезные данные можно читать и обновлять из пользовательских программ. Ключ полностью хранится в памяти ядра. Полезные данные ключей этого типа представляют собой данные произвольной структуры (blob) размером до 32767 байт.

"logon" (начиная с Linux 3.3)

This key type is essentially the same as "user" , but it does not permit the key to read. This is suitable for storing payloads that you do not want to be readable from user space.

Для данного типа ключа значение description должно уточняться префиксом «service», который в description отделяется символом «:» от остальных символов.
"big_key" (начиная с Linux 3.13)

This key type is similar to "user" , but may hold a payload of up to 1 MiB. If the key payload is large enough, then it may be stored encrypted in tmpfs (which can be swapped out) rather than kernel memory.

Дополнительную информацию об этих типах ключей смотрите в keyrings (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 was "logon" and the description was not qualified with a prefix string of the form "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"
ID ключа 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> и Kirill Rekhov <krekhov.dev@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков .