Section (2) add_key
Name
add_key — add a key to the kernel_zsingle_quotesz_s key management facility
Synopsis
#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) ; |
No glibc wrapper is provided for this system call; see NOTES.
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_zsingle_quotesz_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:
KEY_SPEC_THREAD_KEYRING
-
This specifies the caller_zsingle_quotesz_s thread-specific keyring (
thread-keyring
(7)). KEY_SPEC_PROCESS_KEYRING
-
This specifies the caller_zsingle_quotesz_s process-specific keyring (
process-keyring
(7)). KEY_SPEC_SESSION_KEYRING
-
This specifies the caller_zsingle_quotesz_s session-specific keyring (
session-keyring
(7)). KEY_SPEC_USER_KEYRING
-
This specifies the caller_zsingle_quotesz_s UID-specific keyring (
user-keyring
(7)). KEY_SPEC_USER_SESSION_KEYRING
-
This specifies the caller_zsingle_quotesz_s UID-session keyring (
user-session-keyring
(7)).
Key types
The key type
is
a string that specifies the key_zsingle_quotesz_s type. Internally, the
kernel defines a number of key types that are available in
the core key management code. Among the types that are
available for user-space use and can be specified as the
type
argument to
add_key
() are the
following:
keyring
-
Keyrings are special key types that may contain links to sequences of other keys of any type. If this interface is used to create a keyring, then
payload
should be NULL andplen
should be zero. user
-
This is a general purpose key type whose payload may be read and updated by user-space applications. The key is kept entirely within kernel memory. The payload for keys of this type is a blob of arbitrary data of up to 32,767 bytes.
logon
(since 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.
This key type vets the description
to ensure that it
is qualified by a service prefix, by checking to ensure
that the description
contains a _zsingle_quotesz_:_zsingle_quotesz_
that is preceded by other characters.
big_key
(since 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.
For further details on these key types, see keyrings(7).
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 cause of the
error.
ERRORS
- EACCES
-
The keyring wasn_zsingle_quotesz_t available for modification by the user.
- EDQUOT
-
The key quota for this user would be exceeded by creating this key or linking it to the keyring.
- EFAULT
-
One or more of
type
,description
, andpayload
points outside process_zsingle_quotesz_s accessible address space. - EINVAL
-
The size of the string (including the terminating null byte) specified in
type
ordescription
exceeded the limit (32 bytes and 4096 bytes respectively). - EINVAL
-
The payload data was invalid.
- EINVAL
-
type
waslogon
and thedescription
was not qualified with a prefix string of the formservice:
. - EKEYEXPIRED
-
The keyring has expired.
- EKEYREVOKED
-
The keyring has been revoked.
- ENOKEY
-
The keyring doesn_zsingle_quotesz_t exist.
- ENOMEM
-
Insufficient memory to create a key.
- EPERM
-
The
type
started with a period (_zsingle_quotesz_._zsingle_quotesz_). Key types that begin with a period are reserved to the implementation. - EPERM
-
type
waskeyring
and thedescription
started with a period (_zsingle_quotesz_._zsingle_quotesz_). Keyrings with descriptions (names) that begin with a period are reserved to the implementation.
NOTES
No wrapper for this system call is provided in glibc. A
wrapper is provided in the libkeyutils
package. When
employing the wrapper in that library, link with −lkeyutils
.
EXAMPLE
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:
$ ./a.out user mykey Some payload Key ID is 64a4dca $ grep _zsingle_quotesz_64a4dca_zsingle_quotesz_ /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 , 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 , (long) 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
).
COLOPHON
This page is part of release 5.04 of the Linux man-pages
project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
https://www.kernel.org/doc/man−pages/.
Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. Written by David Howells (dhowellsredhat.com) and Copyright (C) 2016 Michael Kerrisk <mtk.man-pagesgmail.com> %%%LICENSE_START(GPLv2+_SW_ONEPARA) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. %%%LICENSE_END |