mirror of https://github.com/mkerrisk/man-pages
add_key.2: New page documenting add_key(2)
Taken from keyutils-1.1 package. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
38271a2dc6
commit
2e2f82fc2a
|
@ -0,0 +1,137 @@
|
||||||
|
.\"
|
||||||
|
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
||||||
|
.\" Written by David Howells (dhowells@redhat.com)
|
||||||
|
.\"
|
||||||
|
.\" 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.
|
||||||
|
.\"
|
||||||
|
.TH ADD_KEY 2 "4 May 2006" 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 ", key_serial_t " keyring ");"
|
||||||
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.BR add_key ()
|
||||||
|
asks the kernel to create or update a key of the given
|
||||||
|
.I type
|
||||||
|
and
|
||||||
|
.IR description ,
|
||||||
|
instantiate it with the
|
||||||
|
.I payload
|
||||||
|
of length
|
||||||
|
.IR plen ,
|
||||||
|
and to attach it to the nominated
|
||||||
|
.I keyring
|
||||||
|
and to return its serial number.
|
||||||
|
.P
|
||||||
|
The key type may reject the data if it's in the wrong format or in some other
|
||||||
|
way invalid.
|
||||||
|
.P
|
||||||
|
If the destination
|
||||||
|
.I keyring
|
||||||
|
already contains a key that matches the specified
|
||||||
|
.IR 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 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 to which the caller has write
|
||||||
|
permission, or it may be a special keyring ID:
|
||||||
|
.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.
|
||||||
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||||
|
.SH KEY TYPES
|
||||||
|
There are a number of key types available in the core key management code, and
|
||||||
|
these can be specified to this function:
|
||||||
|
.TP
|
||||||
|
.B \*(lquser\*(rq
|
||||||
|
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
|
||||||
|
.RB \*(lq afs:mykey \*(rq).
|
||||||
|
The
|
||||||
|
.I payload
|
||||||
|
may be empty or
|
||||||
|
.B NULL
|
||||||
|
for keys of this type.
|
||||||
|
.TP
|
||||||
|
.B \*(lqkeyring\*(rq
|
||||||
|
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
|
||||||
|
.B NULL
|
||||||
|
.I payload
|
||||||
|
should be specified, and
|
||||||
|
.I plen
|
||||||
|
should be zero.
|
||||||
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||||
|
.SH RETURN VALUE
|
||||||
|
On success
|
||||||
|
.BR add_key ()
|
||||||
|
returns the serial number of the key it created or updated.
|
||||||
|
On error, the value
|
||||||
|
.B -1
|
||||||
|
will be returned and errno will have been set to an appropriate error.
|
||||||
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||||
|
.SH ERRORS
|
||||||
|
.TP
|
||||||
|
.B ENOKEY
|
||||||
|
The keyring doesn't exist.
|
||||||
|
.TP
|
||||||
|
.B EKEYEXPIRED
|
||||||
|
The keyring has expired.
|
||||||
|
.TP
|
||||||
|
.B EKEYREVOKED
|
||||||
|
The keyring has been revoked.
|
||||||
|
.TP
|
||||||
|
.B EINVAL
|
||||||
|
The payload data was invalid.
|
||||||
|
.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.
|
||||||
|
.TP
|
||||||
|
.B EACCES
|
||||||
|
The keyring wasn't available for modification by the user.
|
||||||
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||||
|
.SH LINKING
|
||||||
|
Although this is a Linux system call, it is not present in
|
||||||
|
.I libc
|
||||||
|
but can be found rather in
|
||||||
|
.IR libkeyutils .
|
||||||
|
When linking,
|
||||||
|
.B -lkeyutils
|
||||||
|
should be specified to the linker.
|
||||||
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||||
|
.SH SEE ALSO
|
||||||
|
.BR keyctl (1),
|
||||||
|
.BR keyctl (2),
|
||||||
|
.BR request_key (2)
|
Loading…
Reference in New Issue