.\" 2 of the License, or (at your option) any later version.
.\" %%%LICENSE_END
.\"
-.TH ADD_KEY 2 2016-07-17 Linux "Linux Key Management Calls"
+.TH ADD_KEY 2 2019-03-06 Linux "Linux Key Management Calls"
.SH NAME
add_key \- add a key to the kernel's key management facility
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <keyutils.h>
-.sp
+.PP
.BI "key_serial_t add_key(const char *" type ", const char *" description ,
.BI " const void *" payload ", size_t " plen ,
.BI " key_serial_t " keyring ");"
.fi
-
+.PP
No glibc wrapper is provided for this system call; see NOTES.
.SH DESCRIPTION
.BR add_key ()
attaches it to the nominated
.IR keyring ,
and returns the key's serial number.
-.P
+.PP
The key may be rejected if the provided data is in the wrong format or
it is invalid in some other way.
-.P
+.PP
If the destination
.I keyring
already contains a key that matches the specified
and
.IR description ,
then, if the key type supports it,
-.\" FIXME Which key types support this?
+.\" 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 tha
-.\" is consequently unlinked, then keys that it was anchrorin
-.\" will have their refgerence count decreased by one (and ma
-.\" consequently be garbage collected).
-.P
+.\" 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?
+.PP
The destination
.I keyring
serial number may be that of a valid keyring for which the caller has
.I write
-permission, or it may be one of the following special keyring IDs:
-.\" FIXME Perhaps have a separate page describing special keyring IDs?
+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
.BR add_key ()
are the following:
.TP
-.IR """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.
-.TP
.I """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 a NULL
+If this interface is used to create a keyring, then
.I payload
-should be specified, and
+should be NULL and
.I plen
should be zero.
.TP
+.IR """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.
+.TP
.IR """logon""" " (since Linux 3.3)"
.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
This key type is essentially the same as
.IR """user""" ,
-but it does not provide reading.
+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.
-
+.PP
This key type vets the
.I description
to ensure that it is qualified by a "service" prefix,
.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
This key type is similar to
.IR """user""" ,
-but may hold a payload of up to 1 MiB.
+but may hold a payload of up to 1\ MiB.
If the key payload is large enough,
-then it may be stored in tmpfs (which can be swapped out) rather than kernel
-memory.
+then it may be stored encrypted in tmpfs
+(which can be swapped out) rather than kernel memory.
.PP
For further details on these key types, see
.BR keyrings (7).
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
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 VERSIONS
This system call first appeared in Linux 2.6.10.
.SH CONFORMING TO
specified in its command-line arguments,
and links that key into the session keyring.
The following shell session demonstrates the use of the program:
-
+.PP
.in +4n
-.nf
+.EX
$ \fB./a.out user mykey "Some payload"\fP
Key ID is 64a4dca
$ \fBgrep \(aq64a4dca\(aq /proc/keys\fP
064a4dca I--Q--- 1 perm 3f010000 1000 1000 user mykey: 12
-.fi
+.EE
.in
.SS Program source
\&
-.nf
+.EX
#include <sys/types.h>
#include <keyutils.h>
#include <stdio.h>
key_serial_t key;
if (argc != 4) {
- fprintf(stderr, "Usage: %s type description payload\\n",
+ fprintf(stderr, "Usage: %s type description payload\en",
argv[0]);
exit(EXIT_FAILURE);
}
exit(EXIT_FAILURE);
}
- printf("Key ID is %lx\\n", (long) key);
+ printf("Key ID is %lx\en", (long) key);
exit(EXIT_SUCCESS);
}
-.fi
+.EE
.SH SEE ALSO
.ad l
.nh
.BR keyctl (2),
.BR request_key (2),
.BR keyctl (3),
-.BR keyutils (7),
.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)
-
+.PP
The kernel source files
+.IR Documentation/security/keys/core.rst
+and
+.IR Documentation/keys/request\-key.rst
+(or, before Linux 4.13, in the files
+.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76
.IR Documentation/security/keys.txt
and
-.IR Documentation/security/keys\-request\-key.txt .
+.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b
+.IR Documentation/security/keys\-request\-key.txt ).
projects / thirdparty / man-pages.git / blobdiff