mirror of https://github.com/mkerrisk/man-pages
183 lines
4.9 KiB
Groff
183 lines
4.9 KiB
Groff
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
|
.\" Written by David Howells (dhowells@redhat.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
|
|
.\"
|
|
.TH ADD_KEY 2 2016-07-17 Linux "Linux Key Management Calls"
|
|
.SH NAME
|
|
add_key \- add a key to the kernel's key management facility
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <keyutils.h>
|
|
.sp
|
|
.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
|
|
|
|
No glibc wrapper is provided 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 return the key's serial number.
|
|
.P
|
|
The key type may reject the data if it is in the wrong format or
|
|
is in some other way invalid.
|
|
.P
|
|
If the destination
|
|
.I keyring
|
|
already contains a key that matches the specified
|
|
.IR type
|
|
and
|
|
.IR 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 will be created and it will displace the
|
|
link to the extant key from the keyring.
|
|
.P
|
|
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:
|
|
.TP
|
|
.B KEY_SPEC_THREAD_KEYRING
|
|
This specifies the caller's thread-specific keyring.
|
|
.TP
|
|
.B KEY_SPEC_PROCESS_KEYRING
|
|
This specifies the caller's process-specific keyring.
|
|
.TP
|
|
.B KEY_SPEC_SESSION_KEYRING
|
|
This specifies the caller's session-specific keyring.
|
|
.TP
|
|
.B KEY_SPEC_USER_KEYRING
|
|
This specifies the caller's UID-specific keyring.
|
|
.TP
|
|
.B KEY_SPEC_USER_SESSION_KEYRING
|
|
This specifies the caller's UID-session keyring.
|
|
.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.
|
|
The following types are available for user-space use,
|
|
and can be specified as the
|
|
.I type
|
|
argument to
|
|
.BR add_key ():
|
|
.TP
|
|
.IR """user"""
|
|
Keys of the user-defined key type may contain a blob of arbitrary data, and the
|
|
.I description
|
|
may be any valid string, though it is preferred that the description be
|
|
prefixed with a string representing the service to which the key is of interest
|
|
and a colon (for instance
|
|
.IR """afs:mykey""" ).
|
|
.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
|
|
.I payload
|
|
should be specified, and
|
|
.I plen
|
|
should be zero.
|
|
.TP
|
|
.IR """logon""" " (since Linux 3.3)"
|
|
.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
|
|
This key type is essentially the same as
|
|
.IR """user""" ,
|
|
but does not provide a read operation,
|
|
meaning that the key payload is never visible from user space.
|
|
This is suitable for storing username and password pairs in the keyring
|
|
that you do not want to be readable from user space.
|
|
|
|
This key type also 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.
|
|
.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 cause of the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EACCES
|
|
The keyring wasn't available for modification by the user.
|
|
.TP
|
|
.B EINVAL
|
|
The payload data was invalid.
|
|
.TP
|
|
.B EINVAL
|
|
.IR type
|
|
was
|
|
.IR """logon"""
|
|
and the
|
|
.I description
|
|
was not qualified with a prefix string of the form
|
|
.IR """service:""" .
|
|
.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 EDQUOT
|
|
The key quota for this user would be exceeded by creating this key or linking
|
|
it to the keyring.
|
|
.SH VERSIONS
|
|
This system call first appeared in Linux 2.6.11.
|
|
.SH CONFORMING TO
|
|
This system call is a nonstandard Linux extension.
|
|
.SH NOTES
|
|
No wrapper for this system call is provided in glibc.
|
|
A wrapper is provided in the
|
|
.IR libkeyutils
|
|
package.
|
|
When employing the wrapper in that library, link with
|
|
.IR \-lkeyutils .
|
|
.SH SEE ALSO
|
|
.BR keyctl (1),
|
|
.BR keyctl (2),
|
|
.BR request_key (2),
|
|
.BR keyctl (3),
|
|
.BR keyutils (7),
|
|
.BR keyrings (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)
|
|
|
|
The kernel source files
|
|
.IR Documentation/security/keys.txt
|
|
and
|
|
.IR Documentation/security/keys-request-key.txt .
|