.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2016 Michael Kerrisk .\" and Copyright (C) 2016 Eugene Syromyatnikov .\" A very few fragments remain from an earlier version of this page .\" written by David Howells (dhowells@redhat.com) .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH KEYCTL 2 "1 ноября 2020 г." Linux "Вызовы системы управления ключами Linux" .SH ИМЯ keyctl \- работа с системой управления ключами ядра .SH СИНТАКСИС .nf \fB#include \fP \fB#include \fP .PP \fBlong keyctl(int \fP\fIoperation\fP\fB, ...);\fP \fB/* для прямого вызова через syscall(2): */\fP \fB#include \fP \fB#include \fP \fB#include \fP .PP \fBlong syscall(__NR_keyctl, int \fP\fIoperation\fP\fB, __kernel_ulong_t \fP\fIarg2\fP\fB,\fP \fB __kernel_ulong_t \fP\fIarg3\fP\fB, __kernel_ulong_t \fP\fIarg4\fP\fB,\fP \fB __kernel_ulong_t \fP\fIarg5\fP\fB);\fP .fi .PP В glibc нет обёрточной функции для данного системного вызова; смотрите ЗАМЕЧАНИЯ. .SH ОПИСАНИЕ \fBkeyctl\fP() позволяет программам пользовательского пространства выполнять операции с ключами. .PP Операция, выполняемая \fBkeyctl\fP(), определяется значением аргумента \fIoperation\fP. Каждая операция обёрнута библиотекой \fIlibkeyutils\fP (из пакета \fIkeyutils\fP) в отдельную функцию (описаны далее), чтобы компилятор мог выполнять проверку типов. .PP Возможные значения \fIoperation\fP: .TP \fBKEYCTL_GET_KEYRING_ID\fP (начиная с Linux 2.6.10) Отобразить идентификатор специального ключа в идентификатор реального ключа для этого процесса. .IP Эта операция ищет специальный ключ, чей идентификатор указан в \fIarg2\fP (приводится к \fIkey_serial_t\fP). Если специальный ключ найден, то функция возвращает идентификатор соответствующего реального ключа. В аргументе \fIarg2\fP могут задаваться следующие значения: .RS .TP \fBKEY_SPEC_THREAD_KEYRING\fP Связка ключей вызывающей нити. Смотрите \fBthread\-keyring\fP(7). .TP \fBKEY_SPEC_PROCESS_KEYRING\fP Связка ключей вызывающего процесса. Смотрите \fBprocess\-keyring\fP(7). .TP \fBKEY_SPEC_SESSION_KEYRING\fP Связка ключей сеанса вызывающего. Смотрите \fBsession\-keyring\fP(7). .TP \fBKEY_SPEC_USER_KEYRING\fP Связка ключей по UID вызывающего. Смотрите \fBuser\-keyring\fP(7). .TP \fBKEY_SPEC_USER_SESSION_KEYRING\fP Связка ключей по UID сеанса вызывающего. Смотрите \fBuser\-session\-keyring\fP(7). .TP \fBKEY_SPEC_REQKEY_AUTH_KEY\fP (начиная с Linux 2.6.16) .\" commit b5f545c880a2a47947ba2118b2509644ab7a2969 Ключ авторизации, созданный \fBrequest_key\fP(2) и переданный процессу, который был создан для генерации ключа. Этот ключ доступен только в программах, подобных \fBrequest\-key\fP(8), которым передаётся ключ авторизации из ядра, и ключ становится недоступен сразу после того, как запрошенный ключ был инициализирован; смотрите \fBrequest_key\fP(2). .TP \fBKEY_SPEC_REQUESTOR_KEYRING\fP (начиная с Linux 2.6.29) .\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 Идентификатор связки ключей назначения у \fBrequest_key\fP(2). Эта связка ключей доступна только в программах, подобных \fBrequest\-key\fP(8), которым передаётся ключ авторизации из ядра, и ключ становится недоступен сразу после того, как запрошенный ключ был инициализирован; смотрите \fBrequest_key\fP(2). .RE .IP .\" The keyctl_get_keyring_ID.3 page says that a new key .\" "will be created *if it is appropriate to do so**. What is the .\" determiner for appropriate? .\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY .\" wouldn't get created but user/user-session/session keyring would .\" be created. Если ключ, указанный в \fIarg2\fP, не существует, то дальнейшая работа зависит от значения аргумента \fIarg3\fP (приводится к \fIint\fP). Если \fIarg3\fP содержит ненулевое значение, то — если так надлежит делать (например, когда ищется пользовательский, сеанса пользователя или сеансовый) — создаётся новый ключ и функция возвращает его реальный идентификатор. В противном случае, операция завершается ошибкой \fBENOKEY\fP. .IP Если в \fIarg2\fP задан действительный идентификатор ключа и ключ существует, то эта операция просто возвращает идентификатор ключа. Если ключ не существует, то вызов завершается ошибкой \fBENOKEY\fP. .IP Чтобы найти ключ вызывающий должен иметь право \fIпоиска\fP в связке ключей. .IP Аргументы \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_get_keyring_ID\fP(3). .TP \fBKEYCTL_JOIN_SESSION_KEYRING\fP (начиная с Linux 2.6.10) .\" This may be useful in conjunction with some sort of .\" session management framework that is employed by the application. Заменить связку ключей сеанса этого процесса новой связкой ключей сеанса. .IP Если \fIarg2\fP равно NULL, то создаётся анонимная связка ключей с описанием «_ses» и процесс подписывается на эту связку ключей как на свою связку ключей сеанса, вытесняя предыдущую связку ключей сеанса. .IP В противном случае, \fIarg2\fP (приводится к \fIchar\ *\fP) считается описанием (именем) связки ключей и происходит следующее: .RS .IP * 3 Если связка ключей с таким описанием существует, то процесс, если возможно, попытается подписаться на эту связку ключей как на сеансовую; если это невозможно, то возвращается ошибка. Чтобы подписаться на связку ключей, вызывающий должен иметь право \fIпоиска\fP в связке ключей. .IP * Если связка ключей с таким описанием не существует, то создаётся новая связка ключей с заданным описанием, и процесс подписывается на эту связку ключей как на сеансовую. .RE .IP Аргументы \fIarg3\fP, \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_join_session_keyring\fP(3). .TP \fBKEYCTL_UPDATE\fP (начиная с Linux 2.6.10) Изменить полезные данные ключа. .IP В аргументе \fIarg2\fP (приводится к \fIkey_serial_t\fP) указывается идентификатор изменяемого ключа. Аргумент \fIarg3\fP (приводится к \fIvoid\ *\fP) указывает на новые полезные данные, а в аргументе \fIarg4\fP (приводится к \fIsize_t\fP) содержится размер новых полезных данных в байтах. .IP Чтобы изменить ключ вызывающий должен иметь право \fIзаписи\fP в ключ, и запись должна поддерживаться типом ключа. .IP С помощью этой операции отрицательно инициализированный ключ (смотрите описание \fBKEYCTL_REJECT\fP) может быть положительно инициализирован. .IP Аргумент \fIarg5\fP игнорируется. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_update\fP(3). .TP \fBKEYCTL_REVOKE\fP (начиная с Linux 2.6.10) Отозвать ключ с идентификатором из аргумента \fIarg2\fP (приводится к \fIkey_serial_t\fP). Ключ планируется к удалению сборщиком мусора; его больше нельзя найти, и он недоступен для последующих операций. Дальнейшие попытки использования ключа будут приводить к ошибке \fBEKEYREVOKED\fP. .IP .\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM .\" error for KEYCTL_REVOKE. Does this need to be documented? .\" David Howells: No significance for user space. Вызывающий должен иметь право \fIзаписи\fP и \fIизменения атрибута\fP в ключе. .IP Аргументы \fIarg3\fP, \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_revoke\fP(3). .TP \fBKEYCTL_CHOWN\fP (начиная с Linux 2.6.10) Изменить владельца (идентификатор пользователя и группы) ключа. .IP В аргументе \fIarg2\fP (приводится к \fIkey_serial_t\fP) содержится идентификатор ключа. В аргументе \fIarg3\fP (приводится к \fIuid_t\fP) содержится идентификатор нового пользователя (или \-1, если идентификатор пользователя не меняется). В аргументе \fIarg4\fP (приводится к \fIgid_t\fP) содержится идентификатор новой группы (или \-1, если идентификатор группы не меняется). .IP Ключ должен давать разрешение на \fIизменения атрибута\fP вызывающему. .IP Для смены на новый UID или новый GID, если вызывающий не является её членом, у вызывающего должен быть мандат \fBCAP_SYS_ADMIN\fP (смотрите \fBcapabilities\fP(7)). .IP Если изменяется UID, то у нового пользователя должно быть достаточно квоты для принятия ключа. Уменьшение квоты будет удалено у старого пользователя, который заменяется на идентификатор нового пользователя. .IP Аргумент \fIarg5\fP игнорируется. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_chown\fP(3). .TP \fBKEYCTL_SETPERM\fP (начиная с Linux 2.6.10) Изменить права ключа с идентификатором из аргумента \fIarg2\fP (приводится к \fIkey_serial_t\fP) на права, указанные в аргументе \fIarg3\fP (приводится к \fIkey_perm_t\fP). .IP Если вызывающий не имеет мандата \fBCAP_SYS_ADMIN\fP, то он может изменять права только у ключей, которые ему принадлежат (точнее, UID файловой системы вызывающего должен совпадать с UID ключа). .IP .\" FIXME Above, is it really intended that a privileged process can't .\" override the lack of the 'setattr' permission? Ключ должен давать разрешение на \fIизменения атрибута\fP независимо от мандатов вызывающего. .IP Права \fIarg3\fP определяются маской доступных операций для каждой из следующих пользовательских категорий: .RS .TP \fIвладение\fP (начиная с Linux 2.6.14) .\" commit 664cceb0093b755739e56572b836a99104ee8a75 Это право предоставляется процессу, который владеет ключом (прицеплен с возможностью поиска к одной из связок ключей процесса); смотрите \fBkeyrings\fP(7). .TP \fIпользователь\fP Это право предоставляется процессу, чей UID файловой системы совпадает с UID ключа. .TP \fIгруппа\fP Это право предоставляется процессу, чей GID файловой системы или любой GID из дополнительных групп совпадает с GID ключа. .TP \fIостальные\fP Это право предоставляется остальным процессам, которые не относятся к к категориям \fIпользователь\fP и \fIгруппа\fP. .RE .IP Категории \fIпользователь\fP, \fIгруппа\fP и \fIостальные\fP взаимоисключающие: если процесс попадает в категорию \fIпользователь\fP, то он не получит прав, предоставленных для категории \fIгруппа\fP; если процесс попадает в категорию \fIпользователь\fP или \fIгруппа\fP, то он не получит прав, предоставляемых для категории \fIостальные\fP. .IP Категория \fIвладелец\fP предоставляет права, складываемые из прав категории \fIпользователь\fP, \fIгруппа\fP или \fIостальные\fP. .IP Каждая маска прав имеет размер в восемь бит, но используются только шесть. Доступные права: .RS .TP \fIпросмотр\fP Позволяет читать атрибуты ключа. .IP Это право требуется для операции \fBKEYCTL_DESCRIBE\fP. .IP Биты прав для каждой категории \fBKEY_POS_VIEW\fP, \fBKEY_USR_VIEW\fP, \fBKEY_GRP_VIEW\fP и \fBKEY_OTH_VIEW\fP. .TP \fIчтение\fP Позволяет читать полезные данные ключа. .IP Это право требуется для операции \fBKEYCTL_READ\fP. .IP Биты прав для каждой категории \fBKEY_POS_READ\fP, \fBKEY_USR_READ\fP, \fBKEY_GRP_READ\fP и \fBKEY_OTH_READ\fP. .TP \fIзапись\fP Позволяет изменять или добавлять полезные данные ключа. Для связки ключей позволяет добавление и удаление ключей из связки. .IP Это право требуется для операций \fBKEYCTL_UPDATE\fP, \fBKEYCTL_REVOKE\fP, \fBKEYCTL_CLEAR\fP, \fBKEYCTL_LINK\fP и \fBKEYCTL_UNLINK\fP. .IP Биты прав для каждой категории \fBKEY_POS_WRITE\fP, \fBKEY_USR_WRITE\fP, \fBKEY_GRP_WRITE\fP и \fBKEY_OTH_WRITE\fP. .TP \fIпоиск\fP Позволяет искать связки ключей и ключи. Поиск может быть рекурсивным только во вложенных связках, на которые есть право \fIпоиска\fP. .IP Это право требуется для операций \fBKEYCTL_GET_KEYRING_ID\fP, \fBKEYCTL_JOIN_SESSION_KEYRING\fP, \fBKEYCTL_SEARCH\fP и \fBKEYCTL_INVALIDATE\fP. .IP Биты прав для каждой категории \fBKEY_POS_SEARCH\fP, \fBKEY_USR_SEARCH\fP, \fBKEY_GRP_SEARCH\fP и \fBKEY_OTH_SEARCH\fP. .TP \fIсвязь\fP Позволяет прицеплять ключ или связку ключей. .IP Это право требуется для операций \fBKEYCTL_LINK\fP и \fBKEYCTL_SESSION_TO_PARENT\fP. .IP Биты прав для каждой категории \fBKEY_POS_LINK\fP, \fBKEY_USR_LINK\fP, \fBKEY_GRP_LINK\fP и \fBKEY_OTH_LINK\fP. .TP \fIsetattr\fP (начиная с Linux 2.6.15). Позволяет изменять UID, GID и маску прав ключа. .IP Это право требуется для операций \fBKEYCTL_REVOKE\fP, \fBKEYCTL_CHOWN\fP и \fBKEYCTL_SETPERM\fP. .IP Биты прав для каждой категории \fBKEY_POS_SETATTR\fP, \fBKEY_USR_SETATTR\fP, \fBKEY_GRP_SETATTR\fP и \fBKEY_OTH_SETATTR\fP. .RE .IP Для удобства, следующие макросы определены как маски всех бит прав для каждой пользовательской категории: \fBKEY_POS_ALL\fP, \fBKEY_USR_ALL\fP \fBKEY_GRP_ALL\fP и \fBKEY_OTH_ALL\fP. .IP Аргументы \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_setperm\fP(3). .TP \fBKEYCTL_DESCRIBE\fP (начиная с Linux 2.6.10) Получить строку, описывающую атрибуты указанного ключа. .IP Описываемый идентификатор ключа задаётся в \fIarg2\fP (приводится к \fIkey_serial_t\fP). Описывающая строка возвращается в буфере, на который указывает \fIarg3\fP (приводится к \fIchar\ *\fP); в \fIarg4\fP (приводится к \fIsize_t\fP) задаётся размер этого буфера в байтах. .IP Ключ должен давать вызывающему разрешение на \fIпросмотр\fP. .IP Возвращаемая строка оканчивается null и содержит следующую информацию о ключе: .IP .in +4n \fIтип\fP;\fIuid\fP;\fIgid\fP;\fIправа\fP;\fIописание\fP .in .IP Здесь \fIтип\fP и \fIописание\fP являются строками, \fIuid\fP и \fIgid\fP — десятичным числом в виде строки, а \fIправа\fP — шестнадцатеричной маской прав. Описывающая строка записывается в следующем формате: .IP %s;%d;%d;%08x;%s .IP .\" FIXME But, the kernel does not enforce the requirement .\" that the key description contains no semicolons! .\" So, user space has no guarantee here?? .\" Either something more needs to be said here, .\" or a kernel fix is required. \fBЗамечание: описывающая строка представлена в таком виде, чтобы её можно\fP \fBбыло расширить в будущих версиях ядра\fP. В частности, поле \fIописание\fP не будет содержать точек с запятой; его нужно отделять проходя с конца строки в поиске последней точки с запятой. Это позволяет вставить в будущих версиях новые поля. .IP .\" Function commentary says it copies up to buflen bytes, but see the .\" (buffer && buflen >= ret) condition in keyctl_describe_key() in .\" security/keyctl.c Запись в буфер производится только если \fIarg3\fP не равно NULL и указанный размер буфера достаточен для описывающей строки (включая конечный байт null). Чтобы понять, что буфер был мал, проверьте, что возвращаемое значение больше \fIarg4\fP. .IP Аргумент \fIarg5\fP игнорируется. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_describe\fP(3). .TP \fBKEYCTL_CLEAR\fP Стереть содержимое связки ключей (т. е., удалить из неё все ключи). .IP .\" or the error ENOTDIR results .\" According to Documentation/security/keys.txt: .\" This function can also be used to clear special kernel keyrings if they .\" are appropriately marked if the user has CAP_SYS_ADMIN capability. The .\" DNS resolver cache keyring is an example of this. Идентификатор ключа (должен иметь тип связки ключей) задаётся в \fIarg2\fP (приводится к \fIkey_serial_t\fP). .IP Вызывающий должен иметь право \fIзаписи\fP в связку ключей. .IP Аргументы \fIarg3\fP, \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_clear\fP(3). .TP \fBKEYCTL_LINK\fP (начиная с Linux 2.6.10) Прицепить ключ к связке ключей. .IP Прицепляемый ключ указывается в \fIarg2\fP (приводится к \fIkey_serial_t\fP); связка ключей указывается в \fIarg3\fP (приводится к \fIkey_serial_t\fP). .IP Если ключ с тем же типом и описанием уже прицеплен к связке ключей, то этот ключ отцепляется от связки ключей. .IP Перед созданием связи, ядро проверяет вложенность связок ключей и возвращает соответствующие ошибки, если связь создала был кольцо или если вложенность связок ключей слишком глубока (ограничение вложенности связок ключей определяется константой ядра \fBKEYRING_SEARCH_MAX_DEPTH\fP, равна 6 и это необходимо для предотвращения переполнения стека ядра при выполнении рекурсивного поиска в связках ключей). .IP Вызывающий должен иметь право \fIзацепки\fP (link) у добавляемого ключа и право \fIзаписи\fP у связки ключей. .IP Аргументы \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_link\fP(3). .TP \fBKEYCTL_UNLINK\fP (начиная с Linux 2.6.10) Отцепить ключ от связки ключей. .IP Идентификатор отцепляемого ключа указывается в \fIarg2\fP (приводится к \fIkey_serial_t\fP); идентификатор связки ключей, от которой отцепляется ключ, указывается в \fIarg3\fP (приводится к \fIkey_serial_t\fP). .IP Если ключ не прицеплен к связке ключей, то возвращается ошибка. .IP Вызывающий должен иметь право \fIзаписи\fP в связку ключей, из которой удаляется ключ. .IP Если удаляется последняя ссылка на ключ, то этот ключ планируется к уничтожению. .IP Аргументы \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_unlink\fP(3). .TP \fBKEYCTL_SEARCH\fP (начиная с Linux 2.6.10) Найти ключ в дереве связок ключей, вернуть его идентификатор и, при необходимости, прицепить его к заданной связке ключей. .IP Идентификатор начала дерева ключей, в котором производится поиск, задаётся в \fIarg2\fP (приводится к \fIkey_serial_t\fP). Поиск выполняется сначала вширь и рекурсивно. .IP В аргументах \fIarg3\fP и \fIarg4\fP задаётся искомый ключ: в \fIarg3\fP (приводится к \fIchar\ *\fP) содержится тип ключа (строка символов длиной до 32 байт с учётом конечного байта null), а в \fIarg4\fP (приводится к \fIchar\ *\fP) содержится описание ключа (строка символов до 4096 байт с учётом конечного байта null). .IP Связка ключей источник должна представлять право \fIпоиска\fP вызывающему. При выполнении рекурсивного поиска будут просматриваться только связки ключей, представляющие право \fIпоиска\fP вызывающему. Могут быть найдены только ключи, на которые у вызывающего есть право \fIпоиска\fP. .IP Если ключ найден, то его идентификатор возвращается как результат функции. .IP Если ключ найден и значение \fIarg5\fP (приводится к \fIkey_serial_t\fP) не равно нулю, то с теми же ограничениями и правилами как у \fBKEYCTL_LINK\fP ключ прицепляется в связку ключей, идентификатор которой указан в \fIarg5\fP. Если связка ключей назначения, указанная в \fIarg5\fP, уже содержит ключ того же типа и с тем же описанием, то связь будет замещена новой с ключом, найденным этой операцией. .IP Вместо корректных существующих идентификаторов связок ключей источника (\fIarg2\fP) и приёмника (\fIarg5\fP) можно указывать специальные идентификаторы связок ключей, описанных в \fBKEYCTL_GET_KEYRING_ID\fP. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_search\fP(3). .TP \fBKEYCTL_READ\fP (начиная с Linux 2.6.10) Прочитать полезные данные ключа. .IP .\" including KEY_SPEC_REQKEY_AUTH_KEY Идентификатор ключа, из которого читаются полезные данные, задаётся в \fIarg2\fP (приводится к \fIkey_serial_t\fP). Это может быть идентификатор существующего ключа или любой специальный идентификатор ключа, описанный в \fBKEYCTL_GET_KEYRING_ID\fP. .IP Полезные данные помещаются в буфер, указываемый в \fIarg3\fP (приводится к \fIchar\ *\fP); размер буфера должен быть указан в \fIarg4\fP (приводится к \fIsize_t\fP). .IP Возвращаемые данные будут обработаны для представления согласно типу ключа. Например, связка ключей будет возвращена как массив элементов \fIkey_serial_t\fP, представляющих идентификаторы всех ключей связки. Данные типа ключа \fIuser\fP будут возвращены как есть. Если для типа ключа эта функция не реализована, то операция завершается ошибкой \fBEOPNOTSUPP\fP. .IP Если \fIarg3\fP не равно NULL, то копируется столько полезных данных сколько вмещается в буфер. При успешном выполнении возвращаемое значение всегда равно полному размеру полезных данных. Чтобы удостовериться что буфер был достаточного размера, убедитесь, что возвращаемое значение меньше или равно значению, указанному в \fIarg4\fP. .IP Ключ должен предоставлять вызывающему право \fIчтения\fP или \fIпоиска\fP, если поиск ведётся из связки ключей процесса (т. е., это обладатель ключа). .IP Аргумент \fIarg5\fP игнорируется. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_read\fP(3). .TP \fBKEYCTL_INSTANTIATE\fP (начиная с Linux 2.6.10) Положительно инициализировать неинициализированный ключ заданными полезными данными. .IP Идентификатор инициализированного ключа задаётся в \fIarg2\fP (приводится к \fIkey_serial_t\fP). .IP Полезные данные ключа задаются в буфере, указанном в \fIarg3\fP (приводится к \fIvoid\ *\fP); размер буфера задаётся в \fIarg4\fP (приводится к \fIsize_t\fP). .IP Ссылка на полезные данные может быть равна NULL и размер буфера может равняться 0, если это поддерживается типом ключа (например, если это связка ключей). .IP Операция может завершиться с ошибкой, если полезные данные заданы в неправильном формате или содержат ошибки. .IP Если \fIarg5\fP (приводится к \fIkey_serial_t\fP) не равно нулю, то с теми же ограничениями и правилами как у \fBKEYCTL_LINK\fP инициализированный ключ прицепляется в связку ключей, идентификатор которой указан в \fIarg5\fP. .IP Вызывающий должен иметь соответствующий ключ авторизации и после инициализации ключа ключ авторизации отзывается. Иначе говоря, эта операция доступна только из программ, подобных \fBrequest\-key\fP(8). В \fBrequest_key\fP(2) смотрите описание неинициализированных ключей и их инициализацию. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_instantiate\fP(3). .TP \fBKEYCTL_NEGATE\fP (начиная с Linux 2.6.10) Отрицательно инициализировать неинициализированный ключ. .IP Данная операция эквивалентен вызову: .IP keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4); .IP Аргумент \fIarg5\fP игнорируется. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_negate\fP(3). .TP \fBKEYCTL_SET_REQKEY_KEYRING\fP (начиная с Linux 2.6.13) .\" I.e., calls to the kernel's internal request_key() interface, .\" which is distinct from the request_key(2) system call (which .\" ultimately employs the kernel-internal interface). Задать связку ключей по умолчанию, в которую будут цепляться неявно запрашиваемые ключи для этой нити, и вернуть предыдущее значение. Неявные запросы ключа делаются внутренними компонентами ядра, такое может происходить, например, при открытии файлов в файловой системе AFS или NFS. Задание связки ключей по умолчанию также учитывается при запросе ключа из пользовательского пространства; подробности смотрите в \fBrequest_key\fP(2). .IP В аргументе \fIarg2\fP (приводится к \fIint\fP) должно содержаться одно из следующих значений, задающих новую связку ключей по умолчанию: .RS .TP \fBKEY_REQKEY_DEFL_NO_CHANGE\fP Не изменять связку ключей по умолчанию. Используется для определения текущей связки ключей по умолчанию (без её изменения). .TP \fBKEY_REQKEY_DEFL_DEFAULT\fP Применить действие по умолчанию, то есть использовать связку ключей, привязанную к нити, если есть, в противном случае привязанную к процессу, если есть, иначе привязанную к сеансу, если есть, иначе привязанную к сеансу UID, иначе привязанную к пользователю. .TP \fBKEY_REQKEY_DEFL_THREAD_KEYRING\fP В качестве новой связки ключей по умолчанию использовать связку ключей нити (\fBthread\-keyring\fP(7)). .TP \fBKEY_REQKEY_DEFL_PROCESS_KEYRING\fP В качестве новой связки ключей по умолчанию использовать связку ключей процесса (\fBprocess\-keyring\fP(7)). .TP \fBKEY_REQKEY_DEFL_SESSION_KEYRING\fP В качестве новой связки ключей по умолчанию использовать связку ключей сеанса (\fBsession\-keyring\fP(7)). .TP \fBKEY_REQKEY_DEFL_USER_KEYRING\fP В качестве новой связки ключей по умолчанию использовать связку ключей UID (\fBuser\-keyring\fP(7)). .TP \fBKEY_REQKEY_DEFL_USER_SESSION_KEYRING\fP В качестве новой связки ключей по умолчанию использовать связку ключей UID сеанса (\fBuser\-session\-keyring\fP(7)). .TP \fBKEY_REQKEY_DEFL_REQUESTOR_KEYRING\fP (начиная с Linux 2.6.29) .\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 .\" FIXME The preceding explanation needs to be expanded. .\" Is the following correct: .\" .\" The requestor keyring is the dest_keyring that .\" was supplied to a call to request_key(2)? .\" .\" David Howells said: to be checked Использовать связку ключей запрашивающего. .RE .IP .\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING) Любые другие значения недопустимы. .IP Аргументы \fIarg3\fP, \fIarg4\fP и \fIarg5\fP игнорируются. .IP Параметр, контролируемый данной операцией, наследуется потомком при \fBfork\fP(2) и сохраняется при \fBexecve\fP(2). .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_set_reqkey_keyring\fP(3). .TP \fBKEYCTL_SET_TIMEOUT\fP (начиная с Linux 2.6.16) Назначить время ожидания ключа. .IP Идентификатор ключа задаётся в \fIarg2\fP (приводится к \fIkey_serial_t\fP). Время ожидания в секундах отсчитывается от текущего времени и задаётся в \fIarg3\fP (приводится к \fIunsigned int\fP). Время ожидания изменяется по часам реального времени. .IP Значение времени ожидания 0 очищается существующее ожидание ключа. .IP В файле \fI/proc/keys\fP показывается оставшееся время до момента просрочки каждого ключа (это единственной способ узнать время ожидания ключа). .IP Вызывающий должен иметь право \fIизменения атрибута\fP в ключе или быть держателем авторизационного токена инициализации ключа (смотрите \fBrequest_key\fP(2)). .IP Ключ и все ссылки на него будут автоматически удалены сборщиком мусора после истечения времени ожидания. Последующие попытки доступа к ключу будут завершаться ошибкой \fBEKEYEXPIRED\fP. .IP Данную операцию невозможно применить для задания ожидания отозванного, просроченного или отрицательно инициализированного ключа. .IP Аргументы \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_set_timeout\fP(3). .TP \fBKEYCTL_ASSUME_AUTHORITY\fP (начиная с Linux 2.6.16) Выдать (или отозвать) право вызывающей нити на инициализацию ключа. .IP В аргументе \fIarg2\fP (приводится к \fIkey_serial_t\fP) указывается ненулевое идентификатор ключа для выдачи права допуска или 0 для отмены права допуска. .IP Если \fIarg2\fP не равно нулю, то будет выдано право допуска к указанному идентификатору неинициализированного ключа. Далее этот ключ может быть инициализирован посредством операций \fBKEYCTL_INSTANTIATE\fP, \fBKEYCTL_INSTANTIATE_IOV\fP, \fBKEYCTL_REJECT\fP или \fBKEYCTL_NEGATE\fP. После инициализации ключа, у нити автоматически отменяется право доступа для инициализации ключа. .IP Право доступа на ключ может быть выдано только, если вызывающая нить содержит в своих связках ключей ключ авторизации, который связан с указанным ключом (иначе говоря, операция \fBKEYCTL_ASSUME_AUTHORITY\fP доступна только из программ, подобных \fBrequest\-key\fP(8); в \fBrequest_key\fP(2) смотрите описание как используется эта операция). Вызывающий должен иметь право \fIпоиска\fP ключа авторизации. .IP Если указанный ключ совпадает с ключом авторизации, то возвращается идентификатор этого ключа. Ключ авторизации можно прочитать (\fBKEYCTL_READ\fP) для получения исходящей информации, переданной в \fBrequest_key\fP(2). .IP Если идентификатор в \fIarg2\fP равен 0, то имеющееся в настоящее время право выдачи очищается (отменяется и возвращается 0. .IP Механизм \fBKEYCTL_ASSUME_AUTHORITY\fP позволяет программе, такой как \fBrequest\-key\fP(8) выдать необходимые права для инициализации нового неинициализированного ключа, который был создан предшествующим вызовом \fBrequest_key\fP(2). Дополнительную информацию смотрите в \fBrequest_key\fP(2) и в файле исходного кода ядра \fIDocumentation/security/keys\-request\-key.txt\fP. .IP Аргументы \fIarg3\fP, \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_assume_authority\fP(3). .TP \fBKEYCTL_GET_SECURITY\fP (начиная с Linux 2.6.26) .\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d Получить метку безопасности LSM (модуль безопасности Linux) указанного ключа. .IP В \fIarg2\fP (приводится к \fIkey_serial_t\fP) задаётся идентификатор ключа, чью метку безопасности нужно получить. Метка безопасности (завершается байтом null) будет помещена в буфер, указанный в аргументе \fIarg3\fP (приводится к \fIchar\ *\fP); размер буфера должен быть указан в \fIarg4\fP (приводится к \fIsize_t\fP). .IP Если \fIarg3\fP равно NULL или размер буфера, указанный в \fIarg4\fP, мал, то в качестве результата функции возвращается полный размер строки метки безопасности (включая конечный байт null) и в буфер ничего не копируется. .IP Вызывающий должен иметь право \fIпросмотра\fP указанного ключа. .IP Возвращаемая строка метки безопасности имеет формат, определяемый в соответствии с действующим LSM. Например, при используемом SELinux она может выглядеть так: .IP unconfined_u:unconfined_r:unconfined_t:s0\-s0:c0.c1023 .IP Если в данный момент LSM не работает, то в буфер помещается пустая строка. .IP Аргумент \fIarg5\fP игнорируется. .IP Эта операция доступна в \fIlibkeyutils\fP через функции \fBkeyctl_get_security\fP(3) и \fBkeyctl_get_security_alloc\fP(3). .TP \fBKEYCTL_SESSION_TO_PARENT\fP (начиная с Linux 2.6.32) .\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f .\" What is the use case for KEYCTL_SESSION_TO_PARENT? .\" David Howells: the Process Authentication Groups people requested this, .\" but then didn't use it; maybe there are no users. Заменить связку ключей сеанса у \fIродителя\fP вызывающего процесса на связку ключей сеанса вызывающего процесса. .IP Связка ключей родительского процесса будет заменена в момент следующего перехода родителя из пространства ядра в пространство пользователя. .IP Связка ключей должна существовать и позволять вызывающему выполнять \fIсцепку\fP. Родительский процесс должен быть с одной нитью и иметь те же действующие права как этот процесс и не быть set\-user\-ID или set\-group\-ID. UID связки ключей сеанса родительского процесса (если есть), а также UID связки ключей сеанса вызывающего должны совпадать с действующим UID вызывающего. .IP Факт того, что эта операция затрагивает родительский процесс, позволяет программе, такой как оболочка, запускать дочерний процесс, который с помощью этой операции изменит связку ключей сеанса оболочки (это то, что делает команда \fBnew_session\fP \fBkeyctl\fP(1)). .IP Аргументы \fIarg2\fP, \fIarg3\fP, \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_session_to_parent\fP(3). .TP \fBKEYCTL_REJECT\fP (начиная с Linux 2.6.39) .\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c Пометить ключ как отрицательно инициализированный и задать таймер действия ключа. Эта операция предоставляет собой надмножество возможности операции \fBKEYCTL_NEGATE\fP, представленной ранее. .IP Идентификатор отрицательно инициализируемого ключа указывается в \fIarg2\fP (приводится к \fIkey_serial_t\fP). В \fIarg3\fP (приводится к \fIunsigned int\fP) указывается срок жизни ключа в секундах. В \fIarg4\fP (приводится к \fIunsigned int\fP) указывается ошибка, возвращаемая при нахождении этого ключа — обычно равно \fBEKEYREJECTED\fP, \fBEKEYREVOKED\fP или \fBEKEYEXPIRED\fP. .IP Если \fIarg5\fP (приводится к \fIkey_serial_t\fP) не равно нулю, то с теми же ограничениями и правилами как у \fBKEYCTL_LINK\fP отрицательно инициализированный ключ прицепляется в связку ключей, идентификатор которой указан в \fIarg5\fP. .IP Вызывающий должен иметь соответствующий ключ авторизации. Иначе говоря, эта операция доступна только из программ, подобных \fBrequest\-key\fP(8). Смотрите \fBrequest_key\fP(2). .IP Вызывающий должен иметь соответствующий ключ авторизации и после инициализации ключа ключ авторизации отзывается. Иначе говоря, эта операция доступна только из программ, подобных \fBrequest\-key\fP(8). В \fBrequest_key\fP(2) смотрите описание неинициализированных ключей и их инициализацию. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_reject\fP(3). .TP \fBKEYCTL_INSTANTIATE_IOV\fP (начиная с Linux 2.6.39) .\" commit ee009e4a0d4555ed522a631bae9896399674f063 Инициализировать неинициализированный ключ заданными полезными данными, указанными в векторе буферов. .IP Эта операция подобна \fBKEYCTL_INSTANTIATE\fP, но полезные данные указываются в виде массива структур \fIiovec\fP: .IP .in +4n .EX struct iovec { void *iov_base; /* начальный адрес буфера */ size_t iov_len; /* размер буфера (в байтах) */ }; .EE .in .IP Указатель на вектор полезных данных передаётся в \fIarg3\fP (приводится к \fIconst struct iovec\ *\fP). Количество элементов в векторе задаётся в \fIarg4\fP (приводится к \fIunsigned int\fP). .IP Значение аргумента \fIarg2\fP (идентификатор ключа) и \fIarg5\fP (идентификатор связки ключей) рассматриваются также как у \fBKEYCTL_INSTANTIATE\fP. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_instantiate_iov\fP(3). .TP \fBKEYCTL_INVALIDATE\fP (начиная с Linux 3.5) .\" commit fd75815f727f157a05f4c96b5294a4617c0557da Пометить ключ как недействительный. .IP Идентификатор ключа, отмечаемого недействительным, задаётся в \fIarg2\fP (приводится к \fIkey_serial_t\fP). .IP .\" CAP_SYS_ADMIN is permitted to invalidate certain special keys Чтобы сделать ключ недействительным, вызывающий должен иметь на ключ право \fIпоиска\fP. .IP Эта операция помечает ключ как недействительный и планирует его к немедленной сборке мусорщиком. Сборщик мусора удаляет недействительный ключ из всех связок ключей и удаляет ключ после того, как количество ссылок на него станет равным 0. После этой операции ключ будет игнорироваться при поиске, даже если он ещё не удалён. .IP Ключи, помеченный как недействительные, сразу становятся невидимыми для обычных операций с ключами, хотя их видно в \fI/proc/keys\fP (отмечены флагом «i») до действительного удаления. .IP Аргументы \fIarg3\fP, \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_invalidate\fP(3). .TP \fBKEYCTL_GET_PERSISTENT\fP (начиная с Linux 3.13) .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e Получить постоянную связку ключей (\fBpersistent\-keyring\fP(7)) заданного пользователя и прицепить её к указанную связку ключей. .IP Идентификатор пользователя указывается в \fIarg2\fP (приводится к \fIuid_t\fP). Если указано значение \-1, то используется реальный идентификатор пользователя вызывающего. Идентификатор связки ключей назначения указывается в \fIarg3\fP (приводится к \fIkey_serial_t\fP). .IP Вызывающий должен иметь мандат \fBCAP_SETUID\fP в своём пространстве имён пользователя чтобы получить постоянную связку ключей для идентификатора пользователя, который не совпадает с реальным или действующим идентификатора пользователя вызывающего. .IP При успешном выполнении вызова добавляет ссылка на постоянную связку ключей в связку ключей с идентификатором, указанном \fIarg3\fP. .IP Вызывающий должен иметь право \fIзаписи\fP в связку ключей. .IP Если постоянная связка ключей не существует, то она будет создана ядром. .IP Каждый раз при выполнении операции \fBKEYCTL_GET_PERSISTENT\fP срок действия постоянной связки ключей сбрасывается в значение: .IP .in +4n .EX /proc/sys/kernel/keys/persistent_keyring_expiry .EE .in .IP По истечению срока действия постоянная связка ключей удаляется и все ссылки на неё затем удаляются сборщиком мусора. .IP Постоянные связки ключей были добавлены в ядро Linux версии 3.13. .IP Аргументы \fIarg4\fP и \fIarg5\fP игнорируются. .IP Эта операция доступна в \fIlibkeyutils\fP через функцию \fBkeyctl_get_persistent\fP(3). .TP \fBKEYCTL_DH_COMPUTE\fP (начиная с Linux 4.7) .\" commit ddbb41148724367394d0880c516bfaeed127b52e Вычислить открытый и закрытый ключ Диффи\-Хеллмана, возможно применяя к результату функцию формирования ключа (key derivation function, KDF). .IP В аргументе \fIarg2\fP передаётся указатель на набор параметров, содержащих серийные номера трёх ключей \fI"user"\fP, используемых в вычислении Диффи\-Хеллмана, упакованных в следующую структуру: .IP .in +4n .EX struct keyctl_dh_params { int32_t private; /* локальный закрытый ключ */ int32_t prime; /* основание, известное обеим сторонам */ int32_t base; /* базовое целое: из общего генератора или из открытого ключа удалённой стороны */ }; .EE .in .IP Для каждого из трёх указанных в структуре ключей у вызывающего должно быть право на \fIчтение\fP. Полезные данные этих ключей используются для вычисления результата Диффи\-Хеллмана по формуле: .IP база \(ha закрытый mod основание .IP Если база это общий генератор, то результатом будет локальный открытый ключ. Если база это открытый ключ удалённой стороны, то результатом будет общий закрытый ключ. .IP Аргумент \fIarg3\fP (приводится к \fIchar\ *\fP) указывает на буфер, в который помещается результат вычисления. Размер буфера задаётся в \fIarg4\fP (приводится к \fIsize_t\fP). .IP Буфер должен быть достаточного размера для хранения выходных данных, в противном случае возвращается ошибка. Если значение \fIarg4\fP равно нулю, то буфер не используется и операция возвращает минимально требуемый размер буфера (т. е., длину основания). .IP Вычисления Диффи\-Хеллмана можно выполнять в пространстве пользователя, но требуется библиотека целых чисел многократной точности (MPI). Помещение реализации в ядро даёт доступ к реализации MPI ядра и позволяет использовать аппаратуру шифрования и ускорения. .IP .\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8 Добавление поддержки вычисления DH в системный вызов \fBkeyctl\fP() считается хорошим решением, так как алгоритм DH используется для получения общих ключей; также для типа ключа можно задать подходящую реализацию DH (программную или аппаратную). .IP Если аргумент \fIarg5\fP равен \fBNULL\fP, то возвращается сам результат DH. В противном случае (начиная с Linux 4.12), значение равно указателю на структуру, в которой задаются параметры для применения в операции KDF: .IP .in +4n .EX struct keyctl_kdf_params { char *hashname; /* имя алгоритма хэширования */ char *otherinfo; /* SP800\-56A OtherInfo */ __u32 otherinfolen; /* размер данных otherinfo */ __u32 __spare[8]; /* зарезервировано */ }; .EE .in .IP В поле \fIhashname\fP содержится строка, завершающаяся null, которой задаётся имя хэша (доступно в программном интерфейсе шифрования ядра; список хэшей сложно описать; в файле .UR https://www.kernel.org\:/doc\:/html\:/latest\:/crypto\:/architecture.html «Kernel Crypto API Architecture» .UE можно найти как компонуются имена хэшей из алгоритмов шифрования и шаблонов с типом \fBCRYPTO_ALG_TYPE_SHASH\fP с учётом доступного исходного кода ядра и настроек) для применения к результату DH в операции KDF. .IP Поле \fIotherinfo\fP содержит данные \fIOtherInfo\fP, описанные в SP800\-56A, раздел 5.8.1.2, зависящие от алгоритма. Эти данные объединяются с результатом операции DH и предоставляются как входные операции KDF. Его размер указывается в поле \fIotherinfolen\fP и ограничивается константой \fBKEYCTL_KDF_MAX_OI_LEN\fP, которая определена в \fIsecurity/keys/internal.h\fP и равна 64. .IP .\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 Поле \fB__spare\fP в настоящее время не используется. Оно игнорировалось до Linux 4.13 (но всё равно доступно из пользовательского пространства, так как копируется в ядро), и, начиная с Linux 4.13, должно содержать нули. .IP Реализация KDF соответствует SP800\-56A, а также SP800\-108 (счётчик KDF). .IP .\" keyutils commit 742c9d7b94051d3b21f9f61a73ed6b5f3544cb82 .\" keyutils commit d68a981e5db41d059ac782071c35d1e8f3aaf61c Эта операция доступна в \fIlibkeyutils\fP (начиная с версии 1.5.10) через функции \fBkeyctl_dh_compute\fP(3) и \fBkeyctl_dh_compute_alloc\fP(3). .TP \fBKEYCTL_RESTRICT_KEYRING\fP (начиная с Linux 4.12) .\" commit 6563c91fd645556c7801748f15bc727c77fcd311 .\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9 Применить ограничение прицепить ключ к связке ключей с идентификатором, указанном в \fIarg2\fP (приводится к типу \fIkey_serial_t\fP). Вызывающий должен иметь право \fIsetattr\fP на ключ. Если \fIarg3\fP равно NULL, то все попытки добавить ключ в связку ключей блокируются; в противном случае он содержит указатель на строку с именем типа ключа, а в аргументе \fIarg4\fP содержится указатель на строку, описывающую ограничения, присущие типу. В Linux 4.12 из ограничений определено только «asymmetric»: .RS .TP \fBbuiltin_trusted\fP Позволить прицеплять во встроенную связку ключей («.builtin_trusted_keys») только ключи, которые подписаны ключом. .TP \fBbuiltin_and_secondary_trusted\fP Позволить прицеплять во вторичную связку ключей («.secondary_trusted_keys») только ключи, которые подписаны ключом, или как расширение, ключ во встроенную связку ключей, поскольку последний присоединен с первой. .TP \fBключ_или_связка:\fP\fIключ\fP .TQ \fBключ_или_связка:\fP\fIключ\fP\fB:chain\fP Если \fIключ\fP задан идентификатором ключа типа «asymmetric», то разрешены только ключи, подписанные этим ключом. .IP Если \fIключ\fP задан идентификатором связки ключей, то разрешены только ключи, подписанные ключом из этой связки. .IP Если указана «:chain» то разрешены ключи, которые подписаны ключами из связки назначения (то есть, связки ключей с идентификатором из аргумента \fIarg2\fP). .RE .IP Заметим, что ограничение можно настроить для определённой связки только один раз; будучи назначенным, это нельзя изменить. .IP .\" FIXME Document KEYCTL_RESTRICT_KEYRING, added in Linux 4.12 .\" commit 6563c91fd645556c7801748f15bc727c77fcd311 .\" Author: Mat Martineau .\" See Documentation/security/keys.txt Аргумент \fIarg5\fP игнорируется. .SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" При успешном выполнении возвращаемое значение зависит от используемой команды: .TP \fBKEYCTL_GET_KEYRING_ID\fP Идентификатор запрашиваемой связки ключей. .TP \fBKEYCTL_JOIN_SESSION_KEYRING\fP Идентификатор присоединяемой связки ключей сеанса. .TP \fBKEYCTL_DESCRIBE\fP Размер описания (включая конечный байт null), безотносительно к указанному размеру буфера. .TP \fBKEYCTL_SEARCH\fP Идентификатор найденного ключа. .TP \fBKEYCTL_READ\fP Количество данных, доступных из ключа, безотносительно к указанному размеру буфера. .TP \fBKEYCTL_SET_REQKEY_KEYRING\fP Идентификатор предыдущей связки ключе по умолчанию, в которую неявно цепляются запрашиваемые ключи (одна из \fBKEY_REQKEY_DEFL_USER_*\fP). .TP \fBKEYCTL_ASSUME_AUTHORITY\fP Равно 0, если был указан идентификатор равный 0, или идентификатор ключа авторизации, совпадающий с указанным ключом, если указан ненулевой идентификатор ключа. .TP \fBKEYCTL_GET_SECURITY\fP Размер описания строки метки безопасности LSM (включая конечный байт null), безотносительно к указанному размеру буфера. .TP \fBKEYCTL_GET_PERSISTENT\fP Идентификатор постоянной связки ключей. .TP \fBKEYCTL_DH_COMPUTE\fP Количество байт, скопированных в буфер, или требуемый размер буфера, если \fIarg4\fP равно 0. .TP Остальные операции Ноль. .PP В случае ошибки возвращается \-1, а \fIerrno\fP устанавливается в значение ошибки. .SH ОШИБКИ .TP \fBEACCES\fP Запрошенная операция не разрешена. .TP \fBEAGAIN\fP Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и при инициализации модуля шифрования возникла ошибка. .TP \fBEDEADLK\fP Значение \fIoperation\fP равно \fBKEYCTL_LINK\fP и запрошенная связь привела бы зацикливанию. .TP \fBEDEADLK\fP Значение \fIoperation\fP равно \fBKEYCTL_RESTRICT_KEYRING\fP и запрошенная связь привела бы зацикливанию. .TP \fBEDQUOT\fP Квота на ключи для данного пользователя была бы превышена, если бы этот ключ создался или был бы прицеплен в связку ключей. .TP \fBEEXIST\fP Значение \fIoperation\fP равно \fBKEYCTL_RESTRICT_KEYRING\fP и связка ключей из аргумента \fIarg2\fP уже содержит набор ограничений. .TP \fBEFAULT\fP Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и возникла ошибки в одной из следующих операций: .RS .IP \(bu 3 копирования \fIstruct keyctl_dh_params\fP, указанном в аргументе \fIarg2\fP,из пользовательского пространства .IP \(bu копирования \fIstruct keyctl_kdf_params\fP, указанном в аргументе \fIarg5\fP не равном NULL,из пользовательского пространства (случай, когда ядро поддерживает выполнение операции KDF над результатом операции DH) .IP \(bu копирования данные, указанных в поле \fIhashname\fP с типом \fIstruct keyctl_kdf_params\fP из пользовательского пространства .IP \(bu копирования данные, указанных в поле \fIotherinfo\fP с типом \fIstruct keyctl_kdf_params\fP из пользовательского пространства и поле \fIotherinfolen\fP не равно нулю .IP \(bu копирования результата в пользовательское пространство .RE .TP \fBEINVAL\fP Значение \fIoperation\fP равно \fBKEYCTL_SETPERM\fP и в \fIarg3\fP указан неверный бит прав. .TP \fBEINVAL\fP Значение \fIoperation\fP равно \fBKEYCTL_SEARCH\fP и размер описания в \fIarg4\fP (включая конечный байт null) превышает 4096 байт. Размер строки (включая конечный байт null), указанный в \fIarg3\fP (тип ключа) или \fIarg4\fP (описание ключа) превышает ограничение (32 байта и 4096 байта, соответственно). .TP \fBEINVAL\fP (ядра Linux до 4.12) Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и аргумент \fIarg5\fP не равен NULL. .TP \fBEINVAL\fP Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и указанный размер свёртки алгоритма хэширования равен нулю. .TP \fBEINVAL\fP Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP, но указанный размер буфера недостаточен для размещения результата. Укажите 0 в качестве размера буфера, чтобы получить минимальный размер буфера. .TP \fBEINVAL\fP Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и указанное имя хэша в поле \fIhashname\fP структуры \fIstruct keyctl_kdf_params\fP, на которую указывает аргумент \fIarg5\fP, слишком велико (ограничение зависит от реализации и различно в разных версиях ядра, но считается достаточно большим для всех допустимых имён алгоритмов). .TP \fBEINVAL\fP .\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и поле \fI__spare\fP структуры \fIstruct keyctl_kdf_params\fP, на которую указывает аргумент \fIarg5\fP, содержит ненулевое значение. .TP \fBEKEYEXPIRED\fP Найден или указан просроченный ключ. .TP \fBEKEYREJECTED\fP Найден или указан отклонённый (rejected) ключ. .TP \fBEKEYREVOKED\fP Найден или указан отозванный ключ. .TP \fBELOOP\fP Значение \fIoperation\fP равно \fBKEYCTL_LINK\fP и запрошенная связь привела бы к превышению количества вложенных друг в друга связок ключей. .TP \fBEMSGSIZE\fP Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и длина буфера превышает \fBKEYCTL_KDF_MAX_OUTPUT_LEN\fP (в данный момент равна 1024) или поле \fIotherinfolen\fP структуры \fIstruct keyctl_kdf_parms\fP, переданной в \fIarg5\fP, превышает \fBKEYCTL_KDF_MAX_OI_LEN\fP (в данный момент равно 64). .TP \fBENFILE\fP (ядра Linux до 3.13) .\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69 Значение \fIoperation\fP равно \fBKEYCTL_LINK\fP и связка ключей заполнена (до Linux 3.13 доступное место для хранения связей связки ключей было ограничено одной страницей памяти; начиная с Linux 3.13 жёсткого ограничения нет). .TP \fBENOENT\fP Значение \fIoperation\fP равно \fBKEYCTL_UNLINK\fP и отцепляемый ключ не прицеплен к связке ключей. .TP \fBENOENT\fP Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и алгоритм хэширования, указанный в поле \fIhashname\fP структуры \fIstruct keyctl_kdf_params\fP, на которую указывает аргумент \fIarg5\fP, не найден. .TP \fBENOENT\fP Значение \fIoperation\fP равно \fBKEYCTL_RESTRICT_KEYRING\fP и тип из аргумента \fIarg3\fP не поддерживает ограничения установленным ключом сцепления. .TP \fBENOKEY\fP Искомый ключ не найден или указан неверный ключ. .TP \fBENOKEY\fP Значение \fIoperation\fP равно \fBKEYCTL_GET_KEYRING_ID\fP, ключ, указанный \fIarg2\fP, не существует и значение \fIarg3\fP равно нулю (то есть, не создавать ключ, если он не существует). .TP \fBENOMEM\fP При выполнении вызова одна из процедур выделения памяти ядра завершилась ошибкой. .TP \fBENOTDIR\fP Ожидался ключ с типом связки ключей, но указан идентификатор ключа с другим типом. .TP \fBEOPNOTSUPP\fP Значение \fIoperation\fP равно \fBKEYCTL_READ\fP и тип ключа не поддерживает чтение (например, тип \fI"login"\fP). .TP \fBEOPNOTSUPP\fP Значение \fIoperation\fP равно \fBKEYCTL_UPDATE\fP и тип ключа не поддерживает обновление. .TP \fBEOPNOTSUPP\fP Значение \fIoperation\fP равно \fBKEYCTL_RESTRICT_KEYRING\fP, тип из аргумента \fIarg3\fP равен «asymmetric» и ключ, указанный в определении ограничения, предоставляемый аргументом \fIarg4\fP, имеет тип не «asymmetric» или «keyring». .TP \fBEPERM\fP Значение \fIoperation\fP равно \fBKEYCTL_GET_PERSISTENT\fP, в \fIarg2\fP указан UID, отличающийся от реального или действующего UID вызывающей нити, и вызывающий не имеет мандата \fBCAP_SETUID\fP. .TP \fBEPERM\fP Значение \fIoperation\fP равно \fBKEYCTL_SESSION_TO_PARENT\fP и: не один из UID (GID) родительского процесса не совпадают с действующим UID (GID) вызывающего процесса; UID существующей связки ключей сеанса родителя или UID связки ключей сеанса вызывающего не совпадает с действующим UID вызывающего; родительский процесс состоит из нескольких нитей; родительский процесс это \fBinit\fP(1) или нить ядра. .TP \fBETIMEDOUT\fP Значение \fIoperation\fP равно \fBKEYCTL_DH_COMPUTE\fP и истёк срок инициализации модулей шифрования. .SH ВЕРСИИ Этот системный вызов впервые появился в Linux 2.6.10. .SH "СООТВЕТСТВИЕ СТАНДАРТАМ" Этот системный вызов является нестандартным расширением Linux. .SH ЗАМЕЧАНИЯ Для этого системного вызова нет обёрточной функции в glibc. Обёрточная функция предоставляется библиотекой \fIlibkeyutils\fP. Для вызова нужно выполнить компоновку с библиотекой, указав \fI\-lkeyutils\fP. Несмотря на то, что можно вызывать системные вызова напрямую, для выполнения отдельных операций, вероятно, лучше использовать различные библиотечные функции, описанные выше. .SH ПРИМЕРЫ Программа, показанная далее, предоставляет сокращённый набор возможностей программы \fBrequest\-key\fP(8) из пакета \fIkeyutils\fP. Для информирования программа записывает различные данные в файл журнала. .PP Согласно \fBrequest_key\fP(2), программа \fBrequest\-key\fP(8) вызывается с аргументами командной строки, которые описывают инициализируемый ключ. Программа из примера запрашивает и протоколирует эти аргументы. Программа авторизует на инициализацию запрашиваемого ключа и затем инициализирует этот ключ. .PP Следующий сеанс оболочки показывает использование этой программы. В сеансе мы компилируем программу, а затем используем её как временную замены стандартной программы \fBrequest\-key\fP(8) (заметим, что временное отключение стандартной программы \fBrequest\-key\fP(8) может быть небезопасно на некоторых системах). После того, как наша программа установлена, мы показываем её работу с \fBrequest_key\fP(2) для запроса ключа. .PP .in +4n .EX $ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP $ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP $ \fBsudo cp key_instantiate /sbin/request\-key\fP $ \fB./t_request_key user mykey somepayloaddata\fP Идентификатор ключа равен 20d035bf $ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP .EE .in .PP Заглянув в файл журнала, созданный программой, мы увидим аргументы командной строки, переданные нашей программе: .PP .in +4n .EX $ \fBcat /tmp/key_instantiate.log\fP Время: Mon Nov 7 13:06:47 2016 Аргументы командной строки: argv[0]: /sbin/request\-key operation: create key_to_instantiate: 20d035bf UID: 1000 GID: 1000 thread_keyring: 0 process_keyring: 0 session_keyring: 256e6a6 Описание ключа: user;1000;1000;3f010000;mykey Полезные данные ключа авторизации: somepayloaddata Связка ключей назначения: 256e6a6 Описание ключа авторизации: .request_key_auth;1000;1000;0b010000;20d035bf .EE .in .PP Последние несколько строк вывода показывают, что программа смогла получить: .IP * 3 описание инициализируемого ключа, которое содержит имя ключа (\fImykey\fP); .IP * полезные данные ключа авторизации, которые содержат данные (\fIsomepayloaddata\fP), переданные в \fBrequest_key\fP(2); .IP * связку ключей назначения, которая была указана в вызове \fBrequest_key\fP(2); и .IP * описание ключа авторизации, где мы можем увидеть, что имя ключа авторизации совпадает с идентификатором ключа, который будет инициализирован (\fI20d035bf\fP). .PP Пример программы в \fBrequest_key\fP(2) задаёт связку ключей назначения как \fBKEY_SPEC_SESSION_KEYRING\fP. Просмотрев содержимое \fI/proc/keys\fP, мы можем увидеть, что он транслировался в идентификатор связки ключей назначения (\fI0256e6a6\fP), показанный в журнале выше; мы также может увидеть только что созданный ключ с именем \fImykey\fP и идентификатором \fI20d035bf\fP. .PP .in +4n .EX $ \fBcat /proc/keys | egrep \(aqmykey|256e6a6\(aq\fP 0256e6a6 I\-\-Q\-\-\- 194 perm 3f030000 1000 1000 keyring _ses: 3 20d035bf I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 16 .EE .in .SS "Исходный код программы" \& .EX /* key_instantiate.c */ #include #include #include #include #include #include #include #include #include #include #ifndef KEY_SPEC_REQUESTOR_KEYRING #define KEY_SPEC_REQUESTOR_KEYRING \-8 #endif int main(int argc, char *argv[]) { FILE *fp; time_t t; char *operation; key_serial_t key_to_instantiate, dest_keyring; key_serial_t thread_keyring, process_keyring, session_keyring; uid_t uid; gid_t gid; char dbuf[256]; char auth_key_payload[256]; int akp_size; /* Size of auth_key_payload */ int auth_key; fp = fopen("/tmp/key_instantiate.log", "w"); if (fp == NULL) exit(EXIT_FAILURE); setbuf(fp, NULL); t = time(NULL); fprintf(fp, "Время: %s\en", ctime(&t)); /* * ядро передаёт постоянный набор аргументов в программу, * которую выполняет execs; получаем их. */ operation = argv[1]; key_to_instantiate = atoi(argv[2]); uid = atoi(argv[3]); gid = atoi(argv[4]); thread_keyring = atoi(argv[5]); process_keyring = atoi(argv[6]); session_keyring = atoi(argv[7]); fprintf(fp, "Command line arguments:\en"); fprintf(fp, " argv[0]: %s\en", argv[0]); fprintf(fp, " operation: %s\en", operation); fprintf(fp, " key_to_instantiate: %jx\en", (uintmax_t) key_to_instantiate); fprintf(fp, " UID: %jd\en", (intmax_t) uid); fprintf(fp, " GID: %jd\en", (intmax_t) gid); fprintf(fp, " thread_keyring: %jx\en", (uintmax_t) thread_keyring); fprintf(fp, " process_keyring: %jx\en", (uintmax_t) process_keyring); fprintf(fp, " session_keyring: %jx\en", (uintmax_t) session_keyring); fprintf(fp, "\en"); /* * выдаём право на инициализацию ключа с именем в argv[2] */ if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) { fprintf(fp, "Ошибка KEYCTL_ASSUME_AUTHORITY: %s\en", strerror(errno)); exit(EXIT_FAILURE); } /* * получаем описание ключа, который был инициализирован */ if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate, dbuf, sizeof(dbuf)) == \-1) { fprintf(fp, "Ошибка KEYCTL_DESCRIBE: %s\en", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Описание ключа: %s\en", dbuf); /* * получаем полезные данные ключа авторизации, который * в действительности содержит данные, переданные в request_key() */ akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY, auth_key_payload, sizeof(auth_key_payload)); if (akp_size == \-1) { fprintf(fp, "Ошибка KEYCTL_READ: %s\en", strerror(errno)); exit(EXIT_FAILURE); } auth_key_payload[akp_size] = \(aq\e0\(aq; fprintf(fp, "Полезные данные ключа авторизации: %s\en", auth_key_payload); /* * из любопытства, получим идентификатор ключа авторизации и * выведем его. */ auth_key = keyctl(KEYCTL_GET_KEYRING_ID, KEY_SPEC_REQKEY_AUTH_KEY); if (auth_key == \-1) { fprintf(fp, "Ошибка KEYCTL_GET_KEYRING_ID: %s\en", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Идентификатор ключа авторизации: %jx\en", (uintmax_t) auth_key); /* * получим идентификатор ключа связки ключей назначения request_key(2). */ dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID, KEY_SPEC_REQUESTOR_KEYRING); if (dest_keyring == \-1) { fprintf(fp, "Ошибка KEYCTL_GET_KEYRING_ID: %s\en", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Связка ключей назначения: %jx\en", (uintmax_t) dest_keyring); /* * получим описание ключа авторизации. Это * позволит увидеть тип ключа, UID, GID, права, * и описание (имя) ключа. Среди прочего, * мы увидим, что имя ключа представляет шестнадцатеричную * строку идентификатора инициализированного ключа. */ if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY, dbuf, sizeof(dbuf)) == \-1) { fprintf(fp, "Ошибка KEYCTL_DESCRIBE: %s\en", strerror(errno)); exit(EXIT_FAILURE); } fprintf(fp, "Описание ключа авторизации: %s\en", dbuf); /* * Инициализируем ключ с помощью переданных данных из * полезной нагрузки ключа авторизации. */ if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate, auth_key_payload, akp_size + 1, dest_keyring) == \-1) { fprintf(fp, "Ошибка KEYCTL_INSTANTIATE: %s\en", strerror(errno)); exit(EXIT_FAILURE); } exit(EXIT_SUCCESS); } .EE .SH "СМ. ТАКЖЕ" .ad l .nh .\" .BR find_key_by_type_and_name (3) .\" There is a man page, but this function seems not to exist \fBkeyctl\fP(1), \fBadd_key\fP(2), \fBrequest_key\fP(2), \fBkeyctl\fP(3), \fBkeyctl_assume_authority\fP(3), \fBkeyctl_chown\fP(3), \fBkeyctl_clear\fP(3), \fBkeyctl_describe\fP(3), \fBkeyctl_describe_alloc\fP(3), \fBkeyctl_dh_compute\fP(3), \fBkeyctl_dh_compute_alloc\fP(3), \fBkeyctl_get_keyring_ID\fP(3), \fBkeyctl_get_persistent\fP(3), \fBkeyctl_get_security\fP(3), \fBkeyctl_get_security_alloc\fP(3), \fBkeyctl_instantiate\fP(3), \fBkeyctl_instantiate_iov\fP(3), \fBkeyctl_invalidate\fP(3), \fBkeyctl_join_session_keyring\fP(3), \fBkeyctl_link\fP(3), \fBkeyctl_negate\fP(3), \fBkeyctl_read\fP(3), \fBkeyctl_read_alloc\fP(3), \fBkeyctl_reject\fP(3), \fBkeyctl_revoke\fP(3), \fBkeyctl_search\fP(3), \fBkeyctl_session_to_parent\fP(3), \fBkeyctl_set_reqkey_keyring\fP(3), \fBkeyctl_set_timeout\fP(3), \fBkeyctl_setperm\fP(3), \fBkeyctl_unlink\fP(3), \fBkeyctl_update\fP(3), \fBrecursive_key_scan\fP(3), \fBrecursive_session_key_scan\fP(3), \fBcapabilities\fP(7), \fBcredentials\fP(7), \fBkeyrings\fP(7), \fBkeyutils\fP(7), \fBpersistent\-keyring\fP(7), \fBprocess\-keyring\fP(7), \fBsession\-keyring\fP(7), \fBthread\-keyring\fP(7), \fBuser\-keyring\fP(7), \fBuser_namespaces\fP(7), \fBuser\-session\-keyring\fP(7), \fBrequest\-key\fP(8) .PP Файл из дерева исходного кода ядра \fIDocumentation/security/keys/\fP (до Linux 4.13 — \fIDocumentation/security/keys.txt\fP). .SH ЗАМЕЧАНИЯ Эта страница является частью проекта Linux \fIman\-pages\fP версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу \%https://www.kernel.org/doc/man\-pages/. .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства был сделан Alex Nik , Azamat Hackimov , Yuri Kozlov и Иван Павлов . .PP Этот перевод является бесплатной документацией; прочитайте .UR https://www.gnu.org/licenses/gpl-3.0.html Стандартную общественную лицензию GNU версии 3 .UE или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ. .PP Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на .MT man-pages-ru-talks@lists.sourceforge.net .ME .