Doc: Update man pages for KEYCTL_RESTRICT_KEYRING

Created a new manual page for the new keyctl_restrict_keyring function and
added 'keyctl restrict_keyring' information for the keyctl command line
utility.

Signed-off-by: Mat Martineau <mathew.j.martineau@linux.intel.com>
Signed-off-by: David Howells <dhowells@redhat.com>

3 files changed, 100 insertions, 0 deletions

diff --git a/man/keyctl.1 b/man/keyctl.1
index 7060506..6e3da4d 100644
--- a/man/keyctl.1
+++ b/man/keyctl.1
@@ -41,6 +41,8 @@ keyctl \- key management facility control
 .br
 \fBkeyctl\fR search <keyring> <type> <desc> [<dest_keyring>]
 .br
+\fBkeyctl\fR restrict_keyring <keyring> [<type> [<restriction>]]
+.br
 \fBkeyctl\fR read <key>
 .br
 \fBkeyctl\fR pipe <key>
@@ -344,6 +346,20 @@ $ keyctl search @us user debug:bye
 keyctl_search: Requested key not available
 .fi
 .RE
+.SS Restrict a keyring
+\fBkeyctl restrict_keyring\fR <keyring> [<type> [<restriction>]]
+
+This command limits the linkage of keys to the given keyring using a provided
+restriction scheme. The scheme is associated with a given key type, with
+further details provided in the restriction option string.  Options typically
+contain a restriction name possibly followed by key ids or other data relevant
+to the restriction. If no restriction scheme is provided, the keyring will
+reject all links.
+
+.RS
+.nf
+$ keyctl restrict_keyring $1 asymmetric builtin_trusted
+.RE
 .SS Read a key
 \fBkeyctl read\fR <key>
 .br
diff --git a/man/keyctl.3 b/man/keyctl.3
index 81929c2..5360f5b 100644
--- a/man/keyctl.3
+++ b/man/keyctl.3
@@ -73,6 +73,8 @@ and then telling the linker it should link in the library:
 .br
 .BR keyctl_reject (3)
 .br
+.BR keyctl_restrict_keyring (3)
+.br
 .BR keyctl_revoke (3)
 .br
 .BR keyctl_search (3)
diff --git a/man/keyctl_restrict_keyring.3 b/man/keyctl_restrict_keyring.3
new file mode 100644
index 0000000..468d5b4
--- /dev/null
+++ b/man/keyctl_restrict_keyring.3
@@ -0,0 +1,82 @@
+.\"
+.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
+.\" Copyright (C) 2017 Intel Corporation. All rights reserved.
+.\"
+.\" 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_RESTRICT_KEYRING 3 "28 Feb 2017" Linux "Linux Key Management Calls"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH NAME
+keyctl_restrict_keyring \- restrict keys that may be linked to a keyring
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SYNOPSIS
+.nf
+.B #include <keyutils.h>
+.sp
+.BI "long keyctl_restrict_keyring(key_serial_t " keyring ,
+.BI "const char *" type ", const char *" restriction ");"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH DESCRIPTION
+.BR keyctl_restrict_keyring ()
+limits the linkage of keys to the given
+.I keyring
+using a provided key
+.I type
+and
+.I restriction
+scheme. The available options vary depending on the key type, and
+typically contain a restriction name possibly followed by key ids or
+other data relevant to the restriction. If the type and restriction are
+both
+.B NULL,
+the keyring will reject all links.
+.P
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH RETURN VALUE
+On success
+.BR keyctl_restrict_keyring ()
+returns
+.BR 0 .
+On error, the value
+.B -1
+will be returned and
+.I errno
+will have been set to an appropriate error.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH ERRORS
+.TP
+.B EDEADLK
+A restriction cycle was avoided. Two keyrings cannot restrict each other.
+.TP
+.B EEXIST
+The keyring is already restricted.
+.TP
+.B EINVAL
+The restriction string is invalid or too large.
+.TP
+.B ENOKEY
+The key type in the restriction is invalid or not available.
+.TP
+.B ENOTDIR
+The provided key id references an item that is not a keyring.
+.TP
+.B ENOENT
+The key type exists but does not support restrictions.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.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
+.ad l
+.nh
+.BR keyctl (1),
+.BR keyctl (2),
+.BR keyctl (3),
+.BR keyutils (7)