Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 298 insertions, 0 deletions

diff --git a/man/man2/add_key.2 b/man/man2/add_key.2
new file mode 100644
index 0000000..a98e483
--- /dev/null
+++ b/man/man2/add_key.2
@@ -0,0 +1,298 @@
+.\" 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 2024-05-02 "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 ).