2016-11-01 15:40:57 +00:00
|
|
|
.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
|
|
|
|
.\" Written by David Howells (dhowells@redhat.com)
|
2016-11-03 19:44:51 +00:00
|
|
|
.\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
|
2016-11-01 15:40:57 +00:00
|
|
|
.\"
|
2016-11-02 11:24:22 +00:00
|
|
|
.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
|
2016-11-01 15:40:57 +00:00
|
|
|
.\" This program is free software; you can redistribute it and/or
|
2016-11-08 08:24:22 +00:00
|
|
|
.\" modify it under the terms of the GNU General Public License
|
2016-11-01 15:40:57 +00:00
|
|
|
.\" as published by the Free Software Foundation; either version
|
2016-11-08 08:24:22 +00:00
|
|
|
.\" 2 of the License, or (at your option) any later version.
|
2016-11-02 11:24:22 +00:00
|
|
|
.\" %%%LICENSE_END
|
2016-11-01 15:40:57 +00:00
|
|
|
.\"
|
intro.1, clock_getres.2, execve.2, fcntl.2, iopl.2, lseek.2, mknod.2, mmap.2, mount.2, mq_getsetattr.2, pidfd_open.2, prctl.2, setns.2, sgetmask.2, sigaction.2, stat.2, statx.2, sync.2, syscalls.2, syslog.2, timerfd_create.2, umask.2, a64l.3, aio_init.3, atoi.3, dladdr.3, fread.3, getpt.3, isfdtype.3, malloc_stats.3, malloc_trim.3, mkfifo.3, mq_close.3, mq_open.3, mq_receive.3, mq_send.3, mq_unlink.3, posix_memalign.3, posix_openpt.3, pthread_atfork.3, pthread_rwlockattr_setkind_np.3, regex.3, scanf.3, sem_close.3, sem_destroy.3, sem_init.3, sem_open.3, sem_post.3, sem_unlink.3, sigset.3, sigvec.3, strftime.3, termios.3, console_codes.4, dsp56k.4, fd.4, lp.4, mouse.4, pts.4, sk98lin.4, dir_colors.5, proc.5, resolv.conf.5, termcap.5, utmp.5, aio.7, armscii-8.7, arp.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, environ.7, glob.7, inode.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, mailaddr.7, man-pages.7, netdevice.7, operator.7, persistent-keyring.7, process-keyring.7, pthreads.7, pty.7, raw.7, regex.7, session-keyring.7, shm_overview.7, signal.7, socket.7, suffixes.7, thread-keyring.7, unicode.7, units.7, uri.7, user-keyring.7, user-session-keyring.7, iconvconfig.8, ld.so.8, zic.8: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-08-13 08:01:14 +00:00
|
|
|
.TH KEYRINGS 7 2020-08-13 Linux "Linux Programmer's Manual"
|
2016-11-01 15:40:57 +00:00
|
|
|
.SH NAME
|
2016-11-01 17:26:22 +00:00
|
|
|
keyrings \- in-kernel key management and retention facility
|
2016-11-01 20:45:39 +00:00
|
|
|
.SH DESCRIPTION
|
2016-11-02 17:24:01 +00:00
|
|
|
The Linux key-management facility
|
2016-11-08 08:47:39 +00:00
|
|
|
is primarily a way for various kernel components
|
|
|
|
to retain or cache security data,
|
2016-11-01 20:58:07 +00:00
|
|
|
authentication keys, encryption keys, and other data in the kernel.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-07 13:09:55 +00:00
|
|
|
System call interfaces are provided so that user-space programs can manage
|
2016-11-07 13:13:21 +00:00
|
|
|
those objects and also use the facility for their own purposes; see
|
|
|
|
.BR add_key (2),
|
|
|
|
.BR request_key (2),
|
|
|
|
and
|
|
|
|
.BR keyctl (2).
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.PP
|
2016-11-01 21:02:20 +00:00
|
|
|
A library and some user-space utilities are provided to allow access to the
|
2016-11-01 17:45:14 +00:00
|
|
|
facility.
|
|
|
|
See
|
2016-11-02 17:24:01 +00:00
|
|
|
.BR keyctl (1),
|
|
|
|
.BR keyctl (3),
|
|
|
|
and
|
2016-11-01 15:40:57 +00:00
|
|
|
.BR keyutils (7)
|
2016-11-01 18:08:09 +00:00
|
|
|
for more information.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS Keys
|
2016-11-02 17:24:01 +00:00
|
|
|
A key has the following attributes:
|
|
|
|
.TP
|
2016-11-03 20:30:41 +00:00
|
|
|
Serial number (ID)
|
2016-11-08 08:47:39 +00:00
|
|
|
This is a unique integer handle by which a key is referred to in system calls.
|
2016-11-03 20:30:41 +00:00
|
|
|
The serial number is sometimes synonymously referred as the key ID.
|
2016-11-02 17:24:01 +00:00
|
|
|
Programmatically, key serial numbers are represented using the type
|
|
|
|
.IR key_serial_t .
|
|
|
|
.TP
|
|
|
|
Type
|
|
|
|
A key's type defines what sort of data can be held in the key,
|
|
|
|
how the proposed content of the key will be parsed,
|
|
|
|
and how the payload will be used.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-07 13:12:41 +00:00
|
|
|
There are a number of general-purpose types available, plus some specialist
|
2016-11-08 08:47:39 +00:00
|
|
|
types defined by specific kernel components.
|
2016-11-02 17:24:01 +00:00
|
|
|
.TP
|
|
|
|
Description (name)
|
|
|
|
The key description is a printable string that is used as the search term
|
|
|
|
for the key (in conjunction with the key type) as well as a display name.
|
|
|
|
During searches, the description may be partially matched or exactly matched.
|
|
|
|
.TP
|
2016-11-03 20:30:41 +00:00
|
|
|
Payload (data)
|
2016-11-02 17:24:01 +00:00
|
|
|
The payload is the actual content of a key.
|
2016-11-01 17:45:14 +00:00
|
|
|
This is usually set when a key is created,
|
2016-11-01 21:02:20 +00:00
|
|
|
but it is possible for the kernel to upcall to user space to finish the
|
2016-11-01 17:45:14 +00:00
|
|
|
instantiation of a key if that key wasn't already known to the kernel
|
|
|
|
when it was requested.
|
2016-12-13 11:42:05 +00:00
|
|
|
For further details, see
|
|
|
|
.BR request_key (2).
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-01 15:40:57 +00:00
|
|
|
A key's payload can be read and updated if the key type supports it and if
|
|
|
|
suitable permission is granted to the caller.
|
2016-11-02 17:24:01 +00:00
|
|
|
.TP
|
|
|
|
Access rights
|
2016-11-02 02:57:08 +00:00
|
|
|
Much as files do,
|
|
|
|
each key has an owning user ID, an owning group ID, and a security label.
|
2016-11-07 13:12:41 +00:00
|
|
|
Each key also has a set of permissions,
|
2016-11-01 17:45:14 +00:00
|
|
|
though there are more than for a normal UNIX file,
|
2016-11-07 13:12:41 +00:00
|
|
|
and there is an additional category\(empossessor\(embeyond the usual user,
|
2016-12-13 11:42:05 +00:00
|
|
|
group, and other (see
|
|
|
|
.IR Possession ,
|
|
|
|
below).
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-07 13:12:41 +00:00
|
|
|
Note that keys are quota controlled, since they require unswappable kernel
|
2016-11-08 08:47:39 +00:00
|
|
|
memory.
|
2016-11-07 13:12:41 +00:00
|
|
|
The owning user ID specifies whose quota is to be debited.
|
2016-11-02 17:24:01 +00:00
|
|
|
.TP
|
|
|
|
Expiration time
|
2016-11-01 17:45:14 +00:00
|
|
|
Each key can have an expiration time set.
|
|
|
|
When that time is reached,
|
2016-11-08 08:47:39 +00:00
|
|
|
the key is marked as being expired and accesses to it fail with the error
|
2016-11-01 18:08:09 +00:00
|
|
|
.BR EKEYEXPIRED .
|
2016-11-07 13:12:41 +00:00
|
|
|
If not deleted, updated, or replaced, then, after a set amount of time,
|
|
|
|
an expired key is automatically removed (garbage collected)
|
|
|
|
along with all links to it,
|
access.2, delete_module.2, eventfd.2, fallocate.2, fcntl.2, getrandom.2, init_module.2, open.2, seccomp.2, timerfd_create.2, openpty.3, pthread_spin_lock.3, shm_open.3, tempnam.3, fifo.7, keyrings.7, pid_namespaces.7, sched.7, thread-keyring.7: wfix (will fail --> fail/fails)
Reported-by: Pedro Alves <palves@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-10-20 14:55:10 +00:00
|
|
|
and attempts to access the key fail with the error
|
2016-11-02 17:24:01 +00:00
|
|
|
.BR ENOKEY .
|
|
|
|
.TP
|
|
|
|
Reference count
|
2016-11-01 17:45:14 +00:00
|
|
|
Each key has a reference count.
|
2016-11-02 17:24:01 +00:00
|
|
|
Keys are referenced by keyrings, by currently active users,
|
2016-11-01 17:45:14 +00:00
|
|
|
and by a process's credentials.
|
|
|
|
When the reference count reaches zero,
|
|
|
|
the key is scheduled for garbage collection.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS Key types
|
2016-11-07 13:12:41 +00:00
|
|
|
The kernel provides several basic types of key:
|
2016-11-02 17:24:01 +00:00
|
|
|
.TP
|
2016-12-13 11:42:55 +00:00
|
|
|
.I """keyring"""
|
2020-07-23 21:53:37 +00:00
|
|
|
.\" Note that keyrings use different fields in struct key in order to store
|
|
|
|
.\" their data - index_key instead of type/description and name_link/keys
|
|
|
|
.\" instead of payload.
|
2016-12-13 11:42:55 +00:00
|
|
|
Keyrings are special keys which store a set of links
|
|
|
|
to other keys (including other keyrings),
|
|
|
|
analogous to a directory holding links to files.
|
|
|
|
The main purpose of a keyring is to prevent other keys from
|
|
|
|
being garbage collected because nothing refers to them.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-12-13 11:42:55 +00:00
|
|
|
Keyrings with descriptions (names)
|
|
|
|
that begin with a period (\(aq.\(aq) are reserved to the implementation.
|
|
|
|
.TP
|
2016-11-03 21:39:00 +00:00
|
|
|
.I """user"""
|
2016-11-07 13:12:41 +00:00
|
|
|
This is a general-purpose key type.
|
2016-11-03 21:39:00 +00:00
|
|
|
The key is kept entirely within kernel memory.
|
|
|
|
The payload may be read and updated by user-space applications.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 21:39:00 +00:00
|
|
|
The payload for keys of this type is a blob of arbitrary data
|
|
|
|
of up to 32,767 bytes.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 21:39:00 +00:00
|
|
|
The description may be any valid string, though it is preferred that it
|
|
|
|
start with a colon-delimited prefix representing the service
|
|
|
|
to which the key is of interest
|
|
|
|
(for instance
|
|
|
|
.IR """afs:mykey""" ).
|
|
|
|
.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 (i.e., the
|
|
|
|
.BR keyctl (2)
|
|
|
|
.BR KEYCTL_READ
|
|
|
|
operation),
|
|
|
|
meaning that the key payload is never visible from user space.
|
|
|
|
This is suitable for storing username-password pairs
|
2016-11-07 13:12:41 +00:00
|
|
|
that should not be readable from user space.
|
2017-09-11 03:11:12 +00:00
|
|
|
.IP
|
2017-09-11 11:27:42 +00:00
|
|
|
The description of a
|
|
|
|
.IR """logon"""
|
|
|
|
key
|
2020-01-21 11:28:32 +00:00
|
|
|
.I must
|
2017-09-11 11:27:42 +00:00
|
|
|
start with a non-empty colon-delimited prefix whose purpose
|
|
|
|
is to identify the service to which the key belongs.
|
|
|
|
(Note that this differs from keys of the
|
|
|
|
.IR """user"""
|
|
|
|
type, where the inclusion of a prefix is recommended but is not enforced.)
|
2016-11-02 17:24:01 +00:00
|
|
|
.TP
|
2016-11-03 21:39:00 +00:00
|
|
|
.IR """big_key""" " (since Linux 3.13)"
|
|
|
|
.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
|
|
|
|
This key type is similar to the
|
2016-11-02 17:24:01 +00:00
|
|
|
.I """user"""
|
add_key.2, alloc_hugepages.2, execve.2, fanotify_init.2, getrlimit.2, listxattr.2, mmap.2, shmget.2, malloc.3, random.4, st.4, bootparam.7, epoll.7, keyrings.7, pipe.7, xattr.7: Use non-breaking space for measurement units
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-18 10:28:20 +00:00
|
|
|
key type, but it may hold a payload of up to 1\ MiB in size.
|
2016-12-13 13:51:10 +00:00
|
|
|
This key type is useful for purposes such as holding Kerberos ticket caches.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-12-13 13:51:10 +00:00
|
|
|
The payload data may be stored in a tmpfs filesystem,
|
|
|
|
rather than in kernel memory,
|
|
|
|
if the data size exceeds the overhead of storing the data in the filesystem.
|
|
|
|
(Storing the data in a filesystem requires filesystem structures
|
|
|
|
to be allocated in the kernel.
|
2016-12-13 12:48:37 +00:00
|
|
|
The size of these structures determines the size threshold
|
|
|
|
above which the tmpfs storage method is used.)
|
2016-12-13 12:56:29 +00:00
|
|
|
Since Linux 4.8,
|
|
|
|
.\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef
|
2016-12-13 13:51:10 +00:00
|
|
|
the payload data is encrypted when stored in tmpfs,
|
2016-12-14 07:26:52 +00:00
|
|
|
thereby preventing it from being written unencrypted into swap space.
|
2016-11-02 17:24:01 +00:00
|
|
|
.PP
|
2016-11-07 13:09:55 +00:00
|
|
|
There are more specialized key types available also,
|
2016-11-07 13:12:41 +00:00
|
|
|
but they aren't discussed here
|
|
|
|
because they aren't intended for normal user-space use.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.PP
|
2016-11-16 10:20:03 +00:00
|
|
|
Key type names
|
|
|
|
that begin with a period (\(aq.\(aq) are reserved to the implementation.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS Keyrings
|
2016-11-07 13:09:55 +00:00
|
|
|
As previously mentioned, keyrings are a special type of key that contain
|
|
|
|
links to other keys (which may include other keyrings).
|
2016-11-01 17:45:14 +00:00
|
|
|
Keys may be linked to by multiple keyrings.
|
|
|
|
Keyrings may be considered as analogous to UNIX directories
|
2016-11-01 15:40:57 +00:00
|
|
|
where each directory contains a set of hard links to files.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 20:58:07 +00:00
|
|
|
Various operations (system calls) may be applied only to keyrings:
|
2016-11-03 20:30:41 +00:00
|
|
|
.IP Adding
|
2016-11-01 17:45:14 +00:00
|
|
|
A key may be added to a keyring by system calls that create keys.
|
|
|
|
This prevents the new key from being immediately deleted
|
2016-11-08 08:47:39 +00:00
|
|
|
when the system call releases its last reference to the key.
|
2016-11-03 20:30:41 +00:00
|
|
|
.IP Linking
|
2016-11-01 15:40:57 +00:00
|
|
|
A link may be added to a keyring pointing to a key that is already known,
|
|
|
|
provided this does not create a self-referential cycle.
|
2016-11-03 20:30:41 +00:00
|
|
|
.IP Unlinking
|
2016-11-01 17:45:14 +00:00
|
|
|
A link may be removed from a keyring.
|
|
|
|
When the last link to a key is removed,
|
2016-11-01 15:40:57 +00:00
|
|
|
that key will be scheduled for deletion by the garbage collector.
|
2016-11-03 20:30:41 +00:00
|
|
|
.IP Clearing
|
2016-11-01 15:40:57 +00:00
|
|
|
All the links may be removed from a keyring.
|
2016-11-03 20:30:41 +00:00
|
|
|
.IP Searching
|
2016-11-01 15:40:57 +00:00
|
|
|
A keyring may be considered the root of a tree or subtree in which keyrings
|
2016-11-01 17:45:14 +00:00
|
|
|
form the branches and non-keyrings the leaves.
|
2016-11-07 13:12:41 +00:00
|
|
|
This tree may be searched for a key matching
|
2016-11-01 17:45:14 +00:00
|
|
|
a particular type and description.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 20:54:55 +00:00
|
|
|
See
|
2016-11-01 15:40:57 +00:00
|
|
|
.BR keyctl_clear (3),
|
|
|
|
.BR keyctl_link (3),
|
2016-11-02 17:24:01 +00:00
|
|
|
.BR keyctl_search (3),
|
2016-11-01 15:40:57 +00:00
|
|
|
and
|
|
|
|
.BR keyctl_unlink (3)
|
2016-11-01 20:54:55 +00:00
|
|
|
for more information.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS Anchoring keys
|
2016-12-13 11:42:05 +00:00
|
|
|
To prevent a key from being garbage collected,
|
2018-04-09 14:54:11 +00:00
|
|
|
it must be anchored to keep its reference count elevated
|
2016-11-01 17:45:14 +00:00
|
|
|
when it is not in active use by the kernel.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.PP
|
2016-11-07 13:12:41 +00:00
|
|
|
Keyrings are used to anchor other keys:
|
|
|
|
each link is a reference on a key.
|
|
|
|
Note that keyrings themselves are just keys and
|
2016-11-08 08:47:39 +00:00
|
|
|
are also subject to the same anchoring requirement to prevent
|
|
|
|
them being garbage collected.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.PP
|
2016-11-01 17:45:14 +00:00
|
|
|
The kernel makes available a number of anchor keyrings.
|
2016-11-01 20:58:07 +00:00
|
|
|
Note that some of these keyrings will be created only when first accessed.
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
Process keyrings
|
2016-11-01 15:40:57 +00:00
|
|
|
Process credentials themselves reference keyrings with specific semantics.
|
2016-11-02 02:57:08 +00:00
|
|
|
These keyrings are pinned as long as the set of credentials exists,
|
|
|
|
which is usually as long as the process exists.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP
|
2016-11-01 17:45:14 +00:00
|
|
|
There are three keyrings with different inheritance/sharing rules:
|
2016-11-07 13:12:41 +00:00
|
|
|
the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR session\-keyring (7)
|
2016-11-01 18:08:09 +00:00
|
|
|
(inherited and shared by all child processes),
|
|
|
|
the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR process\-keyring (7)
|
2016-11-01 18:08:09 +00:00
|
|
|
(shared by all threads in a process) and
|
|
|
|
the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR thread\-keyring (7)
|
2016-11-01 18:08:09 +00:00
|
|
|
(specific to a particular thread).
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-25 09:44:27 +00:00
|
|
|
As an alternative to using the actual keyring IDs,
|
|
|
|
in calls to
|
|
|
|
.BR add_key (2),
|
|
|
|
.BR keyctl (2),
|
|
|
|
and
|
|
|
|
.BR request_key (2),
|
|
|
|
the special keyring values
|
|
|
|
.BR KEY_SPEC_SESSION_KEYRING ,
|
|
|
|
.BR KEY_SPEC_PROCESS_KEYRING ,
|
|
|
|
and
|
|
|
|
.BR KEY_SPEC_THREAD_KEYRING
|
|
|
|
can be used to refer to the caller's own instances of these keyrings.
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
User keyrings
|
|
|
|
Each UID known to the kernel has a record that contains two keyrings: the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR user\-keyring (7)
|
2016-11-01 18:08:09 +00:00
|
|
|
and the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR user\-session\-keyring (7).
|
2016-11-01 17:45:14 +00:00
|
|
|
These exist for as long as the UID record in the kernel exists.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-25 09:44:27 +00:00
|
|
|
As an alternative to using the actual keyring IDs,
|
|
|
|
in calls to
|
|
|
|
.BR add_key (2),
|
|
|
|
.BR keyctl (2),
|
|
|
|
and
|
|
|
|
.BR request_key (2),
|
|
|
|
the special keyring values
|
|
|
|
.BR KEY_SPEC_USER_KEYRING
|
|
|
|
and
|
|
|
|
.BR KEY_SPEC_USER_SESSION_KEYRING
|
|
|
|
can be used to refer to the caller's own instances of these keyrings.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-01 17:45:14 +00:00
|
|
|
A link to the user keyring is placed in a new session keyring by
|
2017-03-13 20:17:48 +00:00
|
|
|
.BR pam_keyinit (8)
|
2016-11-01 18:08:09 +00:00
|
|
|
when a new login session is initiated.
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
Persistent keyrings
|
2016-11-01 18:08:09 +00:00
|
|
|
There is a
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR persistent\-keyring (7)
|
2016-11-01 18:08:09 +00:00
|
|
|
available to each UID known to the system.
|
2016-11-01 17:45:14 +00:00
|
|
|
It may persist beyond the life of the UID record previously mentioned,
|
|
|
|
but has an expiration time set such that it is automatically cleaned up
|
|
|
|
after a set time.
|
2016-11-08 08:47:39 +00:00
|
|
|
The persistent keyring permits, for example,
|
2016-11-07 13:12:41 +00:00
|
|
|
.BR cron (8)
|
|
|
|
scripts to use credentials that are left in the persistent keyring after
|
|
|
|
the user logs out.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP
|
2016-11-07 13:12:41 +00:00
|
|
|
Note that the expiration time of the persistent keyring
|
|
|
|
is reset every time the persistent key is requested.
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
Special keyrings
|
2016-11-01 17:45:14 +00:00
|
|
|
There are special keyrings owned by the kernel that can anchor keys
|
|
|
|
for special purposes.
|
2016-11-03 20:30:41 +00:00
|
|
|
An example of this is the \fIsystem keyring\fR used for holding
|
2016-11-01 15:40:57 +00:00
|
|
|
encryption keys for module signature verification.
|
|
|
|
.IP
|
2016-11-02 17:24:01 +00:00
|
|
|
These special keyrings are usually closed to direct alteration
|
|
|
|
by user space.
|
2016-11-25 09:57:26 +00:00
|
|
|
.PP
|
|
|
|
An originally planned "group keyring",
|
|
|
|
for storing keys associated with each GID known to the kernel,
|
|
|
|
is not so far implemented, is unlikely to be implemented.
|
|
|
|
Nevertheless, the constant
|
|
|
|
.BR KEY_SPEC_GROUP_KEYRING
|
|
|
|
has been defined for this keyring.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS Possession
|
2016-11-02 17:24:01 +00:00
|
|
|
The concept of possession is important to understanding the keyrings
|
2016-11-01 17:45:14 +00:00
|
|
|
security model.
|
|
|
|
Whether a thread possesses a key is determined by the following rules:
|
2016-11-02 17:24:01 +00:00
|
|
|
.IP (1) 4
|
|
|
|
Any key or keyring that does not grant
|
|
|
|
.I search
|
|
|
|
permission to the caller is ignored in all the following rules.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP (2)
|
2016-11-07 13:12:41 +00:00
|
|
|
A thread possesses its
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR session\-keyring (7),
|
|
|
|
.BR process\-keyring (7),
|
2016-11-07 13:12:41 +00:00
|
|
|
and
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR thread\-keyring (7)
|
2016-11-07 13:12:41 +00:00
|
|
|
directly because those keyrings are referred to by its credentials.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP (3)
|
2016-11-07 13:12:41 +00:00
|
|
|
If a keyring is possessed, then any key it links to is also possessed.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP (4)
|
|
|
|
If any key a keyring links to is itself a keyring, then rule (3) applies
|
2016-11-07 13:12:41 +00:00
|
|
|
recursively.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP (5)
|
2016-11-07 13:12:41 +00:00
|
|
|
If a process is upcalled from the kernel to instantiate a key (see
|
|
|
|
.BR request_key (2)),
|
|
|
|
then it also possesses the requester's keyrings as in
|
|
|
|
rule (1) as if it were the requester.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 17:45:14 +00:00
|
|
|
Note that possession is not a fundamental property of a key,
|
2016-11-02 17:24:01 +00:00
|
|
|
but must rather be calculated each time the key is needed.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-02 17:24:01 +00:00
|
|
|
Possession is designed to allow set-user-ID programs run from, say
|
|
|
|
a user's shell to access the user's keys.
|
2016-11-07 13:12:41 +00:00
|
|
|
Granting permissions to the key possessor while denying them
|
2016-11-08 08:47:39 +00:00
|
|
|
to the key owner and group allows the prevention of access to keys
|
2016-11-07 13:12:41 +00:00
|
|
|
on the basis of UID and GID matches.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 18:08:09 +00:00
|
|
|
When it creates the session keyring,
|
|
|
|
.BR pam_keyinit (8)
|
2016-11-02 17:24:01 +00:00
|
|
|
adds a link to the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR user\-keyring (7),
|
2016-11-01 18:08:09 +00:00
|
|
|
thus making the user keyring and anything it contains possessed by default.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS Access rights
|
2016-11-01 15:40:57 +00:00
|
|
|
Each key has the following security-related attributes:
|
2016-11-02 17:24:01 +00:00
|
|
|
.IP * 3
|
|
|
|
The owning user ID
|
|
|
|
.IP *
|
|
|
|
The ID of a group that is permitted to access the key
|
|
|
|
.IP *
|
|
|
|
A security label
|
|
|
|
.IP *
|
|
|
|
A permissions mask
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 17:45:14 +00:00
|
|
|
The permissions mask contains four sets of rights.
|
|
|
|
The first three sets are mutually exclusive.
|
2016-11-02 17:24:01 +00:00
|
|
|
One and only one will be in force for a particular access check.
|
|
|
|
In order of descending priority, these three sets are:
|
|
|
|
.IP \fIuser\fR
|
|
|
|
The set specifies the rights granted
|
|
|
|
if the key's user ID matches the caller's filesystem user ID.
|
|
|
|
.IP \fIgroup\fR
|
|
|
|
The set specifies the rights granted
|
|
|
|
if the user ID didn't match and the key's group ID matches the caller's
|
|
|
|
filesystem GID or one of the caller's supplementary group IDs.
|
|
|
|
.IP \fIother\fR
|
|
|
|
The set specifies the rights granted
|
|
|
|
if neither the key's user ID nor group ID matched.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 15:40:57 +00:00
|
|
|
The fourth set of rights is:
|
2016-11-02 17:24:01 +00:00
|
|
|
.IP \fIpossessor\fR
|
|
|
|
The set specifies the rights granted
|
|
|
|
if a key is determined to be possessed by the caller.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-02 17:24:01 +00:00
|
|
|
The complete set of rights for a key is the union of whichever
|
|
|
|
of the first three sets is applicable plus the fourth set
|
2016-11-01 17:45:14 +00:00
|
|
|
if the key is possessed.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-02 17:24:01 +00:00
|
|
|
The set of rights that may be granted in each of the four masks
|
|
|
|
is as follows:
|
|
|
|
.TP
|
|
|
|
.I view
|
|
|
|
The attributes of the key may be read.
|
|
|
|
This includes the type,
|
|
|
|
description, and access rights (excluding the security label).
|
|
|
|
.TP
|
|
|
|
.I read
|
|
|
|
For a key: the payload of the key may be read.
|
|
|
|
For a keyring: the list of serial numbers (keys) to
|
|
|
|
which the keyring has links may be read.
|
|
|
|
.TP
|
|
|
|
.I write
|
2016-11-07 13:12:41 +00:00
|
|
|
The payload of the key may be updated and the key may be revoked.
|
2016-11-02 17:24:01 +00:00
|
|
|
For a keyring, links may be added to or removed from the keyring,
|
2016-11-07 13:12:41 +00:00
|
|
|
and the keyring may be cleared completely (all links are removed),
|
2016-11-02 17:24:01 +00:00
|
|
|
.TP
|
|
|
|
.I search
|
|
|
|
For a key (or a keyring): the key may be found by a search.
|
|
|
|
For a keyring: keys and keyrings that are linked to by the
|
|
|
|
keyring may be searched.
|
|
|
|
.TP
|
|
|
|
.I link
|
|
|
|
Links may be created from keyrings to the key.
|
|
|
|
The initial link to a key that is established when the key is created
|
|
|
|
doesn't require this permission.
|
|
|
|
.TP
|
|
|
|
.I setattr
|
|
|
|
The ownership details and security label of the key may be changed,
|
|
|
|
the key's expiration time may be set, and the key may be revoked.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-02 17:24:01 +00:00
|
|
|
In addition to access rights, any active Linux Security Module (LSM) may
|
2016-11-01 17:45:14 +00:00
|
|
|
prevent access to a key if its policy so dictates.
|
|
|
|
A key may be given a
|
2016-11-07 13:12:41 +00:00
|
|
|
security label or other attribute by the LSM;
|
|
|
|
this label is retrievable via
|
|
|
|
.BR keyctl_get_security (3).
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 20:54:55 +00:00
|
|
|
See
|
2016-11-01 15:40:57 +00:00
|
|
|
.BR keyctl_chown (3),
|
|
|
|
.BR keyctl_describe (3),
|
|
|
|
.BR keyctl_get_security (3),
|
2016-11-02 17:24:01 +00:00
|
|
|
.BR keyctl_setperm (3),
|
2016-11-01 15:40:57 +00:00
|
|
|
and
|
|
|
|
.BR selinux (8)
|
2016-11-01 20:54:55 +00:00
|
|
|
for more information.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS Searching for keys
|
2016-11-02 17:24:01 +00:00
|
|
|
One of the key features of the Linux key-management facility
|
|
|
|
is the ability to find a key that a process is retaining.
|
2016-11-01 18:08:09 +00:00
|
|
|
The
|
|
|
|
.BR request_key (2)
|
|
|
|
system call is the primary point of
|
2016-11-02 17:24:01 +00:00
|
|
|
access for user-space applications to find a key.
|
2016-11-07 13:12:41 +00:00
|
|
|
(Internally, the kernel has something similar available
|
2016-11-02 17:24:01 +00:00
|
|
|
for use by internal components that make use of keys.)
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 15:40:57 +00:00
|
|
|
The search algorithm works as follows:
|
2016-11-02 17:24:01 +00:00
|
|
|
.IP (1) 4
|
2016-11-07 13:12:41 +00:00
|
|
|
The process keyrings are searched in the following order: the thread
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR thread\-keyring (7)
|
2016-11-02 17:24:01 +00:00
|
|
|
if it exists, the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR process\-keyring (7)
|
2016-11-02 17:24:01 +00:00
|
|
|
if it exists, and then either the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR session\-keyring (7)
|
2016-11-01 18:08:09 +00:00
|
|
|
if it exists or the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR user\-session\-keyring (7)
|
2016-11-01 18:08:09 +00:00
|
|
|
if that exists.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP (2)
|
2016-11-02 02:52:46 +00:00
|
|
|
If the caller was a process that was invoked by the
|
|
|
|
.BR request_key (2)
|
2016-11-07 13:12:41 +00:00
|
|
|
upcall mechanism, then the keyrings of the original caller of
|
2016-11-02 02:52:46 +00:00
|
|
|
.BR request_key (2)
|
2016-11-01 15:40:57 +00:00
|
|
|
will be searched as well.
|
|
|
|
.IP (3)
|
2016-12-13 11:42:05 +00:00
|
|
|
The search of a keyring tree is in breadth-first order:
|
2016-11-02 17:24:01 +00:00
|
|
|
each keyring is searched first for a match,
|
|
|
|
then the keyrings referred to by that keyring are searched.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP (4)
|
2016-11-02 17:24:01 +00:00
|
|
|
If a matching key is found that is valid,
|
|
|
|
then the search terminates and that key is returned.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP (5)
|
2016-11-02 17:24:01 +00:00
|
|
|
If a matching key is found that has an error state attached,
|
|
|
|
that error state is noted and the search continues.
|
2016-11-01 15:40:57 +00:00
|
|
|
.IP (6)
|
2016-11-07 16:12:17 +00:00
|
|
|
If no valid matching key is found,
|
2017-03-13 20:17:48 +00:00
|
|
|
then the first noted error state is returned; otherwise, an
|
2016-11-02 17:24:01 +00:00
|
|
|
.B ENOKEY
|
|
|
|
error is returned.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-07 13:09:55 +00:00
|
|
|
It is also possible to search a specific keyring, in which case only steps
|
|
|
|
(3) to (6) apply.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 18:08:09 +00:00
|
|
|
See
|
2016-11-01 15:40:57 +00:00
|
|
|
.BR request_key (2)
|
|
|
|
and
|
|
|
|
.BR keyctl_search (3)
|
2016-11-01 18:08:09 +00:00
|
|
|
for more information.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS On-demand key creation
|
2016-11-01 18:08:09 +00:00
|
|
|
If a key cannot be found,
|
|
|
|
.BR request_key (2)
|
|
|
|
will, if given a
|
|
|
|
.I callout_info
|
2016-11-01 21:02:20 +00:00
|
|
|
argument, create a new key and then upcall to user space to
|
2016-11-01 17:45:14 +00:00
|
|
|
instantiate the key.
|
|
|
|
This allows keys to be created on an as-needed basis.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-07 13:12:41 +00:00
|
|
|
Typically,
|
|
|
|
this will involve the kernel creating a new process that executes the
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR request\-key (8)
|
2016-11-01 21:02:20 +00:00
|
|
|
program, which will then execute the appropriate handler based on its
|
2016-11-01 15:40:57 +00:00
|
|
|
configuration.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-02 17:24:01 +00:00
|
|
|
The handler is passed a special authorization key that allows it
|
|
|
|
and only it to instantiate the new key.
|
2016-11-01 17:45:14 +00:00
|
|
|
This is also used to permit searches performed by the
|
2016-11-01 15:40:57 +00:00
|
|
|
handler program to also search the requester's keyrings.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 20:54:55 +00:00
|
|
|
See
|
2016-11-02 17:24:01 +00:00
|
|
|
.BR request_key (2),
|
2016-11-01 15:40:57 +00:00
|
|
|
.BR keyctl_assume_authority (3),
|
|
|
|
.BR keyctl_instantiate (3),
|
|
|
|
.BR keyctl_negate (3),
|
|
|
|
.BR keyctl_reject (3),
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR request\-key (8),
|
2016-11-01 15:40:57 +00:00
|
|
|
and
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR request\-key.conf (5)
|
2016-11-01 20:54:55 +00:00
|
|
|
for more information.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-03 19:44:51 +00:00
|
|
|
.SS /proc files
|
2016-11-03 20:26:37 +00:00
|
|
|
The kernel provides various
|
|
|
|
.I /proc
|
|
|
|
files that expose information about keys or define limits on key usage.
|
2016-11-03 18:46:16 +00:00
|
|
|
.TP
|
2016-11-03 19:06:44 +00:00
|
|
|
.IR /proc/keys " (since Linux 2.6.10)"
|
2016-11-07 23:57:13 +00:00
|
|
|
This file exposes a list of the keys for which the reading thread has
|
|
|
|
.I view
|
|
|
|
permission, providing various information about each key.
|
2016-11-07 23:59:34 +00:00
|
|
|
The thread need not possess the key for it to be visible in this file.
|
2016-12-13 11:42:05 +00:00
|
|
|
.\" David Howells, Dec 2016 linux-man@:
|
|
|
|
.\" This [The thread need not possess the key for it to be visible in
|
|
|
|
.\" this file.] is correct. See proc_keys_show() in security/keys/proc.c:
|
2017-03-13 20:17:48 +00:00
|
|
|
.\"
|
2016-12-13 11:42:05 +00:00
|
|
|
.\" rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW);
|
|
|
|
.\" if (rc < 0)
|
|
|
|
.\" return 0;
|
|
|
|
.\"
|
|
|
|
.\"Possibly it shouldn't be, but for now it is.
|
|
|
|
.\"
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 19:44:51 +00:00
|
|
|
The only keys included in the list are those that grant
|
|
|
|
.I view
|
2016-12-13 11:42:05 +00:00
|
|
|
permission to the reading process
|
|
|
|
(regardless of whether or not it possesses them).
|
2016-11-03 19:44:51 +00:00
|
|
|
LSM security checks are still performed,
|
2016-11-04 02:39:51 +00:00
|
|
|
and may filter out further keys that the process is not authorized to view.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-12-16 15:35:10 +00:00
|
|
|
An example of the data that one might see in this file
|
|
|
|
(with the columns numbered for easy reference below)
|
|
|
|
is the following:
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2017-08-19 08:56:06 +00:00
|
|
|
.EX
|
2016-12-16 15:35:10 +00:00
|
|
|
(1) (2) (3)(4) (5) (6) (7) (8) (9)
|
2016-11-03 19:44:51 +00:00
|
|
|
009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
|
|
|
|
1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
|
|
|
|
25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
|
|
|
|
28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1
|
|
|
|
2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2
|
|
|
|
30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1
|
|
|
|
32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2
|
|
|
|
32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
|
|
|
|
3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1
|
execve.2, ioctl_console.2, ioctl_iflags.2, ioctl_ns.2, ioctl_userfaultfd.2, kcmp.2, kexec_load.2, keyctl.2, link.2, listxattr.2, membarrier.2, memfd_create.2, mmap.2, modify_ldt.2, mprotect.2, msgctl.2, nanosleep.2, open_by_handle_at.2, perf_event_open.2, poll.2, posix_fadvise.2, process_vm_readv.2, ptrace.2, query_module.2, quotactl.2, readdir.2, readv.2, recv.2, recvmmsg.2, request_key.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setattr.2, sched_setscheduler.2, seccomp.2, select.2, select_tut.2, semctl.2, semop.2, send.2, sendmmsg.2, set_thread_area.2, setns.2, shmctl.2, shmget.2, sigaction.2, sigaltstack.2, signal.2, sigwaitinfo.2, stat.2, statfs.2, statx.2, sync_file_range.2, syscall.2, sysctl.2, sysinfo.2, tee.2, timer_create.2, timer_settime.2, timerfd_create.2, unshare.2, userfaultfd.2, ustat.2, utime.2, utimensat.2, vmsplice.2, wait.2, adjtime.3, aio_init.3, backtrace.3, basename.3, bswap.3, btree.3, clock_getcpuclockid.3, cmsg.3, confstr.3, dbopen.3, dl_iterate_phdr.3, dladdr.3, dlinfo.3, dlopen.3, duplocale.3, encrypt.3, end.3, endian.3, err.3, errno.3, ether_aton.3, fgetgrent.3, fgetpwent.3, fmemopen.3, frexp.3, ftime.3, fts.3, getaddrinfo.3, getaddrinfo_a.3, getdate.3, getfsent.3, getgrent.3, getgrent_r.3, getgrnam.3, getgrouplist.3, gethostbyname.3, getifaddrs.3, getipnodebyname.3, getmntent.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getprotoent_r.3, getpw.3, getpwent.3, getpwent_r.3, getpwnam.3, getrpcent.3, getservent.3, getservent_r.3, getspnam.3, getttyent.3, glob.3, gnu_get_libc_version.3, hash.3, hsearch.3, if_nameindex.3, inet.3, inet_net_pton.3, inet_pton.3, insque.3, isalpha.3, makecontext.3, mallinfo.3, malloc_info.3, mallopt.3, matherr.3, mbstowcs.3, mcheck.3, memchr.3, mq_getattr.3, mq_open.3, mq_receive.3, mq_send.3, mtrace.3, newlocale.3, ntp_gettime.3, posix_openpt.3, printf.3, pthread_attr_init.3, pthread_attr_setschedparam.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_cleanup_push_defer_np.3, pthread_create.3, pthread_getattr_default_np.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setname_np.3, pthread_setschedparam.3, pthread_sigmask.3, pthread_tryjoin_np.3, readdir.3, realpath.3, recno.3, regex.3, rpc.3, scanf.3, sched_getcpu.3, sem_wait.3, setaliasent.3, sigqueue.3, statvfs.3, strcat.3, strcpy.3, strftime.3, strtok.3, strtol.3, strverscmp.3, toupper.3, ttyslot.3, xdr.3, fuse.4, loop.4, rtc.4, st.4, acct.5, core.5, elf.5, slabinfo.5, aio.7, arp.7, capabilities.7, cgroup_namespaces.7, cgroups.7, ddp.7, fanotify.7, feature_test_macros.7, inode.7, inotify.7, ip.7, keyrings.7, locale.7, mount_namespaces.7, namespaces.7, netdevice.7, netlink.7, packet.7, pkeys.7, pthreads.7, sched.7, session-keyring.7, sock_diag.7, socket.7, spufs.7, udplite.7, unix.7, user_namespaces.7, vdso.7, x25.7, ld.so.8: Use consistent markup for code snippets
Change .nf/.fi to .EX/.EE
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-18 19:52:46 +00:00
|
|
|
.EE
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 19:44:51 +00:00
|
|
|
The fields shown in each line of this file are as follows:
|
|
|
|
.RS
|
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
ID (1)
|
2016-11-03 19:44:51 +00:00
|
|
|
The ID (serial number) of the key, expressed in hexadecimal.
|
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
Flags (2)
|
2016-11-03 19:44:51 +00:00
|
|
|
A set of flags describing the state of the key:
|
|
|
|
.RS
|
|
|
|
.IP I 4
|
2016-12-15 07:28:36 +00:00
|
|
|
.\" KEY_FLAG_INSTANTIATED
|
2016-11-03 19:44:51 +00:00
|
|
|
The key has been instantiated.
|
|
|
|
.IP R
|
2016-12-15 07:28:36 +00:00
|
|
|
.\" KEY_FLAG_REVOKED
|
2016-11-03 19:44:51 +00:00
|
|
|
The key has been revoked.
|
|
|
|
.IP D
|
2016-12-15 07:28:36 +00:00
|
|
|
.\" KEY_FLAG_DEAD
|
2016-12-13 13:36:09 +00:00
|
|
|
The key is dead (i.e., the key type has been unregistered).
|
2016-12-13 11:42:05 +00:00
|
|
|
.\" unregister_key_type() in the kernel source
|
2016-11-03 19:44:51 +00:00
|
|
|
(A key may be briefly in this state during garbage collection.)
|
|
|
|
.IP Q
|
2016-12-15 07:28:36 +00:00
|
|
|
.\" KEY_FLAG_IN_QUOTA
|
2016-11-03 19:44:51 +00:00
|
|
|
The key contributes to the user's quota.
|
|
|
|
.IP U
|
2016-12-15 07:28:36 +00:00
|
|
|
.\" KEY_FLAG_USER_CONSTRUCT
|
2016-11-03 19:44:51 +00:00
|
|
|
The key is under construction via a callback to user space;
|
|
|
|
see
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR request\-key (2).
|
2016-11-03 19:44:51 +00:00
|
|
|
.IP N
|
2016-12-15 07:28:36 +00:00
|
|
|
.\" KEY_FLAG_NEGATIVE
|
2016-11-03 19:44:51 +00:00
|
|
|
The key is negatively instantiated.
|
|
|
|
.IP i
|
2016-12-15 07:28:36 +00:00
|
|
|
.\" KEY_FLAG_INVALIDATED
|
2016-11-03 19:44:51 +00:00
|
|
|
The key has been invalidated.
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
Usage (3)
|
2016-11-03 20:26:37 +00:00
|
|
|
This is a count of the number of kernel credential
|
|
|
|
structures that are pinning the key
|
2016-11-03 20:30:41 +00:00
|
|
|
(approximately: the number of threads and open file references
|
2016-11-03 20:26:37 +00:00
|
|
|
that refer to this key).
|
2016-11-03 19:44:51 +00:00
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
Timeout (4)
|
2016-11-03 19:44:51 +00:00
|
|
|
The amount of time until the key will expire,
|
|
|
|
expressed in human-readable form (weeks, days, hours, minutes, and seconds).
|
|
|
|
The string
|
|
|
|
.I perm
|
|
|
|
here means that the key is permanent (no timeout).
|
|
|
|
The string
|
|
|
|
.I expd
|
|
|
|
means that the key has already expired,
|
|
|
|
but has not yet been garbage collected.
|
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
Permissions (5)
|
2016-11-03 20:30:41 +00:00
|
|
|
The key permissions, expressed as four hexadecimal bytes containing,
|
|
|
|
from left to right, the possessor, user, group, and other permissions.
|
2016-11-07 15:32:44 +00:00
|
|
|
Within each byte, the permission bits are as follows:
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-07 15:32:44 +00:00
|
|
|
.PD 0
|
|
|
|
.RS 12
|
|
|
|
.TP
|
|
|
|
0x01
|
|
|
|
.I view
|
|
|
|
.TP
|
|
|
|
Ox02
|
|
|
|
.I read
|
|
|
|
.TP
|
|
|
|
0x04
|
|
|
|
.I write
|
|
|
|
.TP
|
|
|
|
0x08
|
|
|
|
.I search
|
|
|
|
.TP
|
|
|
|
0x10
|
|
|
|
.I link
|
|
|
|
.TP
|
|
|
|
0x20
|
|
|
|
.I setattr
|
|
|
|
.RE
|
|
|
|
.PD
|
2016-11-03 19:44:51 +00:00
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
UID (6)
|
2016-11-03 19:44:51 +00:00
|
|
|
The user ID of the key owner.
|
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
GID (7)
|
2016-11-03 19:44:51 +00:00
|
|
|
The group ID of the key.
|
2016-11-07 13:12:41 +00:00
|
|
|
The value \-1 here means that the key has no group ID;
|
2016-11-03 20:26:37 +00:00
|
|
|
this can occur in certain circumstances for keys created by the kernel.
|
2016-11-03 19:44:51 +00:00
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
Type (8)
|
2016-11-03 19:44:51 +00:00
|
|
|
The key type (user, keyring, etc.)
|
|
|
|
.TP
|
2016-12-16 15:35:10 +00:00
|
|
|
Description (9)
|
2016-11-03 19:44:51 +00:00
|
|
|
The key description (name).
|
2016-11-04 02:39:51 +00:00
|
|
|
This field contains descriptive information about the key.
|
|
|
|
For most key types, it has the form
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-04 22:13:42 +00:00
|
|
|
name[: extra\-info]
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-04 02:39:51 +00:00
|
|
|
The
|
|
|
|
.I name
|
2017-01-03 23:36:55 +00:00
|
|
|
subfield is the key's description (name).
|
2016-11-04 02:39:51 +00:00
|
|
|
The optional
|
|
|
|
.I extra\-info
|
|
|
|
field provides some further information about the key.
|
|
|
|
The information that appears here depends on the key type, as follows:
|
|
|
|
.RS
|
getent.1, localedef.1, clock_nanosleep.2, fcntl.2, getitimer.2, getsockopt.2, inotify_init.2, ioctl.2, mlock.2, mprotect.2, quotactl.2, s390_sthyi.2, semctl.2, shmctl.2, shmget.2, wait.2, CPU_SET.3, aio_init.3, des_crypt.3, fmemopen.3, fopencookie.3, fts.3, getaddrinfo.3, getrpcent.3, lio_listio.3, posix_spawn.3, shm_open.3, st.4, elf.5, group.5, proc.5, services.5, aio.7, feature_test_macros.7, keyrings.7, man-pages.7, sigevent.7, tcp.7, udp.7: Global formatting fix: disfavor nonstandard .TP indents
In many cases, these don't improve readability, and (when stacked)
they sometimes have the side effect of sometimes forcing text
to be justified within a narrow column range.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-19 13:22:55 +00:00
|
|
|
.TP
|
2016-11-04 02:39:51 +00:00
|
|
|
.IR """user""" " and " """logon"""
|
|
|
|
The size in bytes of the key payload (expressed in decimal).
|
|
|
|
.TP
|
|
|
|
.IR """keyring"""
|
|
|
|
The number of keys linked to the keyring,
|
2016-11-03 19:44:51 +00:00
|
|
|
or the string
|
|
|
|
.IR empty
|
|
|
|
if there are no keys linked to the keyring.
|
2016-11-04 02:39:51 +00:00
|
|
|
.TP
|
|
|
|
.IR """big_key"""
|
|
|
|
The payload size in bytes, followed either by the string
|
|
|
|
.IR [file] ,
|
|
|
|
if the key payload exceeds the threshold that means that the
|
2016-11-07 13:12:41 +00:00
|
|
|
payload is stored in a (swappable)
|
|
|
|
.BR tmpfs (5)
|
|
|
|
filesystem,
|
2016-11-04 02:39:51 +00:00
|
|
|
or otherwise the string
|
|
|
|
.IR [buff] ,
|
|
|
|
indicating that the key is small enough to reside in kernel memory.
|
|
|
|
.RE
|
|
|
|
.IP
|
|
|
|
For the
|
|
|
|
.IR """.request_key_auth"""
|
|
|
|
key type
|
|
|
|
(authorization key; see
|
|
|
|
.BR request_key (2)),
|
|
|
|
the description field has the form shown in the following example:
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-04 02:39:51 +00:00
|
|
|
key:c9a9b19 pid:28880 ci:10
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-04 02:39:51 +00:00
|
|
|
The three subfields are as follows:
|
|
|
|
.RS
|
getent.1, localedef.1, clock_nanosleep.2, fcntl.2, getitimer.2, getsockopt.2, inotify_init.2, ioctl.2, mlock.2, mprotect.2, quotactl.2, s390_sthyi.2, semctl.2, shmctl.2, shmget.2, wait.2, CPU_SET.3, aio_init.3, des_crypt.3, fmemopen.3, fopencookie.3, fts.3, getaddrinfo.3, getrpcent.3, lio_listio.3, posix_spawn.3, shm_open.3, st.4, elf.5, group.5, proc.5, services.5, aio.7, feature_test_macros.7, keyrings.7, man-pages.7, sigevent.7, tcp.7, udp.7: Global formatting fix: disfavor nonstandard .TP indents
In many cases, these don't improve readability, and (when stacked)
they sometimes have the side effect of sometimes forcing text
to be justified within a narrow column range.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-19 13:22:55 +00:00
|
|
|
.TP
|
2016-11-04 02:39:51 +00:00
|
|
|
.I key
|
|
|
|
The hexadecimal ID of the key being instantiated in the requesting program.
|
|
|
|
.TP
|
|
|
|
.I pid
|
|
|
|
The PID of the requesting program.
|
|
|
|
.TP
|
|
|
|
.I ci
|
|
|
|
The length of the callout data with which the requested key should
|
|
|
|
be instantiated
|
|
|
|
(i.e., the length of the payload associated with the authorization key).
|
|
|
|
.RE
|
2016-11-03 19:44:51 +00:00
|
|
|
.RE
|
2016-11-03 19:06:44 +00:00
|
|
|
.TP
|
|
|
|
.IR /proc/key-users " (since Linux 2.6.10)"
|
|
|
|
This file lists various information for each user ID that
|
|
|
|
has at least one key on the system.
|
|
|
|
An example of the data that one might see in this file is the following:
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 19:06:44 +00:00
|
|
|
.in +4n
|
execve.2, ioctl_console.2, ioctl_iflags.2, ioctl_ns.2, ioctl_userfaultfd.2, kcmp.2, kexec_load.2, keyctl.2, link.2, listxattr.2, membarrier.2, memfd_create.2, mmap.2, modify_ldt.2, mprotect.2, msgctl.2, nanosleep.2, open_by_handle_at.2, perf_event_open.2, poll.2, posix_fadvise.2, process_vm_readv.2, ptrace.2, query_module.2, quotactl.2, readdir.2, readv.2, recv.2, recvmmsg.2, request_key.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setattr.2, sched_setscheduler.2, seccomp.2, select.2, select_tut.2, semctl.2, semop.2, send.2, sendmmsg.2, set_thread_area.2, setns.2, shmctl.2, shmget.2, sigaction.2, sigaltstack.2, signal.2, sigwaitinfo.2, stat.2, statfs.2, statx.2, sync_file_range.2, syscall.2, sysctl.2, sysinfo.2, tee.2, timer_create.2, timer_settime.2, timerfd_create.2, unshare.2, userfaultfd.2, ustat.2, utime.2, utimensat.2, vmsplice.2, wait.2, adjtime.3, aio_init.3, backtrace.3, basename.3, bswap.3, btree.3, clock_getcpuclockid.3, cmsg.3, confstr.3, dbopen.3, dl_iterate_phdr.3, dladdr.3, dlinfo.3, dlopen.3, duplocale.3, encrypt.3, end.3, endian.3, err.3, errno.3, ether_aton.3, fgetgrent.3, fgetpwent.3, fmemopen.3, frexp.3, ftime.3, fts.3, getaddrinfo.3, getaddrinfo_a.3, getdate.3, getfsent.3, getgrent.3, getgrent_r.3, getgrnam.3, getgrouplist.3, gethostbyname.3, getifaddrs.3, getipnodebyname.3, getmntent.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getprotoent_r.3, getpw.3, getpwent.3, getpwent_r.3, getpwnam.3, getrpcent.3, getservent.3, getservent_r.3, getspnam.3, getttyent.3, glob.3, gnu_get_libc_version.3, hash.3, hsearch.3, if_nameindex.3, inet.3, inet_net_pton.3, inet_pton.3, insque.3, isalpha.3, makecontext.3, mallinfo.3, malloc_info.3, mallopt.3, matherr.3, mbstowcs.3, mcheck.3, memchr.3, mq_getattr.3, mq_open.3, mq_receive.3, mq_send.3, mtrace.3, newlocale.3, ntp_gettime.3, posix_openpt.3, printf.3, pthread_attr_init.3, pthread_attr_setschedparam.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_cleanup_push_defer_np.3, pthread_create.3, pthread_getattr_default_np.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setname_np.3, pthread_setschedparam.3, pthread_sigmask.3, pthread_tryjoin_np.3, readdir.3, realpath.3, recno.3, regex.3, rpc.3, scanf.3, sched_getcpu.3, sem_wait.3, setaliasent.3, sigqueue.3, statvfs.3, strcat.3, strcpy.3, strftime.3, strtok.3, strtol.3, strverscmp.3, toupper.3, ttyslot.3, xdr.3, fuse.4, loop.4, rtc.4, st.4, acct.5, core.5, elf.5, slabinfo.5, aio.7, arp.7, capabilities.7, cgroup_namespaces.7, cgroups.7, ddp.7, fanotify.7, feature_test_macros.7, inode.7, inotify.7, ip.7, keyrings.7, locale.7, mount_namespaces.7, namespaces.7, netdevice.7, netlink.7, packet.7, pkeys.7, pthreads.7, sched.7, session-keyring.7, sock_diag.7, socket.7, spufs.7, udplite.7, unix.7, user_namespaces.7, vdso.7, x25.7, ld.so.8: Use consistent markup for code snippets
Change .nf/.fi to .EX/.EE
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-18 19:52:46 +00:00
|
|
|
.EX
|
2016-11-03 19:06:44 +00:00
|
|
|
0: 10 9/9 2/1000000 22/25000000
|
|
|
|
42: 9 9/9 8/200 106/20000
|
|
|
|
1000: 11 11/11 10/200 271/20000
|
execve.2, ioctl_console.2, ioctl_iflags.2, ioctl_ns.2, ioctl_userfaultfd.2, kcmp.2, kexec_load.2, keyctl.2, link.2, listxattr.2, membarrier.2, memfd_create.2, mmap.2, modify_ldt.2, mprotect.2, msgctl.2, nanosleep.2, open_by_handle_at.2, perf_event_open.2, poll.2, posix_fadvise.2, process_vm_readv.2, ptrace.2, query_module.2, quotactl.2, readdir.2, readv.2, recv.2, recvmmsg.2, request_key.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setattr.2, sched_setscheduler.2, seccomp.2, select.2, select_tut.2, semctl.2, semop.2, send.2, sendmmsg.2, set_thread_area.2, setns.2, shmctl.2, shmget.2, sigaction.2, sigaltstack.2, signal.2, sigwaitinfo.2, stat.2, statfs.2, statx.2, sync_file_range.2, syscall.2, sysctl.2, sysinfo.2, tee.2, timer_create.2, timer_settime.2, timerfd_create.2, unshare.2, userfaultfd.2, ustat.2, utime.2, utimensat.2, vmsplice.2, wait.2, adjtime.3, aio_init.3, backtrace.3, basename.3, bswap.3, btree.3, clock_getcpuclockid.3, cmsg.3, confstr.3, dbopen.3, dl_iterate_phdr.3, dladdr.3, dlinfo.3, dlopen.3, duplocale.3, encrypt.3, end.3, endian.3, err.3, errno.3, ether_aton.3, fgetgrent.3, fgetpwent.3, fmemopen.3, frexp.3, ftime.3, fts.3, getaddrinfo.3, getaddrinfo_a.3, getdate.3, getfsent.3, getgrent.3, getgrent_r.3, getgrnam.3, getgrouplist.3, gethostbyname.3, getifaddrs.3, getipnodebyname.3, getmntent.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getprotoent_r.3, getpw.3, getpwent.3, getpwent_r.3, getpwnam.3, getrpcent.3, getservent.3, getservent_r.3, getspnam.3, getttyent.3, glob.3, gnu_get_libc_version.3, hash.3, hsearch.3, if_nameindex.3, inet.3, inet_net_pton.3, inet_pton.3, insque.3, isalpha.3, makecontext.3, mallinfo.3, malloc_info.3, mallopt.3, matherr.3, mbstowcs.3, mcheck.3, memchr.3, mq_getattr.3, mq_open.3, mq_receive.3, mq_send.3, mtrace.3, newlocale.3, ntp_gettime.3, posix_openpt.3, printf.3, pthread_attr_init.3, pthread_attr_setschedparam.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_cleanup_push_defer_np.3, pthread_create.3, pthread_getattr_default_np.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setname_np.3, pthread_setschedparam.3, pthread_sigmask.3, pthread_tryjoin_np.3, readdir.3, realpath.3, recno.3, regex.3, rpc.3, scanf.3, sched_getcpu.3, sem_wait.3, setaliasent.3, sigqueue.3, statvfs.3, strcat.3, strcpy.3, strftime.3, strtok.3, strtol.3, strverscmp.3, toupper.3, ttyslot.3, xdr.3, fuse.4, loop.4, rtc.4, st.4, acct.5, core.5, elf.5, slabinfo.5, aio.7, arp.7, capabilities.7, cgroup_namespaces.7, cgroups.7, ddp.7, fanotify.7, feature_test_macros.7, inode.7, inotify.7, ip.7, keyrings.7, locale.7, mount_namespaces.7, namespaces.7, netdevice.7, netlink.7, packet.7, pkeys.7, pthreads.7, sched.7, session-keyring.7, sock_diag.7, socket.7, spufs.7, udplite.7, unix.7, user_namespaces.7, vdso.7, x25.7, ld.so.8: Use consistent markup for code snippets
Change .nf/.fi to .EX/.EE
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-18 19:52:46 +00:00
|
|
|
.EE
|
ioctl_console.2, ioctl_getfsmap.2, ioctl_iflags.2, ioctl_list.2, ioctl_ns.2, kcmp.2, kexec_load.2, keyctl.2, link.2, mmap.2, modify_ldt.2, msgctl.2, poll.2, query_module.2, quotactl.2, recv.2, recvmmsg.2, sched_setscheduler.2, seccomp.2, select.2, semctl.2, semop.2, send.2, set_thread_area.2, setns.2, shmctl.2, shmget.2, sigaction.2, sysinfo.2, timer_create.2, timerfd_create.2, uname.2, unshare.2, userfaultfd.2, ustat.2, utimensat.2, vmsplice.2, wait.2, adjtime.3, backtrace.3, bswap.3, btree.3, clock_getcpuclockid.3, confstr.3, dbopen.3, dl_iterate_phdr.3, dlinfo.3, duplocale.3, encrypt.3, end.3, endian.3, err.3, errno.3, fmemopen.3, fopencookie.3, frexp.3, fts.3, ftw.3, getaddrinfo.3, getaddrinfo_a.3, getcontext.3, getgrouplist.3, getifaddrs.3, getipnodebyname.3, getnameinfo.3, getopt.3, getprotoent_r.3, getpwent_r.3, getrpcent.3, getservent_r.3, getttyent.3, getumask.3, glob.3, gnu_get_libc_version.3, hash.3, hsearch.3, inet.3, inet_pton.3, insque.3, isalpha.3, makecontext.3, mallopt.3, mbstowcs.3, mcheck.3, memchr.3, mq_getattr.3, mq_open.3, mtrace.3, newlocale.3, ntp_gettime.3, offsetof.3, posix_openpt.3, printf.3, pthread_setname_np.3, pthread_setschedparam.3, rpc.3, scanf.3, sched_getcpu.3, sem_wait.3, setaliasent.3, sigqueue.3, sigvec.3, stdarg.3, strcat.3, strcpy.3, strftime.3, strtol.3, toupper.3, ttyslot.3, fuse.4, loop.4, st.4, elf.5, cgroup_namespaces.7, cgroups.7, feature_test_macros.7, inode.7, inotify.7, keyrings.7, man-pages.7, math_error.7, mount_namespaces.7, mq_overview.7, pthreads.7, sched.7, session-keyring.7, udplite.7, unix.7, vdso.7: Use consistent markup for code snippets
The preferred form is
.PP/.IP
.in +4n
.EX
<code>
.EE
.in
.PP/.IP
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-18 19:37:55 +00:00
|
|
|
.in
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 19:06:44 +00:00
|
|
|
The fields shown in each line are as follows:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.I uid
|
|
|
|
The user ID.
|
|
|
|
.TP
|
|
|
|
.I usage
|
2016-11-03 20:26:37 +00:00
|
|
|
This is a kernel-internal usage count for the kernel structure
|
|
|
|
used to record key users.
|
2016-11-03 19:06:44 +00:00
|
|
|
.TP
|
|
|
|
.IR nkeys / nikeys
|
|
|
|
The total number of keys owned by the user,
|
|
|
|
and the number of those keys that have been instantiated.
|
|
|
|
.TP
|
|
|
|
.IR qnkeys / maxkeys
|
|
|
|
The number of keys owned by the user,
|
2016-11-07 13:12:41 +00:00
|
|
|
and the maximum number of keys that the user may own.
|
2016-11-03 19:06:44 +00:00
|
|
|
.TP
|
|
|
|
.IR qnbytes / maxbytes
|
|
|
|
The number of bytes consumed in payloads of the keys owned by this user,
|
|
|
|
and the upper limit on the number of bytes in key payloads for that user.
|
|
|
|
.RE
|
|
|
|
.TP
|
2016-11-03 18:46:16 +00:00
|
|
|
.IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)"
|
|
|
|
.\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b
|
2016-11-03 18:48:41 +00:00
|
|
|
The value in this file specifies the interval, in seconds,
|
|
|
|
after which revoked and expired keys will be garbage collected.
|
2016-11-03 20:26:37 +00:00
|
|
|
The purpose of having such an interval is so that there is a window
|
|
|
|
of time where user space can see an error (respectively
|
|
|
|
.BR EKEYREVOKED
|
|
|
|
and
|
|
|
|
.BR EKEYEXPIRED )
|
|
|
|
that indicates what happened to the key.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 18:46:16 +00:00
|
|
|
The default value in this file is 300 (i.e., 5 minutes).
|
|
|
|
.TP
|
|
|
|
.IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)"
|
|
|
|
.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
|
|
|
|
This file defines an interval, in seconds,
|
|
|
|
to which the persistent keyring's expiration timer is reset
|
|
|
|
each time the keyring is accessed (via
|
|
|
|
.BR keyctl_get_persistent (3)
|
|
|
|
or the
|
|
|
|
.BR keyctl (2)
|
|
|
|
.B KEYCTL_GET_PERSISTENT
|
|
|
|
operation.)
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 18:46:16 +00:00
|
|
|
The default value in this file is 259200 (i.e., 3 days).
|
2016-11-03 18:41:01 +00:00
|
|
|
.PP
|
2016-11-03 20:30:41 +00:00
|
|
|
The following files (which are writable by privileged processes)
|
2016-11-03 18:41:01 +00:00
|
|
|
are used to enforce quotas on the number of keys
|
|
|
|
and number of bytes of data that can be stored in key payloads:
|
|
|
|
.TP
|
|
|
|
.IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)"
|
|
|
|
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
|
|
|
|
.\" Previously: KEYQUOTA_MAX_BYTES 10000
|
|
|
|
This is the maximum number of bytes of data that a nonroot user
|
|
|
|
can hold in the payloads of the keys owned by the user.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 18:41:01 +00:00
|
|
|
The default value in this file is 20,000.
|
|
|
|
.TP
|
|
|
|
.IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)"
|
|
|
|
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
|
|
|
|
.\" Previously: KEYQUOTA_MAX_KEYS 100
|
|
|
|
This is the maximum number of keys that a nonroot user may own.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-03 18:41:01 +00:00
|
|
|
The default value in this file is 200.
|
|
|
|
.TP
|
|
|
|
.IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)"
|
|
|
|
This is the maximum number of bytes of data that the root user
|
|
|
|
(UID 0 in the root user namespace)
|
|
|
|
can hold in the payloads of the keys owned by root.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-25 01:01:33 +00:00
|
|
|
.\"738c5d190f6540539a04baf36ce21d46b5da04bd
|
2016-11-25 08:53:36 +00:00
|
|
|
The default value in this file is 25,000,000 (20,000 before Linux 3.17).
|
2016-11-03 18:41:01 +00:00
|
|
|
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
|
|
|
|
.TP
|
|
|
|
.IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)"
|
|
|
|
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
|
|
|
|
This is the maximum number of keys that the root user
|
|
|
|
(UID 0 in the root user namespace)
|
|
|
|
may own.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.IP
|
2016-11-25 01:01:33 +00:00
|
|
|
.\"738c5d190f6540539a04baf36ce21d46b5da04bd
|
2016-11-25 08:53:36 +00:00
|
|
|
The default value in this file is 1,000,000 (200 before Linux 3.17).
|
2016-11-03 18:41:01 +00:00
|
|
|
.PP
|
|
|
|
With respect to keyrings,
|
|
|
|
note that each link in a keyring consumes 4 bytes of the keyring payload.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 20:45:39 +00:00
|
|
|
.SS Users
|
2016-11-02 17:24:01 +00:00
|
|
|
The Linux key-management facility has a number of users and usages,
|
|
|
|
but is not limited to those that already exist.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 15:40:57 +00:00
|
|
|
In-kernel users of this facility include:
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
Network filesystems - DNS
|
2016-11-01 15:40:57 +00:00
|
|
|
The kernel uses the upcall mechanism provided by the keys to upcall to
|
2016-11-01 21:02:20 +00:00
|
|
|
user space to do DNS lookups and then to cache the results.
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
AF_RXRPC and kAFS - Authentication
|
2016-11-02 17:24:01 +00:00
|
|
|
The AF_RXRPC network protocol and the in-kernel AFS filesystem
|
|
|
|
use keys to store the ticket needed to do secured or encrypted traffic.
|
2016-11-01 17:45:14 +00:00
|
|
|
These are then looked up by
|
2016-11-01 15:40:57 +00:00
|
|
|
network operations on AF_RXRPC and filesystem operations on kAFS.
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
NFS - User ID mapping
|
2016-11-02 17:24:01 +00:00
|
|
|
The NFS filesystem uses keys to store mappings of
|
|
|
|
foreign user IDs to local user IDs.
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
CIFS - Password
|
2016-11-01 15:40:57 +00:00
|
|
|
The CIFS filesystem uses keys to store passwords for accessing remote shares.
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
Module verification
|
2016-11-01 17:45:14 +00:00
|
|
|
The kernel build process can be made to cryptographically sign modules.
|
|
|
|
That signature is then checked when a module is loaded.
|
add_key.2, bpf.2, fcntl.2, futex.2, listxattr.2, perf_event_open.2, prctl.2, request_key.2, sigaltstack.2, __ppc_set_ppr_med.3, __ppc_yield.3, getw.3, setbuf.3, setjmp.3, lirc.4, core.5, securetty.5, inode.7, keyrings.7, process-keyring.7, user-keyring.7, ld.so.8: srcfix: use .PP instead of .P
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 23:13:44 +00:00
|
|
|
.PP
|
2016-11-01 21:02:20 +00:00
|
|
|
User-space users of this facility include:
|
2016-11-03 20:30:41 +00:00
|
|
|
.TP
|
|
|
|
Kerberos key storage
|
2016-11-01 15:40:57 +00:00
|
|
|
The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication
|
2016-11-07 13:09:55 +00:00
|
|
|
tokens which can be made to be automatically cleaned up a set time after
|
|
|
|
the user last uses them,
|
2016-11-02 17:24:01 +00:00
|
|
|
but until then permits them to hang around after the user
|
2016-11-07 13:12:41 +00:00
|
|
|
has logged out so that
|
|
|
|
.BR cron (8)
|
|
|
|
scripts can use them.
|
2016-11-07 13:09:55 +00:00
|
|
|
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
2016-11-01 15:40:57 +00:00
|
|
|
.SH SEE ALSO
|
2016-11-01 17:12:21 +00:00
|
|
|
.ad l
|
|
|
|
.nh
|
2016-11-25 09:07:12 +00:00
|
|
|
.BR keyctl (1),
|
|
|
|
.BR add_key (2),
|
|
|
|
.BR keyctl (2),
|
|
|
|
.BR request_key (2),
|
|
|
|
.BR keyctl (3),
|
2016-11-01 15:40:57 +00:00
|
|
|
.BR keyutils (7),
|
2016-11-01 17:12:21 +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-11-25 09:07:12 +00:00
|
|
|
.BR pam_keyinit (8),
|
intro.1, localedef.1, memusage.1, memusagestat.1, bpf.2, execve.2, fork.2, keyctl.2, request_key.2, sigaction.2, signal.2, socket.2, dlopen.3, getauxval.3, gnu_get_libc_version.3, pthread_atfork.3, sem_post.3, setjmp.3, strftime.3, veth.4, locale.5, nscd.conf.5, resolv.conf.5, address_families.7, armscii-8.7, ascii.7, capabilities.7, cgroups.7, charsets.7, cp1251.7, cp1252.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, keyrings.7, koi8-r.7, koi8-u.7, libc.7, locale.7, man.7, network_namespaces.7, persistent-keyring.7, session-keyring.7, signal.7, unicode.7, uri.7, user-keyring.7, user-session-keyring.7: ffix: replace - with real\-
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-07-06 12:28:51 +00:00
|
|
|
.BR request\-key (8)
|
2017-09-02 04:40:14 +00:00
|
|
|
.PP
|
|
|
|
The kernel source files
|
|
|
|
.IR Documentation/crypto/asymmetric-keys.txt
|
|
|
|
and under
|
2017-09-11 03:03:50 +00:00
|
|
|
.IR Documentation/security/keys
|
|
|
|
(or, before Linux 4.13, in the file
|
|
|
|
.IR Documentation/security/keys.txt ).
|