summaryrefslogtreecommitdiff
path: root/Documentation/security/keys/core.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/security/keys/core.rst')
-rw-r--r--Documentation/security/keys/core.rst128
1 files changed, 100 insertions, 28 deletions
diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
index 0e74f372e58c..1b3c907980ad 100644
--- a/Documentation/security/keys/core.rst
+++ b/Documentation/security/keys/core.rst
@@ -57,9 +57,9 @@ Each key has a number of attributes:
type provides an operation to perform a match between the description on a
key and a criterion string.
- * Each key has an owner user ID, a group ID and a permissions mask. These
- are used to control what a process may do to a key from userspace, and
- whether a kernel service will be able to find the key.
+ * Each key has an owner user ID, a group ID and an ACL. These are used to
+ control what a process may do to a key from userspace, and whether a
+ kernel service will be able to find the key.
* Each key can be set to expire at a specific time by the key type's
instantiation function. Keys can also be immortal.
@@ -198,43 +198,110 @@ The key service provides a number of features besides keys:
Key Access Permissions
======================
-Keys have an owner user ID, a group access ID, and a permissions mask. The mask
-has up to eight bits each for possessor, user, group and other access. Only
-six of each set of eight bits are defined. These permissions granted are:
+Keys have an owner user ID, a group ID and an ACL. The ACL is made up of a
+sequence of ACEs that each contain three elements:
- * View
+ * The type of subject.
+ * The subject.
- This permits a key or keyring's attributes to be viewed - including key
- type and description.
+ These two together indicate the subject to whom the permits are granted.
+ The type can be one of:
- * Read
+ * ``KEY_ACE_SUBJ_STANDARD``
- This permits a key's payload to be viewed or a keyring's list of linked
- keys.
+ The subject is a standard 'macro' type. The subject can be one of:
+
+ * ``KEY_ACE_EVERYONE``
+
+ The permits are granted to everyone. It replaces the old 'other'
+ type on the assumption that you wouldn't grant a permission to other
+ that you you wouldn't grant to everyone else.
+
+ * ``KEY_ACE_OWNER``
+
+ The permits are granted to the owner of the key (key->uid).
+
+ * ``KEY_ACE_GROUP``
+
+ The permits are granted to the key's group (key->gid).
+
+ * ``KEY_ACE_POSSESSOR``
+
+ The permits are granted to anyone who possesses the key.
+
+ * The set of permits granted to the subject. These include:
+
+ * ``KEY_ACE_VIEW``
+
+ This permits a key or keyring's attributes to be viewed - including the
+ key type and description.
+
+ * ``KEY_ACE_READ``
+
+ This permits a key's payload to be viewed or a keyring's list of linked
+ keys.
- * Write
+ * ``KEY_ACE_WRITE``
- This permits a key's payload to be instantiated or updated, or it allows a
- link to be added to or removed from a keyring.
+ This permits a key's payload to be instantiated or updated, or it allows
+ a link to be added to or removed from a keyring.
- * Search
+ * ``KEY_ACE_SEARCH``
- This permits keyrings to be searched and keys to be found. Searches can
- only recurse into nested keyrings that have search permission set.
+ This permits keyrings to be searched and keys to be found. Searches can
+ only recurse into nested keyrings that have search permission set.
- * Link
+ * ``KEY_ACE_LINK``
- This permits a key or keyring to be linked to. To create a link from a
- keyring to a key, a process must have Write permission on the keyring and
- Link permission on the key.
+ This permits a key or keyring to be linked to. To create a link from a
+ keyring to a key, a process must have Write permission on the keyring
+ and Link permission on the key.
- * Set Attribute
+ * ``KEY_ACE_SET_SECURITY``
- This permits a key's UID, GID and permissions mask to be changed.
+ This permits a key's UID, GID and permissions mask to be changed.
+
+ * ``KEY_ACE_INVAL``
+
+ This permits a key to be invalidated with KEYCTL_INVALIDATE.
+
+ * ``KEY_ACE_REVOKE``
+
+ This permits a key to be revoked with KEYCTL_REVOKE.
+
+ * ``KEY_ACE_JOIN``
+
+ This permits a keyring to be joined as a session by
+ KEYCTL_JOIN_SESSION_KEYRING or KEYCTL_SESSION_TO_PARENT.
+
+ * ``KEY_ACE_CLEAR``
+
+ This permits a keyring to be cleared.
For changing the ownership, group ID or permissions mask, being the owner of
the key or having the sysadmin capability is sufficient.
+The legacy KEYCTL_SETPERM and KEYCTL_DESCRIBE functions can only see/generate
+View, Read, Write, Search, Link and SetAttr permits, and do this for each of
+possessor, user, group and other permission sets as a 32-bit flag mask. These
+will be approximated/inferred:
+
+ SETPERM Permit Implied ACE Permit
+ =============== =======================
+ Search Inval, Join
+ Write Revoke, Clear
+ Setattr Set Security, Revoke
+
+ ACE Permit Described as
+ =============== =======================
+ Inval Search
+ Join Search
+ Revoke Write (unless Setattr)
+ Clear write
+ Set Security Setattr
+
+'Other' will be approximated as/inferred from the 'Everyone' subject.
+
SELinux Support
===============
@@ -1084,7 +1151,8 @@ payload contents" for more information.
struct key *request_key(const struct key_type *type,
const char *description,
- const char *callout_info);
+ const char *callout_info,
+ struct key_acl *acl);
This is used to request a key or keyring with a description that matches
the description specified according to the key type's match_preparse()
@@ -1099,6 +1167,8 @@ payload contents" for more information.
If successful, the key will have been attached to the default keyring for
implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.
+ If a key is created, it will be given the specified ACL.
+
See also Documentation/security/keys/request-key.rst.
@@ -1107,7 +1177,8 @@ payload contents" for more information.
struct key *request_key_tag(const struct key_type *type,
const char *description,
struct key_tag *domain_tag,
- const char *callout_info);
+ const char *callout_info,
+ struct key_acl *acl);
This is identical to request_key(), except that a domain tag may be
specifies that causes search algorithm to only match keys matching that
@@ -1122,7 +1193,8 @@ payload contents" for more information.
struct key_tag *domain_tag,
const void *callout_info,
size_t callout_len,
- void *aux);
+ void *aux,
+ struct key_acl *acl);
This is identical to request_key_tag(), except that the auxiliary data is
passed to the key_type->request_key() op if it exists, and the
@@ -1195,7 +1267,7 @@ payload contents" for more information.
struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
const struct cred *cred,
- key_perm_t perm,
+ struct key_acl *acl,
struct key_restriction *restrict_link,
unsigned long flags,
struct key *dest);