DOC: Add get-persistent-keyring manual pages

Add manual pages for keyctl_get_persistent() and keyctl get_persistent.

Signed-off-by: David Howells <dhowells@redhat.com>

3 files changed, 137 insertions, 0 deletions

diff --git a/keyctl.1 b/keyctl.1
index b7549e9..7c8df67 100644
--- a/keyctl.1
+++ b/keyctl.1
@@ -86,6 +86,8 @@ keyctl - Key management facility control
 \fBkeyctl\fR purge [-i] [-p] <type> <desc>
 .br
 \fBkeyctl\fR purge -s <type> <desc>
+.br
+\fBkeyctl\fR get_persistent <keyring> [<uid>]
 .SH DESCRIPTION
 This program is used to control the key management facility in various ways
 using a variety of subcommands.
@@ -721,6 +723,26 @@ description using the key type's comparator in the kernel to match the
 description.  This permits the key type to match a key with a variety of
 descriptions.
 .P
+(*) \fBGet persistent keyring\fR
+.P
+\fBkeyctl\fR get_persistent <keyring> [<uid>]
+.P
+This command gets the persistent keyring for either the current UID or the
+specified UID and attaches it to the nominated keyring.  The persistent
+keyring's ID will be printed on stdout.
+.P
+The kernel will create the keyring if it doesn't exist and every time this
+command is called, will reset the expiration timeout on the keyring to the
+value in:
+.IP
+/proc/sys/kernel/keys/persistent_keyring_expiry
+.P
+(by default three days).  Should the timeout be reached, the persistent keyring
+will be removed and everything it pins can then be garbage collected.
+.P
+If a UID other than the process's real or effective UIDs is specified, then an
+error will be given if the process does not have the CAP_SETUID capability.
+.P
 .SH ERRORS
 .P
 There are a number of common errors returned by this program:
diff --git a/keyctl.3 b/keyctl.3
index 6801e77..fad6d08 100644
--- a/keyctl.3
+++ b/keyctl.3
@@ -43,6 +43,8 @@ and then telling the linker it should link in the library:
 .br
 .BR keyctl_get_keyring_ID (3)
 .br
+.BR keyctl_get_persistent (3)
+.br
 .BR keyctl_instantiate (3)
 .br
 .BR keyctl_instantiate_iov (3)
diff --git a/keyctl_get_persistent.3 b/keyctl_get_persistent.3
new file mode 100644
index 0000000..0f0c74c
--- /dev/null
+++ b/keyctl_get_persistent.3
@@ -0,0 +1,113 @@
+.\"
+.\" Copyright (C) 2013 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 License
+.\" 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"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH NAME
+keyctl_get_persistent \- Change the ownership of a key
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SYNOPSIS
+.nf
+.B #include <keyutils.h>
+.sp
+.BI "long keyctl_get_persistent(uid_t " uid ", key_serial_t " keyring ");"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH DESCRIPTION
+.BR keyctl_get_persistent ()
+gets the persistent keyring for the specified user ID.  Unlike the session and
+user keyrings, this keyring will persist once all login sessions have been
+deleted and can thus be used to carry authentication tokens for processes that
+run without user interaction, such as programs started by cron.
+.P
+The persistent keyring will be created by the kernel if it does not yet exist.
+Each time this function is called, the persistent keyring will have its
+expiration timeout reset to the value in:
+.IP
+/proc/sys/kernel/keys/persistent_keyring_expiry
+.P
+(by default three days).  Should the timeout be reached, the persistent keyring
+will be removed and everything it pins can then be garbage collected.
+.P
+If
+.I uid
+is
+.B -1
+then the calling process's real user ID will be used.  If
+.I uid
+is not
+.B -1
+then error
+.I EPERM
+will be given if the user ID requested does not match either the caller's real
+or effective user IDs or if the calling process does not have
+.B SetUid
+capability.
+.P
+If successful, a link to the persistent keyring will be added into
+.IR keyring .
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH RETURN VALUE
+On success
+.BR keyctl_get_persistent ()
+returns the serial number of the persistent keyring.  On error, the value
+.B -1
+will be returned and errno will have been set to an appropriate error.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH ERRORS
+.TP
+.B EPERM
+Not permitted to access the persistent keyring for the requested
+.IR uid .
+.TP
+.B ENOMEM
+Insufficient memory to create the persistent keyring or to extend
+.IR keyring .
+.TP
+.B ENOKEY
+.I keyring
+does not exist.
+.TP
+.B EKEYEXPIRED
+.I keyring
+has expired.
+.TP
+.B EKEYREVOKED
+.I keyring
+has been revoked.
+.TP
+.B EDQUOT
+The user does not have sufficient quota to extend
+.IR keyring .
+.TP
+.B EACCES
+.I keyring
+exists, but does not grant
+.B write
+permission to the calling process.
+
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH LINKING
+This is a library function that can be found in
+.IR libkeyutils .
+When linking,
+.B -lkeyutils
+should be specified to the linker.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SEE ALSO
+.BR keyctl (1),
+.br
+.BR add_key (2),
+.br
+.BR keyctl (2),
+.br
+.BR request_key (2),
+.br
+.BR keyctl (3),
+.br
+.BR request-key (8)