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>

30 files changed, 1001 insertions, 30 deletions

diff --git a/Makefile b/Makefile
index 0b2095f..c904eaf 100644
--- a/Makefile
+++ b/Makefile
@@ -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)