user-keyring.7: New page adopted from keyutils

Since this page documents kernel-user-space interfaces,
it makes sense to have it as part of man-pages, rather
than the keyutils package.

Signed-off-by: David Howells <dhowells@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man7/user-keyring.7 b/man7/user-keyring.7
new file mode 100644 (file)
index 0000000..db562a2
--- /dev/null
+++ b/man7/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)