diff options
author | David Howells <dhowells@redhat.com> | 2014-02-21 14:04:34 +0000 |
---|---|---|
committer | David Howells <dhowells@redhat.com> | 2014-02-21 14:33:26 +0000 |
commit | 779eb0dfa438ff5040a5652a7155c46083b32e43 (patch) | |
tree | 10badaa340165f84cc2a98f7c3967869811399c4 | |
parent | f4865fb0afc6656e6c4a6e43370842226bbaa636 (diff) | |
download | keyutils-779eb0dfa438ff5040a5652a7155c46083b32e43.tar.gz |
Doc: Add man7 pages for various keyrings concepts
Add manual pages to section 7 describing various keyrings concepts.
Signed-off-by: David Howells <dhowells@redhat.com>
-rw-r--r-- | Makefile | 3 | ||||
-rw-r--r-- | keyutils.spec | 1 | ||||
-rw-r--r-- | man/keyctl.1 | 4 | ||||
-rw-r--r-- | man/keyctl.3 | 18 | ||||
-rw-r--r-- | man/keyctl_chown.3 | 4 | ||||
-rw-r--r-- | man/keyctl_clear.3 | 5 | ||||
-rw-r--r-- | man/keyctl_describe.3 | 4 | ||||
-rw-r--r-- | man/keyctl_get_keyring_ID.3 | 4 | ||||
-rw-r--r-- | man/keyctl_get_persistent.3 | 10 | ||||
-rw-r--r-- | man/keyctl_get_security.3 | 4 | ||||
-rw-r--r-- | man/keyctl_instantiate.3 | 6 | ||||
-rw-r--r-- | man/keyctl_invalidate.3 | 4 | ||||
-rw-r--r-- | man/keyctl_join_session_keyring.3 | 10 | ||||
-rw-r--r-- | man/keyctl_link.3 | 5 | ||||
-rw-r--r-- | man/keyctl_read.3 | 4 | ||||
-rw-r--r-- | man/keyctl_revoke.3 | 4 | ||||
-rw-r--r-- | man/keyctl_search.3 | 4 | ||||
-rw-r--r-- | man/keyctl_session_to_parent.3 | 10 | ||||
-rw-r--r-- | man/keyctl_set_reqkey_keyring.3 | 6 | ||||
-rw-r--r-- | man/keyctl_set_timeout.3 | 4 | ||||
-rw-r--r-- | man/keyctl_setperm.3 | 4 | ||||
-rw-r--r-- | man/keyctl_update.3 | 4 | ||||
-rw-r--r-- | man/keyrings.7 | 416 | ||||
-rw-r--r-- | man/keyutils.7 | 110 | ||||
-rw-r--r-- | man/persistent-keyring.7 | 67 | ||||
-rw-r--r-- | man/process-keyring.7 | 53 | ||||
-rw-r--r-- | man/session-keyring.7 | 85 | ||||
-rw-r--r-- | man/thread-keyring.7 | 50 | ||||
-rw-r--r-- | man/user-keyring.7 | 63 | ||||
-rw-r--r-- | man/user-session-keyring.7 | 65 |
30 files changed, 1001 insertions, 30 deletions
@@ -13,6 +13,7 @@ MANDIR := /usr/share/man MAN1 := $(MANDIR)/man1 MAN3 := $(MANDIR)/man3 MAN5 := $(MANDIR)/man5 +MAN7 := $(MANDIR)/man7 MAN8 := $(MANDIR)/man8 INCLUDEDIR := /usr/include LNS := ln -sf @@ -173,6 +174,8 @@ endif $(INSTALL) -m 0644 $(wildcard man/*.3) $(DESTDIR)$(MAN3) mkdir -p $(DESTDIR)$(MAN5) $(INSTALL) -m 0644 $(wildcard man/*.5) $(DESTDIR)$(MAN5) + mkdir -p $(DESTDIR)$(MAN7) + $(INSTALL) -m 0644 $(wildcard man/*.7) $(DESTDIR)$(MAN7) mkdir -p $(DESTDIR)$(MAN8) $(INSTALL) -m 0644 $(wildcard man/*.8) $(DESTDIR)$(MAN8) $(LNS) keyctl_describe.3 $(DESTDIR)$(MAN3)/keyctl_describe_alloc.3 diff --git a/keyutils.spec b/keyutils.spec index 19c92bf..241c81f 100644 --- a/keyutils.spec +++ b/keyutils.spec @@ -97,6 +97,7 @@ rm -rf $RPM_BUILD_ROOT %files libs %defattr(-,root,root,-) %doc LICENCE.LGPL +%{_mandir}/man7/* %{_libdir}/libkeyutils.so.%{libapiversion} %{_libdir}/libkeyutils.so.%{libapivermajor} diff --git a/man/keyctl.1 b/man/keyctl.1 index 7c8df67..4d6cbe5 100644 --- a/man/keyctl.1 +++ b/man/keyctl.1 @@ -7,7 +7,7 @@ .\" as published by the Free Software Foundation; either version .\" 2 of the License, or (at your option) any later version. .\" -.TH KEYCTL 1 "10 Sep 2013" Linux "Linux Key Management Utilities" +.TH KEYCTL 1 "20 Feb 2014" Linux "Linux Key Management Utilities" .SH NAME keyctl - Key management facility control .SH SYNOPSIS @@ -61,6 +61,8 @@ keyctl - Key management facility control .br \fBkeyctl\fR setperm <key> <mask> .br +\fBkeyctl\fR new_session +.br \fBkeyctl\fR session .br \fBkeyctl\fR session - [<prog> <arg1> <arg2> ...] diff --git a/man/keyctl.3 b/man/keyctl.3 index fad6d08..440c270 100644 --- a/man/keyctl.3 +++ b/man/keyctl.3 @@ -7,7 +7,7 @@ .\" as published by the Free Software Foundation; either version .\" 2 of the Licence, or (at your option) any later version. .\" -.TH KEYCTL 3 "10 Sep 2013" Linux "Linux Key Management Calls" +.TH KEYCTL 3 "21 Feb 2014" Linux "Linux Key Management Calls" .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SH NAME keyctl_*() \- Key management function wrappers @@ -18,7 +18,7 @@ The system call is a multiplexor for a number of key management functions. These should be called via the wrappers in the libkeyutils library. .P -The functions can be compiled in by including the keyutils header file: +The functions can be compiled in by including the \fBkeyutils\fR header file: .sp .RS .nf @@ -35,6 +35,8 @@ and then telling the linker it should link in the library: .SH KEYCTL FUNCTIONS .BR keyctl_assume_authority (3) .br +.BR keyctl_chown (3) +.br .BR keyctl_clear (3) .br .BR keyctl_describe (3) @@ -45,6 +47,10 @@ and then telling the linker it should link in the library: .br .BR keyctl_get_persistent (3) .br +.BR keyctl_get_security (3) +.br +.BR keyctl_get_security_alloc (3) +.br .BR keyctl_instantiate (3) .br .BR keyctl_instantiate_iov (3) @@ -67,10 +73,6 @@ and then telling the linker it should link in the library: .br .BR keyctl_search (3) .br -.BR keyctl_security (3) -.br -.BR keyctl_security_alloc (3) -.br .BR keyctl_session_to_parent (3) .br .BR keyctl_set_reqkey_keyring (3) @@ -99,4 +101,6 @@ and then telling the linker it should link in the library: .br .BR request_key (2), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_chown.3 b/man/keyctl_chown.3 index 2492ec1..902fb65 100644 --- a/man/keyctl_chown.3 +++ b/man/keyctl_chown.3 @@ -85,4 +85,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_clear.3 b/man/keyctl_clear.3 index 87e543e..be446a3 100644 --- a/man/keyctl_clear.3 +++ b/man/keyctl_clear.3 @@ -70,4 +70,7 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) + diff --git a/man/keyctl_describe.3 b/man/keyctl_describe.3 index e125ab8..904720a 100644 --- a/man/keyctl_describe.3 +++ b/man/keyctl_describe.3 @@ -107,4 +107,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_get_keyring_ID.3 b/man/keyctl_get_keyring_ID.3 index be9660d..74d6f18 100644 --- a/man/keyctl_get_keyring_ID.3 +++ b/man/keyctl_get_keyring_ID.3 @@ -93,4 +93,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_get_persistent.3 b/man/keyctl_get_persistent.3 index 0f0c74c..59077df 100644 --- a/man/keyctl_get_persistent.3 +++ b/man/keyctl_get_persistent.3 @@ -7,10 +7,10 @@ .\" as published by the Free Software Foundation; either version .\" 2 of the License, or (at your option) any later version. .\" -.TH KEYCTL_GET_PERSISTENT 3 "21 Nov 2013" Linux "Linux Key Management Calls" +.TH KEYCTL_GET_PERSISTENT 3 "20 Feb 2014" Linux "Linux Key Management Calls" .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SH NAME -keyctl_get_persistent \- Change the ownership of a key +keyctl_get_persistent \- Get the persistent keyring for a user .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SH SYNOPSIS .nf @@ -110,4 +110,8 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR persistent-keyring (7), +.br +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_get_security.3 b/man/keyctl_get_security.3 index f9a3c84..49bda40 100644 --- a/man/keyctl_get_security.3 +++ b/man/keyctl_get_security.3 @@ -97,4 +97,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_instantiate.3 b/man/keyctl_instantiate.3 index 7da0b8c..18c371f 100644 --- a/man/keyctl_instantiate.3 +++ b/man/keyctl_instantiate.3 @@ -189,4 +189,8 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR request-key (8), +.br +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_invalidate.3 b/man/keyctl_invalidate.3 index 7afb70c..86abe48 100644 --- a/man/keyctl_invalidate.3 +++ b/man/keyctl_invalidate.3 @@ -73,4 +73,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_join_session_keyring.3 b/man/keyctl_join_session_keyring.3 index ffbb805..2071fbd 100644 --- a/man/keyctl_join_session_keyring.3 +++ b/man/keyctl_join_session_keyring.3 @@ -7,7 +7,7 @@ .\" as published by the Free Software Foundation; either version .\" 2 of the License, or (at your option) any later version. .\" -.TH KEYCTL_JOIN_SESSION_KEYRING 3 "4 May 2006" Linux "Linux Key Management Calls" +.TH KEYCTL_JOIN_SESSION_KEYRING 3 "20 Feb 2014" Linux "Linux Key Management Calls" .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SH NAME keyctl_join_session_keyring \- Join a different session keyring @@ -79,4 +79,10 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR session-keyring (7), +.br +.BR user-session-keyring (7), +.br +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_link.3 b/man/keyctl_link.3 index f62549e..c73c4ef 100644 --- a/man/keyctl_link.3 +++ b/man/keyctl_link.3 @@ -105,4 +105,7 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) + diff --git a/man/keyctl_read.3 b/man/keyctl_read.3 index 87df11b..fa9485f 100644 --- a/man/keyctl_read.3 +++ b/man/keyctl_read.3 @@ -109,4 +109,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_revoke.3 b/man/keyctl_revoke.3 index 212c776..1551849 100644 --- a/man/keyctl_revoke.3 +++ b/man/keyctl_revoke.3 @@ -70,4 +70,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_search.3 b/man/keyctl_search.3 index 368584c..fb44c25 100644 --- a/man/keyctl_search.3 +++ b/man/keyctl_search.3 @@ -135,4 +135,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_session_to_parent.3 b/man/keyctl_session_to_parent.3 index a0da527..5b15ae5 100644 --- a/man/keyctl_session_to_parent.3 +++ b/man/keyctl_session_to_parent.3 @@ -7,7 +7,7 @@ .\" as published by the Free Software Foundation; either version .\" 2 of the License, or (at your option) any later version. .\" -.TH KEYCTL_SESSION_TO_PARENT 3 "26 Jun 2010" Linux "Linux Key Management Calls" +.TH KEYCTL_SESSION_TO_PARENT 3 "20 Feb 2014" Linux "Linux Key Management Calls" .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SH NAME keyctl_session_to_parent \- Set the parent process's session keyring @@ -72,4 +72,10 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR session-keyring (7), +.br +.BR user-session-keyring (7), +.br +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_set_reqkey_keyring.3 b/man/keyctl_set_reqkey_keyring.3 index fc5946e..c5f41e9 100644 --- a/man/keyctl_set_reqkey_keyring.3 +++ b/man/keyctl_set_reqkey_keyring.3 @@ -95,4 +95,8 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR request-key (8), +.br +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_set_timeout.3 b/man/keyctl_set_timeout.3 index 6d6e774..91cc92f 100644 --- a/man/keyctl_set_timeout.3 +++ b/man/keyctl_set_timeout.3 @@ -78,4 +78,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_setperm.3 b/man/keyctl_setperm.3 index 9bf90f5..3bb9707 100644 --- a/man/keyctl_setperm.3 +++ b/man/keyctl_setperm.3 @@ -127,4 +127,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyctl_update.3 b/man/keyctl_update.3 index dd95fe9..d9575de 100644 --- a/man/keyctl_update.3 +++ b/man/keyctl_update.3 @@ -93,4 +93,6 @@ should be specified to the linker. .br .BR keyctl (3), .br -.BR request-key (8) +.BR keyutils (7), +.br +.BR keyrings (7) diff --git a/man/keyrings.7 b/man/keyrings.7 new file mode 100644 index 0000000..ed72b68 --- /dev/null +++ b/man/keyrings.7 @@ -0,0 +1,416 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH KEYRINGS 7 "21 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyrings \- In-kernel key management and retention facility +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH OVERVIEW +The +.B keyrings +facility is primarily a way for drivers to retain or cache security data, +authentication keys, encryption keys and other data in the kernel. +.P +System call interfaces are provided so that userspace programs can manage those +objects and also use the facility for their own purposes. +.P +A library and some userspace utilities are provided to allow access to the +facility. See +.BR keyutils (7) +manual page for more information. +.P +This document contains the following sections: +.P +.RS +- Keys. +.br +- Key types. +.br +- Keyrings. +.br +- Anchoring keys. +.br +- Possession. +.br +- Access rights. +.br +- Searching for keys. +.br +- On-demand key creation. +.br +- Users. +.br +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.P +.SH KEYS +The facility provides the concept of a '\fBkey\fR', where all of the above +examples are encapsulated within objects of this type. +.P +A 'key' contains the following elements: +.IP "\fBSerial number\fR" +This is a unique integer handle by which a key is referred to in system call +arguments. +.IP "\fBType\fR" +This 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. +.IP +There are a number of general purpose types available, plus some specialist +types defined by specific drivers. +.IP "\fBDescription\fR" +This is a printable string that is used as the search term for the key (in +conjunction with the type) as well as a display name. The description may be +partially matched or exactly matched. +.IP "\fBPayload\fR" +This is the actual content of a key. This is usually set when a key is +created, but it is possible for the kernel to upcall to userspace to finish the +instantiation of a key if that key wasn't already known to the kernel when it +was requested. +.IP +A key's payload can be read and updated if the key type supports it and if +suitable permission is granted to the caller. +.IP "\fBAccess rights\fR" +Each key has an owning user ID, an owning group and a security label - much as +files do. They also have a set of permissions, though there are more than for +a normal UNIX file, and there is an additional category beyond the usual user, +group and other (see below). +.IP +Note that keys are quota controlled since they represent unswappable kernel +memory and the owning user ID specifies whose quota is to be debited. +.IP "\fBExpiration time\fR" +Each key can have an expiration time set. When that time is reached, the key +is marked as being expired and accesses to it fail with \fIEKEYEXPIRED\fR. If +not deleted, updated or replaced, after a set amount of time, expired keys are +automatically removed along with all links to them and \fIENOKEY\fR will be +reported. +.IP "\fBReference count\fR" +Each key has a reference count. Keys are referenced by keyrings, by current +active users and by a process's credentials. When the reference count reaches +zero, the key is scheduled for garbage collection. +.P +See the +.BR keyctl_describe (3) +manual page for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH KEY TYPES +.P +The facility provides several basic types of key: +.IP "\fBkeyring\fR" +Keys of this type are special. The payload consists of a set of links to other +keys, 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. +.IP "\fBuser\fR" +This is a general purpose key type. It may be instantiated with an arbitrary +blob of data of up to about 32KB. It is kept entirely within kernel memory. +It may be read and updated by userspace. +.IP "\fBbig_key\fR" +This is similar to \fBuser\fR but it may hold data up to 1MB in size. The data +may be stored in the swap space rather than in kernel memory if the size +exceeds the overhead of doing so (a tmpfs file is used - which requires +filesystem structures to be allocated in the kernel). +.IP "\fBlogon\fR" +This is similar to \fBuser\fR but the contents may not be read by userspace. +.P +There are more specialised key types available also, but they're not discussed +here as they're not intended for normal userspace use. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.P +.SH KEYRINGS +As previously mentioned, keyrings are a special type of key that contain links +to other keys (which may include other keyrings). Keys may be linked to by +multiple keyrings. Keyrings may be considered as analogous to UNIX directories +where each directory contains a set of hard links to files. +.P +Several of the syscall functions available may only be applied to keyrings: +.IP "\fBAdding\fR" +A key may be added to a keyring by system calls that create keys. This +prevents the new key from being immediately deleted when the system call driver +releases its last reference to the key. +.IP "\fBLinking\fR" +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. +.IP "\fBUnlinking\fR" +A link may be removed from a keyring. When the last link to a key is removed, +that key will be scheduled for deletion by the garbage collector. +.IP "\fBClearing\fR" +All the links may be removed from a keyring. +.IP "\fBSearching\fR" +A keyring may be considered the root of a tree or subtree in which keyrings +form the branches and non-keyrings the leaves. This tree may be searched for a +leaf matching a particular type and description. +.P +See the +.BR keyctl_clear (3), +.BR keyctl_link (3), +.BR keyctl_search (3) +and +.BR keyctl_unlink (3) +manual pages for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ANCHORING KEYS +.P +To prevent a key from being prematurely garbage collected, it must anchored to +keep its reference count elevated when it is not in active use by the kernel. +.P +\fBKeyrings\fR are used to anchor other keys - each link is a reference on a +key - but whilst keyrings are available to link to keys, keyrings themselves +are just keys and are also subject to the same anchoring necessity. +.P +The kernel makes available a number of anchor keyrings. Note that some of +these keyrings will only be created when first accessed. +.IP "\fBProcess keyrings\fR" +Process credentials themselves reference keyrings with specific semantics. +These keyrings are pinned as long as the set of credentials exists - which is +usually as long as the process does. +.IP +There are three keyrings with different inheritance/sharing rules: The \fBsession +keyring\fR (inherited and shared by all child processes), the \fBprocess keyring\fR +(shared by all threads in a process) and the \fBthread keyring\fR (specific to +a particular thread). +.IP "\fBUser keyrings\fR" +Each UID known to the kernel has a record that contains two keyrings: The +\fBuser keyring\fR and the \fBuser session keyring\fR. These exist for as long +as the UID record in the kernel exists. A link to the user keyring is placed +in a new session keyring by \fBpam_keyinit\fR when a new login session is +initiated. +.IP "\fBPersistent keyrings\fR" +There is a \fBpersistent keyring\fR available to each UID known to the system. +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. This, for example, permits cron scripts to use credentials left when the +user logs out. +.IP +Note that the expiration time is reset every time the persistent key is +requested. +.IP "\fBSpecial keyrings\fR" +There are special keyrings owned by the kernel that can anchor keys for special +purposes. An example of this is the \fBsystem keyring\fR used for holding +encryption keys for module signature verification. +.IP +These are usually closed to direct alteration by userspace. +.P +See the +.BR thread-keyring (7), +.BR process-keyring (7), +.BR session-keyring (7), +.BR user-keyring (7), +.BR user-session-keyring (7), +and +.BR persistent-keyring (7) +manual pages for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH POSSESSION +.P +The concept of '\fBpossession\fR' is important to understanding the keyrings +security model. Whether a thread possesses a key is determined by the +following rules: +.IP (1) +Any key or keyring that does not grant \fBSearch\fP permission to the caller is +\fIignored\fP in all the following rules. +.IP (2) +A thread \fIpossesses\fR its \fBsession\fR, \fBprocess\fR and \fBthread\fR +keyrings directly because those are pointed to by its credentials. +.IP (3) +If a keyring is possessed, then any key it links to is \fIalso\fR possessed. +.IP (4) +If any key a keyring links to is itself a keyring, then rule (3) applies +\fIrecursively\fP. +.IP (5) +If a process is upcalled from the kernel to instantiate a key, then it also +possess's the \fIrequester's\fP keyrings as in rule (1) as if it were the +requester. +.P +Note that possession is not a fundamental property of a key, but must rather be +calculated each time it is needed. +.P +Possession is designed to allow setuid programs run from, say, a user's shell +to access the user's keys. It also allows the prevention of access to keys +just on the basis of UID and GID matches. +.P +When it creates the session keyring, the \fBpam_keyinit\fR module adds a link +to the user keyring, thus making the user keyring and anything it contains +possessed by default. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ACCESS RIGHTS +.P +Each key has the following security-related attributes: +.P +.RS +- The owning user ID +.br +- The ID of a group that is permitted to access the key +.br +- A security label +.br +- A permissions mask +.RE +.P +The permissions mask is used to govern the following rights: +.IP \fBView\fR +If set, the attributes of a key may be read. This includes the type, +description and access rights (excluding the security label). +.IP \fBRead\fR +If set, the payload of a key may be read and a list of the serial numbers to +which a keyring has links may be read. +.IP \fBWrite\fR +If set, the payload of a key may be updated, links may be added to or removed +from a keyring, a keyring may be cleared completely and a key may be revoked. +.IP \fBSearch\fR +If set, keyrings and subkeyrings may be searched and keys and keyrings may be +found by that search. +.IP \fBLink\fR +If set, an additional link may be made to a key from a keyring. The initial +link to a key when it is created doesn't require this permit. +.IP \fBSetattr\fR +If set, the ownership details on a key and its security label may be changed, +its expiration time may be set and it may be revoked. +.P +The permissions mask contains four sets of rights. The first three sets are +mutually exclusive. One and only one will be in force at any one time. In +order of descending priority: +.IP \fBUser\fR +Used if the key's user ID matches the caller's \fBfsuid\fR. +.IP \fBGroup\fR +Used if the user ID didn't match and the key's group ID matches the caller's +\fBfsgid\fR or one of the caller's supplementary group list. +.IP \fBOther\fR +Used if neither the key's user ID nor group ID matched. +.P +The fourth set of rights is: +.IP \fBPossessor\fR +Used if a key is determined to be \fBpossessed\fR by the caller. +.P +The complete set of rights for a key is the set union of whichever of the first +three sets is selected plus the fourth if the key is possessed. +.P +If any right is granted to a thread for a key, then that thread will see the +key listed in /proc/keys. If no rights at all are granted, then that thread +can't even tell that the key exists. +.P +In addition to access rights, any active \fBLinux Security Module\fP may +prevent access to a key if its policy so dictates. A key may be given a +security label or other attribute by the LSM which can be retrieved. +.P +See the +.BR keyctl_chown (3), +.BR keyctl_describe (3), +.BR keyctl_get_security (3), +.BR keyctl_setperm (3) +and +.BR selinux (8) +manual pages for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEARCHING FOR KEYS +.P +One of the key features of this facility is the ability to find a key that it +is retaining. The \fBrequest_key\fR() system call is the primary point of +access for userspace to find a key to use (the kernel has something similar +available). +.P +The search algorithm works as follows: +.IP (1) +The three process keyrings are searched in the following order: the thread +keyring if it exists, the process keyring if it exists and then either the +session keyring if it exists or the user session keyring if that exists. +.IP (2) +If the caller was a process that was invoked by the \fBrequest_key\fR() upcall +mechanism then the keyrings of the original caller of that \fBrequest_key\fR() +will be searched as well. +.IP (3) +Each keyring is searched first for a match, then the keyrings referred to by +that keyring are searched. +.IP (4) +If a matching key is found that is valid, then the search terminates and that +key is returned. +.IP (5) +If a matching key is found that has an error state attached, that error state +is noted and the search continues. +.IP (6) +If valid matching key is found, then the first noted error state is returned or +else \fBENOKEY\fR is returned. +.P +It is also possible to search a specific keyring, in which case only steps (3) +to (6) apply. +.P +See the +.BR request_key (2) +and +.BR keyctl_search (3) +manual pages for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ON-DEMAND KEY CREATION +.P +If a key cannot be found, the \fBrequest_key\fR() system call will, if given a +\fIcallout_info\fR argument, create a new key and then upcall to userspace to +instantiate the key. This allows keys to be created on an as-needed basis. +.P +Typically, this will involve the kernel forking and exec'ing \fBrequest-key\fR +program, which will then execute the appopriate handler based on its +configuration. +.P +The handler is passed a special authorisation key that allows it and only it to +instantiate the new key. This is also used to permit searches performed by the +handler program to also search the requester's keyrings. +.P +See the +.BR keyctl_assume_authority (3), +.BR keyctl_instantiate (3), +.BR keyctl_negate (3), +.BR keyctl_reject (3), +.BR request_key (2), +.BR request-key (8) +and +.BR request-key.conf (5) +manual pages for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH USERS +.P +The facility has a number of users and usages, but is not limited to those +that already exist. +.P +In-kernel users of this facility include: +.IP "\fBNetwork filesystems - DNS\fR" +The kernel uses the upcall mechanism provided by the keys to upcall to +userspace to do DNS lookups and then to cache the results. +.IP "\fBAF_RXRPC and kAFS - Authentication\fR" +The AF_RXRPC network protocol and the in-kernel AFS filesystem store the ticket +needed to do secured or encrypted traffic in keys. These are then looked up by +network operations on AF_RXRPC and filesystem operations on kAFS. +.IP "\fBNFS - User ID mapping\fR" +The NFS filesystem uses keys to store foreign user ID to local user ID mapping. +.IP "\fBCIFS - Password\fR" +The CIFS filesystem uses keys to store passwords for accessing remote shares. +.IP "\fBModule verification\fR" +The kernel build process can be made to cryptographically sign modules. That +signature is then checked when a module is loaded. +.P +Userspace users of this facility include: +.IP "\fBKerberos key storage\fR" +The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication +tokens which can be made to be automatically cleaned up a set time after the +user last uses them, but until then permits them to hang around after the user +has logged out so that cron scripts can use them. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyutils (7), +.br +.BR pam_keyinit (8), +.br +.BR thread-keyring (7), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR user-keyring (7), +.br +.BR user-session-keyring (7), +.br +.BR persistent-keyring (7) diff --git a/man/keyutils.7 b/man/keyutils.7 new file mode 100644 index 0000000..b49e21e --- /dev/null +++ b/man/keyutils.7 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH KEYRINGS 7 "21 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyutils \- In-kernel key management utilities +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +The +.B keyutils +package is a library and a set of utilities for accessing the kernel +\fBkeyrings\fP facility. +.P +A header file is supplied to provide the definitions and declarations required +to access the library: +.P +.RS +.B #include <keyutils.h> +.RE +.P +To link with the library, the following: +.P +.RS +.B -lkeyutils +.RE +.P +should be specified to the linker. +.P +Three system calls are provided: +.IP \fBadd_key\fP() +Supply a new key to the kernel. +.IP \fBrequest_key\fP() +Find an existing key for use, or, optionally, create one if one does not exist. +.IP \fBkeyctl\fP() +Control a key in various ways. The library provides a variety of wrappers +around this system call and those should be used rather than calling it +directly. +.P +See the +.BR add_key (2), +.BR request_key (2), +and +.BR keyctl (2) +manual pages for more information. +.P +The \fBkeyctl\fP() wrappers are listed on the +.BR keyctl (3) +manual page. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH UTILITIES +.P +A program is provided to interact with the kernel facility by a number of +subcommands, e.g.: +.P +.RS +.B keyctl add user foo bar @s +.RE +.P +See the +.BR keyctl (1) +manual page for information on that. +.P +The kernel has the ability to upcall to userspace to fabricate new keys. This +can be triggered by \fBrequest_key\fP(), but userspace is better off using +\fBadd_key\fP() instead if it possibly can. +.P +The upcalling mechanism is usually routed via the: +.P +.RS +.B request-key +.RE +.P +program. What this does with any particular key is configurable in: +.P +.RS +.B /etc/request-key.conf +.br +.B /etc/request-key.d/ +.RE +.P +See the +.BR request-key.conf (5) +and the +.BR request-key (8) +manual pages for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyrings (7), +.br +.BR pam_keyinit (8), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR thread-keyring (7), +.br +.BR user-keyring (7), +.br +.BR user-session-keyring (7), +.br +.BR persistent-keyring (7) + diff --git a/man/persistent-keyring.7 b/man/persistent-keyring.7 new file mode 100644 index 0000000..86dbb66 --- /dev/null +++ b/man/persistent-keyring.7 @@ -0,0 +1,67 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "PERSISTENT KEYRING" 7 "20 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +persistent keyring \- Per-user persistent keyring +.SH DESCRIPTION +The +.B persistent keyring +is a keyring used to anchor keys on behalf of a user. Each UID the kernel +deals with has its own persistent keyring that is shared between all threads +owned by that UID. +.P +The persistent keyring is created on demand when a thread requests it. The +keyring's expiration timer is reset every time it is accessed to the value in: +.IP +/proc/sys/kernel/keys/persistent_keyring_expiry +.P +The persistent keyring is not searched by \fBrequest_key\fP() unless it is +referred to by a keyring that is. +.P +The persistent keyring may not be accessed directly, even by processes with +the appropriate UID. Instead it must be linked to one of a process's keyrings +first before that keyring can access it by virtue of its possessor permits. +This is done with \fBkeyctl_get_persistent\fP(). +.P +Persistent keyrings are independent of clone(), fork(), vfork(), execve() and +exit(). They persist until their expiration timers trigger - at which point +they are garbage collected. This allows them to carry keys beyond the life of +the kernel's record of the corresponding UID (the destruction of which results +in the destruction of the user and user session keyrings). +.P +If a persistent keyring does not exist when it is accessed, it will be +created. +.SH SPECIAL OPERATIONS +The keyutils library provides a special operation for manipulating persistent +keyrings: +.IP \fBkeyctl_get_persistent\fP() +This operation allows the caller to get the persistent keyring corresponding +to their own UID or, if they have \fBCAP_SETUID\fR, the persistent keyring +corresponding to some other UID in the same user namespace. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyctl_get_persistent (3), +.br +.BR keyrings (7), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR thread-keyring (7), +.br +.BR user-keyring (7), +.br +.BR user-session-keyring (7) diff --git a/man/process-keyring.7 b/man/process-keyring.7 new file mode 100644 index 0000000..0af7a1c --- /dev/null +++ b/man/process-keyring.7 @@ -0,0 +1,53 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "PROCESS KEYRING" 7 "19 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +process keyring \- Per-process shared keyring +.SH DESCRIPTION +The +.B process keyring +is a keyring used to anchor keys on behalf of a process. It is only created +when a process requests it. +.P +A special serial number value, \fBKEY_SPEC_PROCESS_KEYRING\fP, is defined that +can be used in lieu of the calling process's process keyring's actual serial +number. +.P +From the keyctl utility, '\fB@p\fP' can be used instead of a numeric key ID in +much the same way, but as keyctl is a program run after forking, this is of no +utility. +.P +A process's process keyring is inherited across clone() with CLONE_THREAD and +is cleared by execve(). The process keyring will be destroyed when the last +thread that refers to it exits. +.P +If a process doesn't have a process keyring when it is accessed, then the +process keyring will be created if the keyring is to be modified, otherwise +error ENOKEY will be issued. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyrings (7), +.br +.BR thread-keyring (7), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR user-keyring (7), +.br +.BR user-session-keyring (7), +.br +.BR persistent-keyring (7) diff --git a/man/session-keyring.7 b/man/session-keyring.7 new file mode 100644 index 0000000..6349ddb --- /dev/null +++ b/man/session-keyring.7 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "SESSION KEYRING" 7 "19 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +session keyring \- Session shared process keyring +.SH DESCRIPTION +The +.B session keyring +is a keyring used to anchor keys on behalf of a process. It is typically +created by the \fBpam_keyinit\fP module when a user logs in and a link will be +added that refers to the \fBuser keyring\fP. +.P +A special serial number value, \fBKEY_SPEC_SESSION_KEYRING\fP, is defined that +can be used in lieu of the calling process's session keyring's actual serial +number. +.P +From the keyctl utility, '\fB@s\fP' can be used instead of a numeric key ID in +much the same way. +.P +A process's session keyring is inherited across clone(), fork() and vfork() and +is retained across execve() - even when the target executable is setuid or +setgid. The session keyring will be destroyed when the last process that +refers to it exits. +.P +If a process doesn't have a session keyring when it is accessed, then, under +certain circumstances, the \fBuser session keyring\fR will be attached as the +session keyring and under others a new session keyring will be created. +.SH SPECIAL OPERATIONS +The keyutils library provides a number of special operations for manipulating +session keyrings: +.IP \fBkeyctl_join_session_keyring\fP() +This operation allows the caller to change their session keyring. The caller +can join an existing keyring by name, create a new keyring of the name given or +ask the kernel to create a new session keyring with the name "_ses". +.IP \fBkeyctl_session_to_parent\fP() +This operation allows the caller to set the parent process's session keyring to +the same as their own. For this to succeed, the parent process must have +identical security attributes and must be single threaded. +.P +These operations are also exposed through the keyctl utility as: +.P +.RS +\fBkeyctl\fP session +.br +\fBkeyctl\fP session - [<prog> <arg1> <arg2> ...] +.br +\fBkeyctl\fP session <name> [<prog> <arg1> <arg2> ...] +.RE +.P +and: +.P +.RS +\fBkeyctl\fP new_session +.RE +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyctl_join_session_keyring (3), +.br +.BR keyctl_session_to_parent (3), +.br +.BR pam_keyinit (8), +.br +.BR keyrings (7), +.br +.BR thread-keyring (7), +.br +.BR process-keyring (7), +.br +.BR user-keyring (7), +.br +.BR user-session-keyring (7) +.br +.BR persistent-keyring (7) diff --git a/man/thread-keyring.7 b/man/thread-keyring.7 new file mode 100644 index 0000000..5f43788 --- /dev/null +++ b/man/thread-keyring.7 @@ -0,0 +1,50 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "THREAD KEYRING" 7 "20 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +thread keyring \- Per-thread keyring +.SH DESCRIPTION +The +.B thread keyring +is a keyring used to anchor keys on behalf of a process. It is only created +when a thread requests it. +.P +A special serial number value, \fBKEY_SPEC_THREAD_KEYRING\fP, is defined that +can be used in lieu of the calling thread's thread keyring's actual serial +number. +.P +From the keyctl utility, '\fB@t\fP' can be used instead of a numeric key ID in +much the same way, but as keyctl is a program run after forking, this is of no +utility. +.P +Thread keyrings are not inherited across clone() and are cleared by execve(). +A thread keyring is destroyed when the thread that refers to it exits. +.P +If a thread doesn't have a thread keyring when it is accessed, then the thread +keyring will be created if the keyring is to be modified, otherwise error +ENOKEY will be issued. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyrings (7), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR user-keyring (7), +.br +.BR user-session-keyring (7) +.br +.BR persistent-keyring (7) diff --git a/man/user-keyring.7 b/man/user-keyring.7 new file mode 100644 index 0000000..23ea333 --- /dev/null +++ b/man/user-keyring.7 @@ -0,0 +1,63 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "USER KEYRING" 7 "20 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +user keyring \- Per-user keyring +.SH DESCRIPTION +The +.B user keyring +is a keyring used to anchor keys on behalf of a user. Each UID the kernel +deals with has its own user keyring. This keyring is associated with the +record that the kernel maintains for the UID and, once created, is retained as +long as that record persists. It is shared amongst all processes of that UID. +.P +The user keyring is created on demand when a thread requests it. Normally, +this happens when \fBpam_keyinit\fP is invoked when a user logs in. +.P +The user keyring is not searched by default by \fBrequest_key\fP(). When the +pam_keyinit module creates a session keyring, it adds to it a link to the user +keyring so that the user keyring will be searched when the session keyring is. +.P +A special serial number value, \fBKEY_SPEC_USER_KEYRING\fP, is defined that +can be used in lieu of the calling process's user keyring's actual serial +number. +.P +From the keyctl utility, '\fB@u\fP' can be used instead of a numeric key ID in +much the same way. +.P +User keyrings are independent of clone(), fork(), vfork(), execve() and exit() +excepting that the keyring is destroyed when the UID record is destroyed when +the last process pinning it exits. +.P +If it necessary to for a key associated with a user to exist beyond the UID +record being garbage collected - for example for use by a cron script - then +the \fBpersistent keyring\fP should be used instead. +.P +If a user keyring does not exist when it is accessed, it will be created. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyrings (7), +.br +.BR pam_keyinit (8), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR thread-keyring (7), +.br +.BR user-session-keyring (7), +.br +.BR persistent-keyring (7) diff --git a/man/user-session-keyring.7 b/man/user-session-keyring.7 new file mode 100644 index 0000000..b8ecd21 --- /dev/null +++ b/man/user-session-keyring.7 @@ -0,0 +1,65 @@ +.\" +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "USER SESSION KEYRING" 7 "20 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +user session keyring \- Per-user default session keyring +.SH DESCRIPTION +The +.B user session keyring +is a keyring used to anchor keys on behalf of a user. Each UID the kernel +deals with has its own user session keyring. This keyring is associated with +the record that the kernel maintains for the UID and, once created, is retained +as long as that record persists. It is shared amongst all processes of that +UID. +.P +The user session keyring is created on demand when a thread requests it or when +a thread asks for its \fBsession keyring\fP and that doesn't exist. In the +latter case, a user session keyring will be created and, if the session keyring +wasn't to be created, the user session keyring will be set as the process's +actual session keyring. +.P +The user session keyring is searched by \fBrequest_key\fP() if the actual +session keyring does not exist and is ignored otherwise. +.P +A special serial number value, \fBKEY_SPEC_USER_SESSION_KEYRING\fP, is defined +that can be used in lieu of the calling process's user session keyring's actual +serial number. +.P +From the keyctl utility, '\fB@us\fP' can be used instead of a numeric key ID in +much the same way. +.P +User session keyrings are independent of clone(), fork(), vfork(), execve() and +exit() excepting that the keyring is destroyed when the UID record is destroyed +when the last process pinning it exits. +.P +If a user session keyring does not exist when it is accessed, it will be +created. +.P +It is strongly recommended that a \fBsession keyring\fP be set explicitly, for +example by \fBpam_keyinit\fP, rather than relying on the user session keyring - +particularly if a process is running as root. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyrings (7), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR thread-keyring (7), +.br +.BR user-keyring (7), +.br +.BR persistent-keyring (7) |