2010-02-25 07:24:00 +00:00
|
|
|
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
2016-10-27 08:16:04 +00:00
|
|
|
.\" Written by David Howells (dhowells@redhat.com)
|
|
|
|
.\" and Copyright (C) 2016 Michael Kerrisk <mtk.man-pages@gmail.com>
|
2010-02-25 07:24:00 +00:00
|
|
|
.\"
|
2013-03-10 09:29:47 +00:00
|
|
|
.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
|
2010-02-25 07:24:00 +00:00
|
|
|
.\" 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.
|
2013-03-10 09:28:55 +00:00
|
|
|
.\" %%%LICENSE_END
|
2010-02-25 07:24:00 +00:00
|
|
|
.\"
|
ldd.1, localedef.1, add_key.2, chroot.2, clone.2, fork.2, futex.2, get_mempolicy.2, get_robust_list.2, getitimer.2, getpriority.2, ioctl.2, ioctl_ficlonerange.2, ioctl_fideduperange.2, kcmp.2, kill.2, lookup_dcookie.2, mmap.2, mount.2, open.2, pciconfig_read.2, perf_event_open.2, prctl.2, process_vm_readv.2, ptrace.2, quotactl.2, recv.2, setfsgid.2, setfsuid.2, sysinfo.2, umask.2, umount.2, unshare.2, utimensat.2, wait.2, assert.3, fmax.3, fmin.3, getauxval.3, inet_pton.3, malloc_hook.3, memmem.3, mkdtemp.3, mktemp.3, printf.3, strcasecmp.3, strcat.3, strtoul.3, strxfrm.3, console_codes.4, console_ioctl.4, lirc.4, tty.4, vcs.4, charmap.5, elf.5, locale.5, proc.5, repertoiremap.5, utmp.5, capabilities.7, cgroup_namespaces.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, credentials.7, feature_test_macros.7, iso_8859-1.7, iso_8859-15.7, iso_8859-5.7, koi8-r.7, koi8-u.7, man-pages.7, mount_namespaces.7, namespaces.7, netlink.7, pid_namespaces.7, unix.7, user_namespaces.7, utf-8.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2016-07-17 16:07:58 +00:00
|
|
|
.TH ADD_KEY 2 2016-07-17 Linux "Linux Key Management Calls"
|
2010-02-25 07:24:00 +00:00
|
|
|
.SH NAME
|
intro.1, add_key.2, get_mempolicy.2, get_thread_area.2, intro.2, keyctl.2, mbind.2, request_key.2, set_thread_area.2, clock.3, cmsg.3, getcwd.3, getpw.3, intro.3, malloc.3, posix_memalign.3, shm_open.3, sleep.3, sysconf.3, intro.4, sd.4, intro.5, locale.5, slabinfo.5, intro.6, boot.7, bootparam.7, futex.7, glob.7, hier.7, intro.7, libc.7, locale.7, mq_overview.7, netlink.7, sem_overview.7, shm_overview.7, unix.7, intro.8: Global fix: Use consistent capitalization in NAME section
The line(s) in the NAME section should only use capitals
where English usage dictates that. Otherwise, use
lowercase throughout.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-10-21 06:29:13 +00:00
|
|
|
add_key \- add a key to the kernel's key management facility
|
2010-02-25 07:24:00 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
2016-10-27 07:47:56 +00:00
|
|
|
.B #include <sys/types.h>
|
2010-02-25 07:24:00 +00:00
|
|
|
.B #include <keyutils.h>
|
|
|
|
.sp
|
|
|
|
.BI "key_serial_t add_key(const char *" type ", const char *" description ,
|
2011-11-07 02:43:14 +00:00
|
|
|
.BI " const void *" payload ", size_t " plen ,
|
|
|
|
.BI " key_serial_t " keyring ");"
|
add_key.2, keyctl.2, request_key.2, offsetof.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_cleanup_push_defer_np.3, pthread_equal.3, pthread_exit.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_self.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, pthread_testcancel.3: Global formatting fix: balance .nf/.fi pairs
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-03-12 15:37:22 +00:00
|
|
|
.fi
|
2016-10-21 07:42:23 +00:00
|
|
|
|
|
|
|
No glibc wrapper is provided for this system call; see NOTES.
|
2010-02-25 07:24:00 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
.BR add_key ()
|
2016-10-20 19:47:41 +00:00
|
|
|
creates or updates a key of the given
|
2010-02-25 07:24:00 +00:00
|
|
|
.I type
|
|
|
|
and
|
|
|
|
.IR description ,
|
2016-10-20 19:47:41 +00:00
|
|
|
instantiates it with the
|
2010-02-25 07:24:00 +00:00
|
|
|
.I payload
|
|
|
|
of length
|
|
|
|
.IR plen ,
|
2016-10-20 19:47:41 +00:00
|
|
|
attaches it to the nominated
|
|
|
|
.IR keyring ,
|
2016-11-08 10:44:59 +00:00
|
|
|
and returns the key's serial number.
|
2010-02-25 07:24:00 +00:00
|
|
|
.P
|
2016-11-15 08:43:58 +00:00
|
|
|
The key may be rejected if the provided data is in the wrong format or
|
|
|
|
it is invalid in some other way.
|
2010-02-25 07:24:00 +00:00
|
|
|
.P
|
|
|
|
If the destination
|
|
|
|
.I keyring
|
|
|
|
already contains a key that matches the specified
|
2016-10-20 19:47:41 +00:00
|
|
|
.IR type
|
|
|
|
and
|
|
|
|
.IR description ,
|
2016-11-02 21:01:13 +00:00
|
|
|
then, if the key type supports it,
|
2016-11-06 21:09:01 +00:00
|
|
|
.\" FIXME Which key types support this?
|
2016-11-02 21:01:13 +00:00
|
|
|
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.
|
2016-11-06 21:09:01 +00:00
|
|
|
.\" 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).
|
2010-02-25 07:24:00 +00:00
|
|
|
.P
|
|
|
|
The destination
|
|
|
|
.I keyring
|
2016-10-20 19:47:41 +00:00
|
|
|
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:
|
2016-11-02 22:19:18 +00:00
|
|
|
.\" FIXME Perhaps have a separate page describing special keyring IDs?
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_THREAD_KEYRING
|
2016-10-27 06:05:24 +00:00
|
|
|
This specifies the caller's thread-specific keyring
|
|
|
|
.RB ( thread-keyring (7)).
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_PROCESS_KEYRING
|
2016-10-27 06:05:24 +00:00
|
|
|
This specifies the caller's process-specific keyring
|
|
|
|
.RB ( process-keyring (7)).
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_SESSION_KEYRING
|
2016-10-27 06:05:24 +00:00
|
|
|
This specifies the caller's session-specific keyring
|
|
|
|
.RB ( session-keyring (7)).
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_USER_KEYRING
|
2016-10-27 06:05:24 +00:00
|
|
|
This specifies the caller's UID-specific keyring
|
|
|
|
.RB ( user-keyring (7)).
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_USER_SESSION_KEYRING
|
2016-10-27 06:05:24 +00:00
|
|
|
This specifies the caller's UID-session keyring
|
|
|
|
.RB ( user-session-keyring (7)).
|
2016-10-20 19:47:41 +00:00
|
|
|
.SS Key types
|
2016-10-21 10:25:23 +00:00
|
|
|
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.
|
2016-11-03 21:39:00 +00:00
|
|
|
Among the types that are available for user-space use
|
2016-10-21 10:25:23 +00:00
|
|
|
and can be specified as the
|
|
|
|
.I type
|
|
|
|
argument to
|
2016-11-03 21:39:00 +00:00
|
|
|
.BR add_key ()
|
|
|
|
are the following:
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
2016-10-21 10:12:51 +00:00
|
|
|
.IR """user"""
|
2016-11-03 21:39:00 +00:00
|
|
|
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.
|
2016-10-27 10:58:18 +00:00
|
|
|
The payload for keys of this type is a blob of arbitrary data
|
|
|
|
of up to 32,767 bytes.
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
2016-10-21 10:12:51 +00:00
|
|
|
.I """keyring"""
|
2010-02-25 07:24:00 +00:00
|
|
|
Keyrings are special key types that may contain links to sequences of other
|
2012-05-05 03:10:16 +00:00
|
|
|
keys of any type.
|
2013-02-11 21:40:49 +00:00
|
|
|
If this interface is used to create a keyring, then a NULL
|
2010-02-25 07:24:00 +00:00
|
|
|
.I payload
|
|
|
|
should be specified, and
|
|
|
|
.I plen
|
|
|
|
should be zero.
|
2016-10-21 10:13:15 +00:00
|
|
|
.TP
|
|
|
|
.IR """logon""" " (since Linux 3.3)"
|
|
|
|
.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
|
|
|
|
This key type is essentially the same as
|
|
|
|
.IR """user""" ,
|
2016-11-03 21:39:00 +00:00
|
|
|
but it does not provide reading.
|
|
|
|
This is suitable for storing payloads
|
2016-10-21 10:13:15 +00:00
|
|
|
that you do not want to be readable from user space.
|
|
|
|
|
2016-11-03 21:39:00 +00:00
|
|
|
This key type vets the
|
2016-10-21 10:13:15 +00:00
|
|
|
.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.
|
2016-10-27 07:28:37 +00:00
|
|
|
.TP
|
|
|
|
.IR """big_key""" " (since Linux 3.13)"
|
|
|
|
.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
|
|
|
|
This key type is similar to
|
|
|
|
.IR """user""" ,
|
|
|
|
but may hold a payload of up to 1 MiB.
|
2016-11-15 08:44:14 +00:00
|
|
|
If the key payload is large enough,
|
|
|
|
then it may be stored in tmpfs (which can be swapped out) rather than kernel
|
|
|
|
memory.
|
2016-11-03 21:39:00 +00:00
|
|
|
.PP
|
|
|
|
For further details on these key types, see
|
|
|
|
.BR keyrings (7).
|
2010-02-25 07:24:00 +00:00
|
|
|
.SH RETURN VALUE
|
2016-10-20 19:47:41 +00:00
|
|
|
On success,
|
2010-02-25 07:24:00 +00:00
|
|
|
.BR add_key ()
|
|
|
|
returns the serial number of the key it created or updated.
|
2016-10-20 19:47:41 +00:00
|
|
|
On error, \-1 is returned and
|
|
|
|
.I errno
|
|
|
|
is set to indicate the cause of the error.
|
2010-02-25 07:24:00 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
2016-08-07 16:49:42 +00:00
|
|
|
.B EACCES
|
|
|
|
The keyring wasn't available for modification by the user.
|
|
|
|
.TP
|
2016-10-24 10:55:28 +00:00
|
|
|
.B EDQUOT
|
|
|
|
The key quota for this user would be exceeded by creating this key or linking
|
|
|
|
it to the keyring.
|
|
|
|
.TP
|
2016-11-15 08:44:30 +00:00
|
|
|
.B EFAULT
|
|
|
|
(Part of)
|
|
|
|
.IR type ", " description " or " payload
|
|
|
|
points outside process' accessible address space.
|
|
|
|
.TP
|
2016-08-07 16:49:42 +00:00
|
|
|
.B EINVAL
|
2016-10-27 12:08:47 +00:00
|
|
|
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
|
2016-08-07 16:49:42 +00:00
|
|
|
The payload data was invalid.
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
2016-10-21 10:13:15 +00:00
|
|
|
.B EINVAL
|
|
|
|
.IR type
|
|
|
|
was
|
|
|
|
.IR """logon"""
|
|
|
|
and the
|
|
|
|
.I description
|
|
|
|
was not qualified with a prefix string of the form
|
|
|
|
.IR """service:""" .
|
|
|
|
.TP
|
2010-02-25 07:24:00 +00:00
|
|
|
.B EKEYEXPIRED
|
|
|
|
The keyring has expired.
|
|
|
|
.TP
|
|
|
|
.B EKEYREVOKED
|
|
|
|
The keyring has been revoked.
|
|
|
|
.TP
|
2016-08-07 16:49:42 +00:00
|
|
|
.B ENOKEY
|
|
|
|
The keyring doesn't exist.
|
2010-02-25 07:24:00 +00:00
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
Insufficient memory to create a key.
|
2016-11-15 08:44:40 +00:00
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
The
|
|
|
|
.I type
|
|
|
|
started from dot.
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
.I type
|
|
|
|
was
|
|
|
|
.I """keyring"""
|
|
|
|
and the
|
|
|
|
.I description
|
|
|
|
started from dot.
|
2016-10-19 08:30:25 +00:00
|
|
|
.SH VERSIONS
|
2016-11-03 18:05:38 +00:00
|
|
|
This system call first appeared in Linux 2.6.10.
|
2016-10-19 08:30:25 +00:00
|
|
|
.SH CONFORMING TO
|
|
|
|
This system call is a nonstandard Linux extension.
|
2016-10-19 08:29:31 +00:00
|
|
|
.SH NOTES
|
2016-10-21 07:42:23 +00:00
|
|
|
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 .
|
2016-10-27 08:16:04 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
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:
|
|
|
|
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
$ \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
|
|
|
|
.in
|
|
|
|
.SS Program source
|
|
|
|
\&
|
|
|
|
.nf
|
|
|
|
#include <sys/types.h>
|
|
|
|
#include <keyutils.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\\n",
|
|
|
|
argv[0]);
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
|
|
|
|
key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
|
|
|
|
KEY_SPEC_SESSION_KEYRING);
|
2016-11-08 23:36:21 +00:00
|
|
|
if (key == \-1) {
|
|
|
|
perror("add_key");
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
2016-10-27 08:16:04 +00:00
|
|
|
|
|
|
|
printf("Key ID is %lx\\n", (long) key);
|
|
|
|
|
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
}
|
|
|
|
.fi
|
2010-02-25 07:24:00 +00:00
|
|
|
.SH SEE ALSO
|
2016-11-02 02:59:30 +00:00
|
|
|
.ad l
|
|
|
|
.nh
|
2010-02-25 07:24:00 +00:00
|
|
|
.BR keyctl (1),
|
|
|
|
.BR keyctl (2),
|
2015-04-22 12:04:54 +00:00
|
|
|
.BR request_key (2),
|
2015-04-22 12:06:47 +00:00
|
|
|
.BR keyctl (3),
|
2016-10-21 08:11:18 +00:00
|
|
|
.BR keyutils (7),
|
|
|
|
.BR keyrings (7),
|
2016-11-02 02:59:30 +00:00
|
|
|
.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)
|
2016-10-20 06:47:31 +00:00
|
|
|
|
|
|
|
The kernel source files
|
|
|
|
.IR Documentation/security/keys.txt
|
|
|
|
and
|
2016-11-02 02:59:30 +00:00
|
|
|
.IR Documentation/security/keys\-request\-key.txt .
|