path: root/Documentation/security/keys.txt
diff options
authorMat Martineau <mathew.j.martineau@linux.intel.com>2017-03-01 16:44:09 -0800
committerMat Martineau <mathew.j.martineau@linux.intel.com>2017-04-04 14:10:12 -0700
commit6563c91fd645556c7801748f15bc727c77fcd311 (patch)
tree714a6be7606cb6646c7b182bae136ef26bc9692e /Documentation/security/keys.txt
parentKEYS: Consistent ordering for __key_link_begin and restrict check (diff)
Keyrings recently gained restrict_link capabilities that allow individual keys to be validated prior to linking. This functionality was only available using internal kernel APIs. With the KEYCTL_RESTRICT_KEYRING command existing keyrings can be configured to check the content of keys before they are linked, and then allow or disallow linkage of that key to the keyring. To restrict a keyring, call: keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring, const char *type, const char *restriction) where 'type' is the name of a registered key type and 'restriction' is a string describing how key linkage is to be restricted. The restriction option syntax is specific to each key type. Signed-off-by: Mat Martineau <mathew.j.martineau@linux.intel.com>
Diffstat (limited to 'Documentation/security/keys.txt')
1 files changed, 25 insertions, 0 deletions
diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt
index 5fe04a7cc03d..5f554aab8751 100644
--- a/Documentation/security/keys.txt
+++ b/Documentation/security/keys.txt
@@ -857,6 +857,31 @@ The keyctl syscall functions are:
supported, error ENOKEY if the key could not be found, or error
EACCES if the key is not readable by the caller.
+ (*) Restrict keyring linkage
+ long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring,
+ const char *type, const char *restriction);
+ An existing keyring can restrict linkage of additional keys by evaluating
+ the contents of the key according to a restriction scheme.
+ "keyring" is the key ID for an existing keyring to apply a restriction
+ to. It may be empty or may already have keys linked. Existing linked keys
+ will remain in the keyring even if the new restriction would reject them.
+ "type" is a registered key type.
+ "restriction" is a string describing how key linkage is to be restricted.
+ The format varies depending on the key type, and the string is passed to
+ the lookup_restriction() function for the requested type. It may specify
+ a method and relevant data for the restriction such as signature
+ verification or constraints on key payload. If the requested key type is
+ later unregistered, no keys may be added to the keyring after the key type
+ is removed.
+ To apply a keyring restriction the process must have Set Attribute
+ permission and the keyring must not be previously restricted.