DESCRIPTION

add_key() creates or updates a key of the given type and description, instantiates it with the payload of length plen, attaches it to the nominated keyring, and returns the key's serial number.

The key may be rejected if the provided data is in the wrong format or it is invalid in some other way.

If the destination keyring already contains a key that matches the specified type and description, then, if the key type supports it, that key will be updated rather than a new key being created; if not, a new key (with a different ID) will be created and it will displace the link to the extant key from the keyring.

The destination keyring serial number may be that of a valid keyring for which the caller has write permission. Alternatively, it may be one of the following special keyring IDs:

RETURN VALUE

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.

ERRORS

VERSIONS

This system call first appeared in Linux 2.6.10.

CONFORMING TO

This system call is a nonstandard Linux extension.

NOTES

Glibc does not provide a wrapper for this system call. A wrapper is provided in the libkeyutils package. When employing the wrapper in that library, link with −lkeyutils.

EXAMPLES

The program below creates a key with the type, description, and payload specified in its command-line arguments, and links that key into the session keyring. The following shell session demonstrates the use of the program:

#include <sys/types.h>
#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);
}

SEE ALSO

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)

The kernel source files Documentation/security/keys/core.rst and Documentation/keys/request−key.rst (or, before Linux 4.13, in the files Documentation/security/keys.txt and Documentation/security/keys−request−key.txt).