diff options
Diffstat (limited to 'man2/add_key.2')
| -rw-r--r-- | man2/add_key.2 | 298 |
1 files changed, 0 insertions, 298 deletions
diff --git a/man2/add_key.2 b/man2/add_key.2 deleted file mode 100644 index 2b017f680..000000000 --- a/man2/add_key.2 +++ /dev/null @@ -1,298 +0,0 @@ -.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. -.\" Written by David Howells (dhowells@redhat.com) -.\" and Copyright (C) 2016 Michael Kerrisk <mtk.man-pages@gmail.com> -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.\" -.TH add_key 2 (date) "Linux man-pages (unreleased)" -.SH NAME -add_key \- add a key to the kernel's key management facility -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <keyutils.h> -.P -.BI "key_serial_t add_key(const char *" type ", const char *" description , -.BI " const void " payload [. plen "], size_t " plen , -.BI " key_serial_t " keyring ");" -.fi -.P -.IR Note : -There is no glibc wrapper for this system call; see NOTES. -.SH DESCRIPTION -.BR add_key () -creates or updates a key of the given -.I type -and -.IR description , -instantiates it with the -.I payload -of length -.IR plen , -attaches it to the nominated -.IR keyring , -and returns the key's serial number. -.P -The key may be rejected if the provided data is in the wrong format or -it is invalid in some other way. -.P -If the destination -.I keyring -already contains a key that matches the specified -.I type -and -.IR description , -then, if the key type supports it, -.\" FIXME The aforementioned phrases begs the question: -.\" which key types support this? -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. -.\" FIXME Perhaps elaborate the implications here? Namely, the new -.\" key will have a new ID, and if the old key was a keyring that -.\" is consequently unlinked, then keys that it was anchoring -.\" will have their reference count decreased by one (and may -.\" consequently be garbage collected). Is this all correct? -.P -The destination -.I keyring -serial number may be that of a valid keyring for which the caller has -.I write -permission. -Alternatively, it may be one of the following special keyring IDs: -.\" FIXME . Perhaps have a separate page describing special keyring IDs? -.TP -.B KEY_SPEC_THREAD_KEYRING -This specifies the caller's thread-specific keyring -.RB ( thread\-keyring (7)). -.TP -.B KEY_SPEC_PROCESS_KEYRING -This specifies the caller's process-specific keyring -.RB ( process\-keyring (7)). -.TP -.B KEY_SPEC_SESSION_KEYRING -This specifies the caller's session-specific keyring -.RB ( session\-keyring (7)). -.TP -.B KEY_SPEC_USER_KEYRING -This specifies the caller's UID-specific keyring -.RB ( user\-keyring (7)). -.TP -.B KEY_SPEC_USER_SESSION_KEYRING -This specifies the caller's UID-session keyring -.RB ( user\-session\-keyring (7)). -.SS Key types -The key -.I type -is a string that specifies the key'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 -.I type -argument to -.BR add_key () -are the following: -.TP -.I \[dq]keyring\[dq] -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 -.I payload -should be NULL and -.I plen -should be zero. -.TP -.I \[dq]user\[dq] -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. -.TP -.IR \[dq]logon\[dq] " (since Linux 3.3)" -.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b -This key type is essentially the same as -.IR \[dq]user\[dq] , -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. -.P -This key type vets the -.I description -to ensure that it is qualified by a "service" prefix, -by checking to ensure that the -.I description -contains a ':' that is preceded by other characters. -.TP -.IR \[dq]big_key\[dq] " (since Linux 3.13)" -.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 -This key type is similar to -.IR \[dq]user\[dq] , -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. -.P -For further details on these key types, see -.BR keyrings (7). -.SH RETURN VALUE -On success, -.BR add_key () -returns the serial number of the key it created or updated. -On error, \-1 is returned and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.B EACCES -The keyring wasn't available for modification by the user. -.TP -.B EDQUOT -The key quota for this user would be exceeded by creating this key or linking -it to the keyring. -.TP -.B EFAULT -One or more of -.IR type , -.IR description , -and -.I payload -points outside process's accessible address space. -.TP -.B EINVAL -The size of the string (including the terminating null byte) specified in -.I type -or -.I description -exceeded the limit (32 bytes and 4096 bytes respectively). -.TP -.B EINVAL -The payload data was invalid. -.TP -.B EINVAL -.I type -was -.I \[dq]logon\[dq] -and the -.I description -was not qualified with a prefix string of the form -.IR \[dq]service:\[dq] . -.TP -.B EKEYEXPIRED -The keyring has expired. -.TP -.B EKEYREVOKED -The keyring has been revoked. -.TP -.B ENOKEY -The keyring doesn't exist. -.TP -.B ENOMEM -Insufficient memory to create a key. -.TP -.B EPERM -The -.I type -started with a period (\[aq].\[aq]). -Key types that begin with a period are reserved to the implementation. -.TP -.B EPERM -.I type -was -.I \[dq]keyring\[dq] -and the -.I description -started with a period (\[aq].\[aq]). -Keyrings with descriptions (names) -that begin with a period are reserved to the implementation. -.SH STANDARDS -Linux. -.SH HISTORY -Linux 2.6.10. -.SH NOTES -glibc does not provide a wrapper for this system call. -A wrapper is provided in the -.I libkeyutils -library. -(The accompanying package provides the -.I <keyutils.h> -header file.) -When employing the wrapper in that library, link with -.IR \-lkeyutils . -.SH 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: -.P -.in +4n -.EX -$ \fB./a.out user mykey "Some payload"\fP -Key ID is 64a4dca -$ \fBgrep \[aq]64a4dca\[aq] /proc/keys\fP -064a4dca I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 12 -.EE -.in -.SS Program source -\& -.\" SRC BEGIN (add_key.c) -.EX -#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\en", - 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\en", (uintmax_t) key); -\& - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.ad l -.nh -.BR keyctl (1), -.BR keyctl (2), -.BR request_key (2), -.BR keyctl (3), -.BR keyrings (7), -.BR keyutils (7), -.BR persistent\-keyring (7), -.BR process\-keyring (7), -.BR session\-keyring (7), -.BR thread\-keyring (7), -.BR user\-keyring (7), -.BR user\-session\-keyring (7) -.P -The kernel source files -.I Documentation/security/keys/core.rst -and -.I Documentation/keys/request\-key.rst -(or, before Linux 4.13, in the files -.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 -.I Documentation/security/keys.txt -and -.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b -.IR Documentation/security/keys\-request\-key.txt ). |