Section: Linux Key Management Calls (2)
更新日期： 2020-06-09

名称

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()创建或更新给定类型和描述的密钥，使用长度为plen的有效负载实例化该密钥，将其附加到指定的密钥环上，并返回密钥的序列号。

如果提供的数据格式错误或以其他方式无效，则可能会拒绝该密钥。

如果目标密钥环已经包含与指定的类型和描述匹配的密钥，那么，如果密钥类型支持它，则将更新该密钥，而不是创建新的密钥；否则，将创建一个新的密钥(具有不同的ID)，它将替换从密钥环到现有密钥的链接。

目标密钥环序列号可以是呼叫者对其具有写许可权的有效密钥环的序列号。或者，它可以是以下特殊密钥环ID之一：

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))。

Key types

密钥类型是指定密钥类型的字符串。在内部，内核定义了核心密钥管理代码中可用的多种密钥类型。在用户空间可用的类型中，可以指定为add_key()的类型参数的类型如下：

keyring

密钥环是特殊的密钥类型，可能包含指向任何其他类型的其他密钥序列的链接。如果使用此接口创建密钥环，则有效负载应为NULL，并且plen应为零。

user

这是一种通用密钥类型，其有效载荷可以由用户空间应用程序读取和更新。密钥完全保留在内核内存中。此类密钥的有效载荷是最多32,767字节的任意数据的blob。

logon(since Linux 3.3)

此密钥类型与用户基本相同，但是不允许读取密钥。这适合于存储您不想从用户空间读取的有效负载。

此密钥类型通过检查以确保描述包含以其他字符开头的'：'来审核该描述，以确保该描述由" service"前缀限定。

big_key(since Linux 3.13)

此密钥类型与用户相似，但最多可容纳1个MiB的有效负载。如果密钥有效载荷足够大，则可以将其加密存储在tmpfs中(可以换出)而不是内核内存中。

有关这些密钥类型的更多详细信息，请参见keyrings(7)。

返回值

成功后，add_key()返回其创建或更新的密钥的序列号。发生错误时，将返回-1并将errno设置为指示错误原因。

错误说明

EACCES

用户无法修改密钥环。

EDQUOT

通过创建此密钥或将其链接到密钥环，将超出此用户的密钥配额。

EFAULT

类型，描述和有效负载中的一个或多个指向进程的可访问地址空间之外。

EINVAL

在类型或描述中指定的字符串大小(包括终止的空字节)超过了限制(分别为32个字节和4096个字节)。

EINVAL

有效负载数据无效。

EINVAL

类型为登录，并且描述不符合格式为service：的前缀字符串。

EKEYEXPIRED

密钥环已过期。

EKEYREVOKED

密钥环已被撤消。

ENOKEY

密钥环不存在。

ENOMEM

内存不足，无法创建密钥。

EPERM

类型以句点(aq.aq)开头。以句点开头的键类型保留给实现。

EPERM

类型为keyring，说明以句点(aq.aq)开头。具有以句点开头的描述(名称)的密钥环保留给实现。

版本

该系统调用首次出现在Linux 2.6.10中。

遵循规范

此系统调用是非标准的Linux扩展。

备注

glibc中没有提供此系统调用的包装器。 libkeyutils软件包中提供了包装器。在该库中使用包装器时，请与-lkeyutils链接。

示例

下面的程序创建一个具有其命令行参数中指定的类型，描述和有效负载的密钥，并将该密钥链接到会话密钥环中。以下shell会话演示了该程序的用法：

$ ./a.out user mykey "Some payload"
Key ID is 64a4dca
$ grep aq64a4dcaaq /proc/keys
064a4dca I--Q---    1 perm 3f010000  1000  1000 user    mykey: 12

Program source

#include <sys/types.h>
#include <keyutils.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 %lx\n", (long) 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) ，线程密钥(7)，用户密钥(7)，用户会话密钥(7)

内核源文件Documentation / security / keys / core.rst和Documentation / keys / request-key.rst(或者在Linux 4.13之前，在Documentation / security / keys.txt和Documentation / security / keys-request-key中) 。文本)。

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。