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

Signed-off-by: Mat Martineau <>
Signed-off-by: David Howells <>
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 @@
 \fBkeyctl\fR search <keyring> <type> <desc> [<dest_keyring>]
+\fBkeyctl\fR restrict_keyring <keyring> [<type> [<restriction>]]
 \fBkeyctl\fR read <key>
 \fBkeyctl\fR pipe <key>
@@ -344,6 +346,20 @@
 keyctl_search: Requested key not available
+.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.
+$ keyctl restrict_keyring $1 asymmetric builtin_trusted
 .SS Read a key
 \fBkeyctl read\fR <key>
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 @@
 .BR keyctl_reject (3)
+.BR keyctl_restrict_keyring (3)
 .BR keyctl_revoke (3)
 .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"
+keyctl_restrict_keyring \- restrict keys that may be linked to a keyring
+.B #include <keyutils.h>
+.BI "long keyctl_restrict_keyring(key_serial_t " keyring ,
+.BI "const char *" type ", const char *" restriction ");"
+.BR keyctl_restrict_keyring ()
+limits the linkage of keys to the given
+.I keyring
+using a provided key
+.I type
+.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
+the keyring will reject all links.
+On success
+.BR keyctl_restrict_keyring ()
+.BR 0 .
+On error, the value
+.B -1
+will be returned and
+.I errno
+will have been set to an appropriate error.
+A restriction cycle was avoided. Two keyrings cannot restrict each other.
+The keyring is already restricted.
+The restriction string is invalid or too large.
+The key type in the restriction is invalid or not available.
+The provided key id references an item that is not a keyring.
+The key type exists but does not support restrictions.
+This is a library function that can be found in
+.IR libkeyutils .
+When linking,
+.B \-lkeyutils
+should be specified to the linker.
+.BR keyctl (1),
+.BR keyctl (2),
+.BR keyctl (3),
+.BR keyutils (7)