keys: ACLs
Subsystems (21)
David Howells
maintainercover keys: ACLs
Here are some patches to change the permissions model used by keys and keyrings to be based on an ACL:
(1) Replace the permissions mask internally with an ACL that contains a list of ACEs, each with a specific subject with a permissions mask. Potted default ACLs are available for new keys and keyrings.
ACE subjects can be macroised to indicate the UID and GID specified on the key (which remain). Future commits will be able to add additional subject types, such as specific UIDs or domain tags/namespaces.
Also split a number of permissions to give finer control. Examples include splitting the revocation permit from the change-attributes permit, thereby allowing someone to be granted permission to revoke a key without allowing them to change the owner; also the ability to join a keyring is split from the ability to link to it, thereby stopping a process accessing a keyring by joining it and thus acquiring use of possessor permits.
(2) Provide a keyctl to allow the granting or denial of one or more permits to a specific subject. Direct access to the ACL is not granted, and the ACL cannot be viewed.
The patches can be found on the following branch:
https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/log/?h=keys-acl
David
---
David Howells (2):
KEYS: Replace uid/gid/perm permissions checking with an ACL
KEYS: Provide KEYCTL_GRANT_PERMISSION
certs/blacklist.c | 7 certs/system_keyring.c | 12 - drivers/md/dm-crypt.c | 2 drivers/nvdimm/security.c | 2 fs/afs/security.c | 2 fs/cifs/cifs_spnego.c | 25 + fs/cifs/cifsacl.c | 28 +- fs/cifs/connect.c | 4 fs/crypto/keyinfo.c | 2 fs/ecryptfs/ecryptfs_kernel.h | 2 fs/ecryptfs/keystore.c | 2 fs/fscache/object-list.c | 2 fs/nfs/nfs4idmap.c | 30 +- fs/ubifs/auth.c | 2 include/linux/key.h | 121 ++++--- include/uapi/linux/keyctl.h | 64 ++++ lib/digsig.c | 2 net/ceph/ceph_common.c | 2 net/dns_resolver/dns_key.c | 12 + net/dns_resolver/dns_query.c | 15 + net/rxrpc/key.c | 16 + security/integrity/digsig.c | 31 +- security/integrity/digsig_asymmetric.c | 2 security/integrity/evm/evm_crypto.c | 2 security/integrity/ima/ima_mok.c | 13 + security/integrity/integrity.h | 4 .../integrity/platform_certs/platform_keyring.c | 13 + security/keys/compat.c | 2 security/keys/encrypted-keys/encrypted.c | 2 security/keys/encrypted-keys/masterkey_trusted.c | 2 security/keys/gc.c | 2 security/keys/internal.h | 16 + security/keys/key.c | 29 +- security/keys/keyctl.c | 97 ++++- security/keys/keyring.c | 27 +- security/keys/permission.c | 356 ++++++++++++++++++-- security/keys/persistent.c | 27 +- security/keys/proc.c | 20 + security/keys/process_keys.c | 86 ++++- security/keys/request_key.c | 34 +- security/keys/request_key_auth.c | 15 + security/selinux/hooks.c | 16 + security/smack/smack_lsm.c | 3 43 files changed, 868 insertions(+), 285 deletions(-)
David Howells
maintainerPATCH 1/2 KEYS: Replace uid/gid/perm permissions checking with an ACL
Replace the uid/gid/perm permissions checking on a key with an ACL to allow the SETATTR and SEARCH permissions to be split. This will also allow a greater range of subjects to represented.
======
WHY DO THIS?
======
The problem is that SETATTR and SEARCH cover a slew of actions, not all of which should be grouped together.
For SETATTR, this includes actions that are about controlling access to a key:
(1) Changing a key's ownership.
(2) Changing a key's security information.
(3) Setting a keyring's restriction.
And actions that are about managing a key's lifetime:
(4) Setting an expiry time.
(5) Revoking a key.
and (proposed) managing a key as part of a cache:
(6) Invalidating a key.
Managing a key's lifetime doesn't really have anything to do with controlling access to that key.
Expiry time is awkward since it's more about the lifetime of the content and so, in some ways goes better with WRITE permission. It can, however, be set unconditionally by a process with an appropriate authorisation token for instantiating a key, and can also be set by the key type driver when a key is instantiated, so lumping it with the access-controlling actions is probably okay.
As for SEARCH permission, that currently covers:
(1) Finding keys in a keyring tree during a search.
(2) Permitting keyrings to be joined.
(3) Invalidation.
But these don't really belong together either, since these actions really need to be controlled separately.
Finally, there are number of special cases to do with granting the administrator special rights to invalidate or clear keys that I would like to handle with the ACL rather than key flags and special checks.
=======WHAT IS CHANGED
=======
The SETATTR permission is split to create two new permissions:
(1) SET_SECURITY - which allows the key's owner, group and ACL to be changed and a restriction to be placed on a keyring.
(2) REVOKE - which allows a key to be revoked.
The SEARCH permission is split to create:
(1) SEARCH - which allows a keyring to be search and a key to be found.
(2) JOIN - which allows a keyring to be joined as a session keyring.
(3) INVAL - which allows a key to be invalidated.
The WRITE permission is also split to create:
(1) WRITE - which allows a key's content to be altered and links to be added, removed and replaced in a keyring.
(2) CLEAR - which allows a keyring to be cleared completely. This is split out to make it possible to give just this to an administrator.
(3) REVOKE - see above.
Keys acquire ACLs which consist of a series of ACEs, and all that apply are unioned together. An ACE specifies a subject, such as:
(*) Possessor - permitted to anyone who 'possesses' a key (*) Owner - permitted to the key owner
(*) Group - permitted to the key group
(*) Everyone - permitted to everyone
Note that 'Other' has been replaced with 'Everyone' on the assumption that you wouldn't grant a permit to 'Other' that you wouldn't also grant to everyone else.
Further subjects may be made available by later patches.
The ACE also specifies a permissions mask. The set of permissions is now:
VIEW Can view the key metadata
READ Can read the key content
WRITE Can update/modify the key content
SEARCH Can find the key by searching/requesting
LINK Can make a link to the key
SET_SECURITY Can change owner, ACL, expiry
INVAL Can invalidate
REVOKE Can revoke
JOIN Can join this keyring
CLEAR Can clear this keyring
The KEYCTL_SETPERM function is then deprecated.
The KEYCTL_SET_TIMEOUT function then is permitted if SET_SECURITY is set, or if the caller has a valid instantiation auth token.
The KEYCTL_INVALIDATE function then requires INVAL.
The KEYCTL_REVOKE function then requires REVOKE.
The KEYCTL_JOIN_SESSION_KEYRING function then requires JOIN to join an existing keyring.
The JOIN permission is enabled by default for session keyrings and manually created keyrings only.
===========
BACKWARD COMPATIBILITY
===========
To maintain backward compatibility, KEYCTL_SETPERM will translate the permissions mask it is given into a new ACL for a key - unless KEYCTL_SET_ACL has been called on that key, in which case an error will be returned.
It will convert possessor, owner, group and other permissions into separate ACEs, if each portion of the mask is non-zero.
SETATTR permission turns on all of INVAL, REVOKE and SET_SECURITY. WRITE permission turns on WRITE, REVOKE and, if a keyring, CLEAR. JOIN is turned on if a keyring is being altered.
The KEYCTL_DESCRIBE function translates the ACL back into a permissions mask to return depending on possessor, owner, group and everyone ACEs.
It will make the following mappings:
(1) INVAL, JOIN -> SEARCH
(2) SET_SECURITY -> SETATTR
(3) REVOKE -> WRITE if SETATTR isn't already set
(4) CLEAR -> WRITE
Note that the value subsequently returned by KEYCTL_DESCRIBE may not match the value set with KEYCTL_SETATTR.
===TESTING
===
This passes the keyutils testsuite for all but a couple of tests:
(1) tests/keyctl/dh_compute/badargs: The first wrong-key-type test now returns EOPNOTSUPP rather than ENOKEY as READ permission isn't removed if the type doesn't have ->read(). You still can't actually read the key.
(2) tests/keyctl/permitting/valid: The view-other-permissions test doesn't work as Other has been replaced with Everyone in the ACL.
---
certs/blacklist.c | 7 - certs/system_keyring.c | 12 - drivers/md/dm-crypt.c | 2 drivers/nvdimm/security.c | 2 fs/afs/security.c | 2 fs/cifs/cifs_spnego.c | 25 ++ fs/cifs/cifsacl.c | 28 ++ fs/cifs/connect.c | 4 fs/crypto/keyinfo.c | 2 fs/ecryptfs/ecryptfs_kernel.h | 2 fs/ecryptfs/keystore.c | 2 fs/fscache/object-list.c | 2 fs/nfs/nfs4idmap.c | 30 ++- fs/ubifs/auth.c | 2 include/linux/key.h | 121 ++++++---- include/uapi/linux/keyctl.h | 63 +++++ lib/digsig.c | 2 net/ceph/ceph_common.c | 2 net/dns_resolver/dns_key.c | 12 + net/dns_resolver/dns_query.c | 15 + net/rxrpc/key.c | 16 + security/integrity/digsig.c | 31 +-- security/integrity/digsig_asymmetric.c | 2 security/integrity/evm/evm_crypto.c | 2 security/integrity/ima/ima_mok.c | 13 + security/integrity/integrity.h | 4 .../integrity/platform_certs/platform_keyring.c | 13 + security/keys/encrypted-keys/encrypted.c | 2 security/keys/encrypted-keys/masterkey_trusted.c | 2 security/keys/gc.c | 2 security/keys/internal.h | 11 + security/keys/key.c | 29 +- security/keys/keyctl.c | 92 +++++--- security/keys/keyring.c | 27 ++ security/keys/permission.c | 237 +++++++++++++++++--- security/keys/persistent.c | 27 ++ security/keys/proc.c | 20 +- security/keys/process_keys.c | 86 +++++-- security/keys/request_key.c | 34 +-- security/keys/request_key_auth.c | 15 + security/selinux/hooks.c | 16 + security/smack/smack_lsm.c | 3 42 files changed, 736 insertions(+), 285 deletions(-)
certs/blacklist.c +2 -5
@@ -93,8 +93,7 @@ int mark_hash_blacklisted(const char *hash) hash,NULL ,0 , - ((KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW ), + &internal_key_acl,KEY_ALLOC_NOT_IN_QUOTA | KEY_ALLOC_BUILT_IN);if (IS_ERR (key)) {
@@ -153,9 +152,7 @@ static int __init blacklist_init(void)keyring_alloc (".blacklist" ,KUIDT_INIT (0 ),KGIDT_INIT (0 ),current_cred (), - (KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ | -KEY_USR_SEARCH , + &internal_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA |KEY_FLAG_KEEP ,NULL ,NULL );
certs/system_keyring.c +3 -9
@@ -103,9 +103,7 @@ static __init int system_trusted_keyring_init(void) builtin_trusted_keys keyring_alloc(".builtin_trusted_keys",KUIDT_INIT (0 ),KGIDT_INIT (0 ),current_cred (), - ((KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ |KEY_USR_SEARCH ), -KEY_ALLOC_NOT_IN_QUOTA , + &internal_key_acl,KEY_ALLOC_NOT_IN_QUOTA , NULL, NULL);if (IS_ERR (builtin_trusted_keys))panic ("Can't allocate builtin trusted keyring\n" );
@@ -114,10 +112,7 @@ static __init int system_trusted_keyring_init(void) secondary_trusted_keys keyring_alloc(".secondary_trusted_keys",KUIDT_INIT (0 ),KGIDT_INIT (0 ),current_cred (), - ((KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ |KEY_USR_SEARCH | -KEY_USR_WRITE ), -KEY_ALLOC_NOT_IN_QUOTA , + &internal_writable_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA ,get_builtin_and_secondary_restriction (), NULL);if (IS_ERR (secondary_trusted_keys))
@@ -167,8 +162,7 @@ static __init int load_system_certificate_list(void)NULL , p, plen, - ((KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ ), + &internal_key_acl,KEY_ALLOC_NOT_IN_QUOTA |KEY_ALLOC_BUILT_IN | KEY_ALLOC_BYPASS_RESTRICTION);
drivers/md/dm-crypt.c +1 -1
@@ -2035,7 +2035,7 @@ static int crypt_set_keyring_key(struct crypt_config *cc, const char *key_stringreturn -ENOMEM ; key =request_key (key_string[0 ] ='l' ? &key_type_logon : &key_type_user, - key_desc +1 ,NULL ); + key_desc +1 ,NULL ,NULL );if (IS_ERR (key)) {kzfree (new_key_string);return PTR_ERR (key);
drivers/nvdimm/security.c +1 -1
@@ -55,7 +55,7 @@ static struct key *nvdimm_request_key(struct nvdimm *nvdimm)struct device *dev = &nvdimm->dev;sprintf (desc,"%s%s" ,NVDIMM_PREFIX , nvdimm->dimm_id); - key =request_key (&key_type_encrypted, desc,"" ); + key =request_key (&key_type_encrypted, desc,"" ,NULL );if (IS_ERR (key)) {if (PTR_ERR (key) = -ENOKEY )dev_dbg (dev,"request_key() found no key\n" );
fs/afs/security.c +1 -1
@@ -32,7 +32,7 @@ struct key *afs_request_key(struct afs_cell *cell)_debug ("key %s" , cell->anonymous_key->description); key =request_key (&key_type_rxrpc, cell->anonymous_key->description, -NULL ); +NULL ,NULL );if (IS_ERR (key)) {if (PTR_ERR (key) != -ENOKEY ) {_leave (" = %ld" ,PTR_ERR (key));
fs/cifs/cifs_spnego.c +22 -3
@@ -32,6 +32,25 @@#include "cifsproto.h" static const struct cred *spnego_cred; +static struct key_acl cifs_spnego_key_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .possessor_viewable = true, + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_VIEW |KEY_ACE_SEARCH |KEY_ACE_READ ), +KEY_OWNER_ACE (KEY_ACE_VIEW ), + } +}; + +static struct key_acl cifs_spnego_keyring_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_SEARCH |KEY_ACE_WRITE ), +KEY_OWNER_ACE (KEY_ACE_VIEW |KEY_ACE_READ |KEY_ACE_CLEAR ), + } +}; +/* create a new cifs key */ static int cifs_spnego_key_instantiate (struct key *key,struct key_preparsed_payload *prep)
@@ -170,7 +189,8 @@ cifs_get_spnego_key(struct cifs_ses *sesInfo)cifs_dbg (FYI ,"key description = %s\n" , description); saved_cred =override_creds (spnego_cred); - spnego_key =request_key (&cifs_spnego_key_type, description,"" ); + spnego_key =request_key (&cifs_spnego_key_type, description,"" , + &cifs_spnego_key_acl);revert_creds (saved_cred);#ifdef CONFIG_CIFS_DEBUG2
@@ -207,8 +227,7 @@ init_cifs_spnego(void) keyring =keyring_alloc (".cifs_spnego" ,GLOBAL_ROOT_UID ,GLOBAL_ROOT_GID , cred, - (KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ , + &cifs_spnego_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA ,NULL ,NULL );if (IS_ERR (keyring)) { ret =PTR_ERR (keyring);
fs/cifs/cifsacl.c +24 -4
@@ -33,6 +33,25 @@#include "cifsproto.h" #include "cifs_debug.h" +static struct key_acl cifs_idmap_key_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .possessor_viewable = true, + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_VIEW |KEY_ACE_SEARCH |KEY_ACE_READ ), +KEY_OWNER_ACE (KEY_ACE_VIEW ), + } +}; + +static struct key_acl cifs_idmap_keyring_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_SEARCH |KEY_ACE_WRITE ), +KEY_OWNER_ACE (KEY_ACE_VIEW |KEY_ACE_READ ), + } +}; +/* security id for everyone/world system group */ static const struct cifs_sid sid_everyone = {1 ,1 , {0 ,0 ,0 ,0 ,0 ,1 }, {0 } };
@@ -298,7 +317,8 @@ id_to_sid(unsigned int cid, uint sidtype, struct cifs_sid *ssid) rc =0 ; saved_cred =override_creds (root_cred); - sidkey =request_key (&cifs_idmap_key_type, desc,"" ); + sidkey =request_key (&cifs_idmap_key_type, desc,"" , + &cifs_idmap_key_acl);if (IS_ERR (sidkey)) { rc = -EINVAL ; cifs_dbg(FYI, "%s: Can't map %cid %u to a SID\n",
@@ -403,7 +423,8 @@ sid_to_id(struct cifs_sb_info *cifs_sb, struct cifs_sid *psid,return -ENOMEM ; saved_cred =override_creds (root_cred); - sidkey =request_key (&cifs_idmap_key_type, sidstr,"" ); + sidkey =request_key (&cifs_idmap_key_type, sidstr,"" , + &cifs_idmap_key_acl);if (IS_ERR (sidkey)) { rc = -EINVAL ; cifs_dbg(FYI, "%s: Can't map SID %s to a %cid\n",
@@ -481,8 +502,7 @@ init_cifs_idmap(void) keyring =keyring_alloc (".cifs_idmap" ,GLOBAL_ROOT_UID ,GLOBAL_ROOT_GID , cred, - (KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ , + &cifs_idmap_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA ,NULL ,NULL );if (IS_ERR (keyring)) { ret =PTR_ERR (keyring);
fs/cifs/connect.c +2 -2
@@ -2990,7 +2990,7 @@ cifs_set_cifscreds(struct smb_vol *vol, struct cifs_ses *ses) }cifs_dbg (FYI ,"%s: desc=%s\n" , __func__, desc); - key =request_key (&key_type_logon, desc,"" ); + key =request_key (&key_type_logon, desc,"" ,NULL );if (IS_ERR (key)) {if (!ses->domainName) {cifs_dbg (FYI ,"domainName is NULL\n" );
@@ -3001,7 +3001,7 @@ cifs_set_cifscreds(struct smb_vol *vol, struct cifs_ses *ses)/* didn't work, try to find a domain key */ sprintf (desc,"cifs:d:%s" , ses->domainName);cifs_dbg (FYI ,"%s: desc=%s\n" , __func__, desc); - key =request_key (&key_type_logon, desc,"" ); + key =request_key (&key_type_logon, desc,"" ,NULL );if (IS_ERR (key)) { rc =PTR_ERR (key); goto out_err;
fs/crypto/keyinfo.c +1 -1
@@ -92,7 +92,7 @@ find_and_lock_process_key(const char *prefix,if (!description)return ERR_PTR (-ENOMEM ); - key =request_key (&key_type_logon, description,NULL ); + key =request_key (&key_type_logon, description,NULL ,NULL );kfree (description);if (IS_ERR (key))return key;
fs/ecryptfs/ecryptfs_kernel.h +1 -1
@@ -105,7 +105,7 @@ ecryptfs_get_encrypted_key_payload_data(struct key *key)static inline struct key *ecryptfs_get_encrypted_key (char *sig) { -return request_key (&key_type_encrypted, sig,NULL ); +return request_key (&key_type_encrypted, sig,NULL ,NULL ); }#else
fs/ecryptfs/keystore.c +1 -1
@@ -1624,7 +1624,7 @@ int ecryptfs_keyring_auth_tok_for_sig(struct key **auth_tok_key, {int rc =0 ; - (*auth_tok_key) =request_key (&key_type_user, sig,NULL ); + (*auth_tok_key) =request_key (&key_type_user, sig,NULL ,NULL );if (!(*auth_tok_key) ||IS_ERR (*auth_tok_key)) { (*auth_tok_key) =ecryptfs_get_encrypted_key (sig);if (!(*auth_tok_key) ||IS_ERR (*auth_tok_key)) {
fs/fscache/object-list.c +1 -1
@@ -321,7 +321,7 @@ static void fscache_objlist_config(struct fscache_objlist_data *data)const char *buf;int len; - key =request_key (&key_type_user,"fscache:objlist" ,NULL ); + key =request_key (&key_type_user,"fscache:objlist" ,NULL ,NULL );if (IS_ERR (key)) goto no_config;
fs/nfs/nfs4idmap.c +24 -6
@@ -72,6 +72,25 @@ struct idmap {const struct cred *cred; }; +static struct key_acl nfs_idmap_key_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .possessor_viewable = true, + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_VIEW |KEY_ACE_SEARCH |KEY_ACE_READ ), +KEY_OWNER_ACE (KEY_ACE_VIEW ), + } +}; + +static struct key_acl nfs_idmap_keyring_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_SEARCH |KEY_ACE_WRITE ), +KEY_OWNER_ACE (KEY_ACE_VIEW |KEY_ACE_READ ), + } +}; +static struct user_namespace *idmap_userns (const struct idmap *idmap) {if (idmap && idmap->cred)
@@ -208,8 +227,7 @@ int nfs_idmap_init(void) keyring =keyring_alloc (".id_resolver" ,GLOBAL_ROOT_UID ,GLOBAL_ROOT_GID , cred, - (KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ , + &nfs_idmap_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA ,NULL ,NULL );if (IS_ERR (keyring)) { ret =PTR_ERR (keyring);
@@ -287,11 +305,13 @@ static struct key *nfs_idmap_request_key(const char *name, size_t namelen,return ERR_PTR (ret);if (!idmap->cred || idmap->cred->user_ns = &init_user_ns) - rkey =request_key (&key_type_id_resolver, desc,"" ); + rkey =request_key (&key_type_id_resolver, desc,"" , + &nfs_idmap_key_acl);if (IS_ERR (rkey)) {mutex_lock (&idmap->idmap_mutex); rkey =request_key_with_auxdata (&key_type_id_resolver_legacy, - desc,NULL ,"" ,0 , idmap); + desc,NULL ,"" ,0 , idmap, + &nfs_idmap_key_acl);mutex_unlock (&idmap->idmap_mutex); }if (!IS_ERR (rkey))
@@ -320,8 +340,6 @@ static ssize_t nfs_idmap_get_key(const char *name, size_t namelen, }rcu_read_lock (); - rkey->perm |=KEY_USR_VIEW ; - ret =key_validate (rkey);if (ret <0 ) goto out_up;
fs/ubifs/auth.c +1 -1
@@ -227,7 +227,7 @@ int ubifs_init_authentication(struct ubifs_info *c)snprintf (hmac_name,CRYPTO_MAX_ALG_NAME ,"hmac(%s)" , c->auth_hash_name); - keyring_key =request_key (&key_type_logon, c->auth_key_name,NULL ); + keyring_key =request_key (&key_type_logon, c->auth_key_name,NULL ,NULL );if (IS_ERR (keyring_key)) { ubifs_err(c, "Failed to request key: %ld",
include/linux/key.h +66 -55
222 lines not on this page · raw message
include/uapi/linux/keyctl.h +63 -0
69 lines not on this page · raw message
lib/digsig.c +1 -1
@@ -227,7 +227,7 @@ int digsig_verify(struct key *keyring, const char *sig, int siglen,else key =key_ref_to_ptr (kref); }else { - key =request_key (&key_type_user, name,NULL ); + key =request_key (&key_type_user, name,NULL ,NULL ); }if (IS_ERR (key)) {pr_err ("key not found, id: %s\n" , name);
net/ceph/ceph_common.c +1 -1
@@ -305,7 +305,7 @@ static int get_secret(struct ceph_crypto_key *dst, const char *name) {int err =0 ;struct ceph_crypto_key *ckey; - ukey =request_key (&key_type_ceph, name,NULL ); + ukey =request_key (&key_type_ceph, name,NULL ,NULL );if (IS_ERR (ukey)) {/* request_key errors don't map nicely to mount(2) errors; don't even try, but still printk */
net/dns_resolver/dns_key.c +10 -2
@@ -46,6 +46,15 @@ const struct cred *dns_resolver_cache;#define DNS_ERRORNO_OPTION "dnserror" +static struct key_acl dns_keyring_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_SEARCH |KEY_ACE_WRITE ), +KEY_OWNER_ACE (KEY_ACE_VIEW |KEY_ACE_READ |KEY_ACE_CLEAR ), + } +}; +/* * Preparse instantiation data for a dns_resolver key. *
@@ -343,8 +352,7 @@ static int __init init_dns_resolver(void) keyring =keyring_alloc (".dns_resolver" ,GLOBAL_ROOT_UID ,GLOBAL_ROOT_GID , cred, - (KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ , + &dns_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA ,NULL ,NULL );if (IS_ERR (keyring)) { ret =PTR_ERR (keyring);
net/dns_resolver/dns_query.c +12 -3
@@ -47,6 +47,16 @@#include "internal.h" +static struct key_acl dns_key_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .possessor_viewable = true, + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_VIEW |KEY_ACE_SEARCH |KEY_ACE_READ ), +KEY_OWNER_ACE (KEY_ACE_VIEW |KEY_ACE_INVAL ), + } +}; +/** * dns_query - Query the DNS * @net: The network namespace to operate in.
@@ -125,7 +135,8 @@ int dns_query(struct net *net,* add_key() to preinstall malicious redirections */ saved_cred =override_creds (dns_resolver_cache); - rkey =request_key_net (&key_type_dns_resolver, desc, net, options); + rkey =request_key_net (&key_type_dns_resolver, desc, net, options, + &dns_key_acl);revert_creds (saved_cred);kfree (desc);if (IS_ERR (rkey)) {
@@ -135,8 +146,6 @@ int dns_query(struct net *net,down_read (&rkey->sem);set_bit (KEY_FLAG_ROOT_CAN_INVAL , &rkey->flags); - rkey->perm |=KEY_USR_VIEW ; - ret =key_validate (rkey);if (ret <0 ) goto put;
net/rxrpc/key.c +13 -3
@@ -27,6 +27,14 @@#include <keys/user-type.h> #include "ar-internal.h" +static struct key_acl rxrpc_null_key_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =1 , + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_SEARCH |KEY_ACE_READ ), + } +}; +static int rxrpc_vet_description_s (const char *);static int rxrpc_preparse (struct key_preparsed_payload *);static int rxrpc_preparse_s (struct key_preparsed_payload *);
@@ -914,7 +922,8 @@ int rxrpc_request_key(struct rxrpc_sock *rx, char __user *optval, int optlen)if (IS_ERR (description))return PTR_ERR (description); - key =request_key_net (&key_type_rxrpc, description,sock_net (&rx->sk),NULL ); + key =request_key_net (&key_type_rxrpc, description,sock_net (&rx->sk), +NULL ,NULL );if (IS_ERR (key)) {kfree (description);_leave (" = %ld" ,PTR_ERR (key));
@@ -945,7 +954,8 @@ int rxrpc_server_keyring(struct rxrpc_sock *rx, char __user *optval,if (IS_ERR (description))return PTR_ERR (description); - key =request_key_net (&key_type_keyring, description,sock_net (&rx->sk),NULL ); + key =request_key_net (&key_type_keyring, description,sock_net (&rx->sk), +NULL ,NULL );if (IS_ERR (key)) {kfree (description);_leave (" = %ld" ,PTR_ERR (key));
@@ -1026,7 +1036,7 @@ struct key *rxrpc_get_null_key(const char *keyname) key =key_alloc (&key_type_rxrpc, keyname,GLOBAL_ROOT_UID ,GLOBAL_ROOT_GID , cred, -KEY_POS_SEARCH ,KEY_ALLOC_NOT_IN_QUOTA ,NULL ); + &rxrpc_null_key_acl,KEY_ALLOC_NOT_IN_QUOTA ,NULL );if (IS_ERR (key))return key;
security/integrity/digsig.c +13 -17
@@ -51,7 +51,8 @@ int integrity_digsig_verify(const unsigned int id, const char *sig, int siglen,if (!keyring[id]) { keyring[id] -request_key (&key_type_keyring, keyring_name[id],NULL ); +request_key (&key_type_keyring, keyring_name[id], +NULL ,NULL );if (IS_ERR (keyring[id])) {int err =PTR_ERR (keyring[id]);pr_err ("no %s keyring: %d\n" , keyring_name[id], err);
@@ -73,14 +74,14 @@ int integrity_digsig_verify(const unsigned int id, const char *sig, int siglen,return -EOPNOTSUPP ; } -static int __integrity_init_keyring (const unsigned int id,key_perm_t perm, +static int __integrity_init_keyring (const unsigned int id,struct key_acl *acl,struct key_restriction *restriction) {const struct cred *cred =current_cred ();int err =0 ; keyring[id] =keyring_alloc (keyring_name[id],KUIDT_INIT (0 ), -KGIDT_INIT (0 ), cred, perm, +KGIDT_INIT (0 ), cred, acl,KEY_ALLOC_NOT_IN_QUOTA , restriction,NULL );if (IS_ERR (keyring[id])) { err =PTR_ERR (keyring[id]);
@@ -98,10 +99,7 @@ static int __integrity_init_keyring(const unsigned int id, key_perm_t perm,int __init integrity_init_keyring (const unsigned int id) {struct key_restriction *restriction; -key_perm_t perm; - - perm = (KEY_POS_ALL & ~KEY_POS_SETATTR ) |KEY_USR_VIEW - |KEY_USR_READ |KEY_USR_SEARCH ; +struct key_acl *acl = &internal_keyring_acl;if (id =INTEGRITY_KEYRING_PLATFORM ) { restriction =NULL ;
@@ -116,14 +114,14 @@ int __init integrity_init_keyring(const unsigned int id)return -ENOMEM ; restriction->check = restrict_link_to_ima; - perm |=KEY_USR_WRITE ; + acl = &internal_writable_keyring_acl; out: -return __integrity_init_keyring (id, perm, restriction); +return __integrity_init_keyring (id, &internal_keyring_acl, restriction); } -int __init integrity_add_key (const unsigned int id,const void *data, -off_t size,key_perm_t perm) +static int __init integrity_add_key (const unsigned int id,const void *data, +off_t size,struct key_acl *acl) {key_ref_t key;int rc =0 ;
@@ -132,7 +130,7 @@ int __init integrity_add_key(const unsigned int id, const void *data,return -EINVAL ; key =key_create_or_update (make_key_ref (keyring[id],1 ),"asymmetric" , -NULL , data, size, perm, +NULL , data, size, acl ?: &internal_key_acl,KEY_ALLOC_NOT_IN_QUOTA );if (IS_ERR (key)) { rc =PTR_ERR (key);
@@ -152,7 +150,6 @@ int __init integrity_load_x509(const unsigned int id, const char *path)void *data;loff_t size;int rc; -key_perm_t perm; rc =kernel_read_file_from_path (path, &data, &size,0 ,READING_X509_CERTIFICATE );
@@ -161,21 +158,19 @@ int __init integrity_load_x509(const unsigned int id, const char *path)return rc; } - perm = (KEY_POS_ALL & ~KEY_POS_SETATTR ) |KEY_USR_VIEW |KEY_USR_READ ; -pr_info ("Loading X.509 certificate: %s\n" , path); - rc =integrity_add_key (id, (const void *)data, size, perm); + rc =integrity_add_key (id, data, size,NULL );vfree (data);return rc; }int __init integrity_load_cert (const unsigned int id,const char *source, -const void *data,size_t len,key_perm_t perm) +const void *data,size_t len,struct key_acl *acl) {if (!data)return -EINVAL ;pr_info ("Loading X.509 certificate: %s\n" , source); -return integrity_add_key (id, data, len, perm); +return integrity_add_key (id, data, len, acl); }
security/integrity/digsig_asymmetric.c +1 -1
@@ -57,7 +57,7 @@ static struct key *request_asymmetric_key(struct key *keyring, uint32_t keyid)else key =key_ref_to_ptr (kref); }else { - key =request_key (&key_type_asymmetric, name,NULL ); + key =request_key (&key_type_asymmetric, name,NULL ,NULL ); }if (IS_ERR (key)) {
security/integrity/evm/evm_crypto.c +1 -1
@@ -356,7 +356,7 @@ int evm_init_key(void)struct encrypted_key_payload *ekp;int rc; - evm_key =request_key (&key_type_encrypted,EVMKEY ,NULL ); + evm_key =request_key (&key_type_encrypted,EVMKEY ,NULL ,NULL );if (IS_ERR (evm_key))return -ENOENT ;
security/integrity/ima/ima_mok.c +10 -3
@@ -21,6 +21,15 @@#include <keys/system_keyring.h> +static struct key_acl integrity_blacklist_keyring_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_SEARCH |KEY_ACE_WRITE ), +KEY_OWNER_ACE (KEY_ACE_VIEW |KEY_ACE_READ |KEY_ACE_WRITE |KEY_ACE_SEARCH ), + } +}; +struct key *ima_blacklist_keyring;/*
@@ -40,9 +49,7 @@ __init int ima_mok_init(void) ima_blacklist_keyring =keyring_alloc (".ima_blacklist" ,KUIDT_INIT (0 ),KGIDT_INIT (0 ),current_cred (), - (KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ | -KEY_USR_WRITE |KEY_USR_SEARCH , + &integrity_blacklist_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA , restriction,NULL );
security/integrity/integrity.h +2 -2
@@ -154,7 +154,7 @@ int integrity_digsig_verify(const unsigned int id, const char *sig, int siglen,int __init integrity_init_keyring (const unsigned int id);int __init integrity_load_x509 (const unsigned int id,const char *path);int __init integrity_load_cert (const unsigned int id,const char *source, -const void *data,size_t len,key_perm_t perm); +const void *data,size_t len,struct key_acl *acl);#else static inline int integrity_digsig_verify(const unsigned int id,
@@ -172,7 +172,7 @@ static inline int integrity_init_keyring(const unsigned int id)static inline int __init integrity_load_cert (const unsigned int id,const char *source,const void *data,size_t len, -key_perm_t perm) +struct key_acl *acl) {return 0 ; }
security/integrity/platform_certs/platform_keyring.c +10 -3
@@ -14,6 +14,15 @@#include <linux/slab.h> #include "../integrity.h" +static struct key_acl platform_key_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_SEARCH |KEY_ACE_READ ), +KEY_OWNER_ACE (KEY_ACE_VIEW ), + } +}; +/** * add_to_platform_keyring - Add to platform keyring without validation. * @source: Source of key
@@ -29,10 +38,8 @@ void __init add_to_platform_keyring(const char *source, const void *data,key_perm_t perm;int rc; - perm = (KEY_POS_ALL & ~KEY_POS_SETATTR ) |KEY_USR_VIEW ; - rc =integrity_load_cert (INTEGRITY_KEYRING_PLATFORM , source, data, len, - perm); + &platform_key_acl);if (rc)pr_info ("Error adding keys to platform keyring %s\n" , source); }
security/keys/encrypted-keys/encrypted.c +1 -1
@@ -307,7 +307,7 @@ static struct key *request_user_key(const char *master_desc, const u8 **master_kconst struct user_key_payload *upayload;struct key *ukey; - ukey =request_key (&key_type_user, master_desc,NULL ); + ukey =request_key (&key_type_user, master_desc,NULL ,NULL );if (IS_ERR (ukey)) goto error;
security/keys/encrypted-keys/masterkey_trusted.c +1 -1
@@ -33,7 +33,7 @@ struct key *request_trusted_key(const char *trusted_desc,struct trusted_key_payload *tpayload;struct key *tkey; - tkey =request_key (&key_type_trusted, trusted_desc,NULL ); + tkey =request_key (&key_type_trusted, trusted_desc,NULL ,NULL );if (IS_ERR (tkey)) goto error;
security/keys/gc.c +1 -1
@@ -155,6 +155,7 @@ static noinline void key_gc_unused_keys(struct list_head *keys)key_user_put (key->user);key_put_tag (key->domain_tag); +key_put_acl (rcu_access_pointer (key->acl));kfree (key->description);memzero_explicit (key,sizeof (*key));
@@ -224,7 +225,6 @@ static void key_garbage_collector(struct work_struct *work)if (key->type = key_gc_dead_keytype) { gc_state |=KEY_GC_FOUND_DEAD_KEY ;set_bit (KEY_FLAG_DEAD , &key->flags); - key->perm =0 ; goto skip_dead_key; }else if (key->type = &key_type_keyring && key->restrict_link) {
security/keys/internal.h +9 -2
@@ -88,8 +88,11 @@ extern struct rb_root key_serial_tree;extern spinlock_t key_serial_lock;extern struct mutex key_construction_mutex;extern wait_queue_head_t request_key_conswq; +extern struct key_acl default_key_acl; +extern struct key_acl joinable_keyring_acl;extern void key_set_index_key (struct keyring_index_key *index_key); +extern struct key_type *key_type_lookup (const char *type);extern void key_type_put (struct key_type *ktype);
@@ -156,6 +159,7 @@ extern struct key *request_key_and_link(struct key_type *type,const void *callout_info, size_t callout_len, void *aux, + struct key_acl *acl, struct key *dest_keyring, unsigned long flags);
@@ -179,7 +183,10 @@ extern void key_gc_keytype(struct key_type *ktype);extern int key_task_permission (const key_ref_t key_ref,const struct cred *cred, -key_perm_t perm); +u32 desired_perm); +extern unsigned int key_acl_to_perm (const struct key_acl *acl); +extern long key_set_acl (struct key *key,struct key_acl *acl); +extern void key_put_acl (struct key_acl *acl);/* * Check to see whether permission is granted to use a key in the desired way.
@@ -226,7 +233,7 @@ extern long keyctl_keyring_search(key_serial_t, const char __user *, const char __user *, key_serial_t);extern long keyctl_read_key (key_serial_t ,char __user *,size_t );extern long keyctl_chown_key (key_serial_t ,uid_t ,gid_t ); -extern long keyctl_setperm_key (key_serial_t ,key_perm_t ); +extern long keyctl_setperm_key (key_serial_t ,unsigned int );extern long keyctl_instantiate_key (key_serial_t ,const void __user *,size_t ,key_serial_t );extern long keyctl_negate_key (key_serial_t ,unsigned ,key_serial_t );
security/keys/key.c +10 -19
@@ -199,7 +199,7 @@ static inline void key_alloc_serial(struct key *key)* @uid: The owner of the new key. * @gid: The group ID for the new key's group permissions. * @cred: The credentials specifying UID namespace. -* @perm: The permissions mask of the new key. +* @acl: The ACL to attach to the new key. * @flags: Flags specifying quota properties. * @restrict_link: Optional link restriction for new keyrings. *
@@ -227,7 +227,7 @@ static inline void key_alloc_serial(struct key *key)*/ struct key *key_alloc (struct key_type *type,const char *desc,kuid_t uid,kgid_t gid,const struct cred *cred, -key_perm_t perm,unsigned long flags, +struct key_acl *acl,unsigned long flags,struct key_restriction *restrict_link) {struct key_user *user =NULL ;
@@ -250,6 +250,9 @@ struct key *key_alloc(struct key_type *type, const char *desc, desclen =strlen (desc); quotalen = desclen +1 + type->def_datalen; +if (!acl) + acl = &default_key_acl; +/* get hold of the key tracking for this user */ user =key_user_lookup (uid);if (!user)
@@ -296,7 +299,8 @@ struct key *key_alloc(struct key_type *type, const char *desc, key->datalen = type->def_datalen; key->uid = uid; key->gid = gid; - key->perm = perm; +refcount_inc (&acl->usage); +rcu_assign_pointer (key->acl, acl); key->restrict_link = restrict_link; key->last_used_at =ktime_get_real_seconds ();
@@ -782,7 +786,7 @@ static inline key_ref_t __key_update(key_ref_t key_ref,* @description: The searchable description for the key. * @payload: The data to use to instantiate or update the key. * @plen: The length of @payload. -* @perm: The permissions mask for a new key. +* @acl: The ACL to attach if a key is created. * @flags: The quota flags for a new key. * * Search the destination keyring for a key of the same description and if one
@@ -805,7 +809,7 @@ key_ref_t key_create_or_update(key_ref_t keyring_ref, const char *description, const void *payload, size_t plen, - key_perm_t perm, + struct key_acl *acl, unsigned long flags) { struct keyring_index_key index_key = {
@@ -896,22 +900,9 @@ key_ref_t key_create_or_update(key_ref_t keyring_ref, goto found_matching_key; } -/* if the client doesn't provide, decide on the permissions we want */ -if (perm =KEY_PERM_UNDEF ) { - perm =KEY_POS_VIEW |KEY_POS_SEARCH |KEY_POS_LINK |KEY_POS_SETATTR ; - perm |=KEY_USR_VIEW ; - -if (index_key.type->read) - perm |=KEY_POS_READ ; - -if (index_key.type = &key_type_keyring || - index_key.type->update) - perm |=KEY_POS_WRITE ; - } -/* allocate a new key */ key =key_alloc (index_key.type, index_key.description, - cred->fsuid, cred->fsgid, cred, perm, flags,NULL ); + cred->fsuid, cred->fsgid, cred, acl, flags,NULL );if (IS_ERR (key)) { key_ref =ERR_CAST (key); goto error_link_end;
security/keys/keyctl.c +63 -29
190 lines not on this page · raw message
security/keys/keyring.c +18 -9
@@ -519,11 +519,19 @@ static long keyring_read(const struct key *keyring,return ret; } -/* -* Allocate a keyring and link into the destination keyring. +/** +* keyring_alloc - Allocate a keyring and link into the destination +* @description: The key description to allow the key to be searched out. +* @uid: The owner of the new key. +* @gid: The group ID for the new key's group permissions. +* @cred: The credentials specifying UID namespace. +* @acl: The ACL to attach to the new key. +* @flags: Flags specifying quota properties. +* @restrict_link: Optional link restriction for new keyrings. +* @dest: Destination keyring. */ struct key *keyring_alloc (const char *description,kuid_t uid,kgid_t gid, -const struct cred *cred,key_perm_t perm, +const struct cred *cred,struct key_acl *acl,unsigned long flags,struct key_restriction *restrict_link,struct key *dest)
@@ -532,7 +540,7 @@ struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid,int ret; keyring =key_alloc (&key_type_keyring, description, - uid, gid, cred, perm, flags, restrict_link); + uid, gid, cred, acl, flags, restrict_link);if (!IS_ERR (keyring)) { ret =key_instantiate_and_link (keyring,NULL ,0 , dest,NULL );if (ret <0 ) {
@@ -1136,10 +1144,11 @@ key_ref_t find_key_to_update(key_ref_t keyring_ref,/* * Find a keyring with the specified name. * -* Only keyrings that have nonzero refcount, are not revoked, and are owned by a -* user in the current user namespace are considered. If @uid_keyring is %true, -* the keyring additionally must have been allocated as a user or user session -* keyring; otherwise, it must grant Search permission directly to the caller. +* Only keyrings that have nonzero refcount, are not revoked, and are owned by +* a user in the current user namespace are considered. If @uid_keyring is +* %true, the keyring additionally must have been allocated as a user or user +* session keyring; otherwise, it must grant JOIN permission directly to the +* caller (ie. not through possession). * * Returns a pointer to the keyring with the keyring's refcount having being * incremented on success. -ENOKEY is returned if a key could not be found.
@@ -1173,7 +1182,7 @@ struct key *find_keyring_by_name(const char *name, bool uid_keyring)continue ; }else {if (key_permission (make_key_ref (keyring,0 ), -KEY_NEED_SEARCH ) <0 ) +KEY_NEED_JOIN ) <0 )continue ; }
security/keys/permission.c +201 -36
270 lines not on this page · raw message
security/keys/persistent.c +23 -4
@@ -16,6 +16,27 @@unsigned persistent_keyring_expiry =3 *24 *3600 ;/* Expire after 3 days of non-use */ +static struct key_acl persistent_register_keyring_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_SEARCH |KEY_ACE_WRITE ), +KEY_OWNER_ACE (KEY_ACE_VIEW |KEY_ACE_READ ), + } +}; + +static struct key_acl persistent_keyring_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .possessor_viewable = true, + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_VIEW |KEY_ACE_READ |KEY_ACE_WRITE | +KEY_ACE_SEARCH |KEY_ACE_LINK | +KEY_ACE_CLEAR |KEY_ACE_INVAL ), +KEY_OWNER_ACE (KEY_ACE_VIEW |KEY_ACE_READ ), + } +}; +/* * Create the persistent keyring register for the current user namespace. *
@@ -26,8 +47,7 @@ static int key_create_persistent_register(struct user_namespace *ns)struct key *reg =keyring_alloc (".persistent_register" ,KUIDT_INIT (0 ),KGIDT_INIT (0 ),current_cred (), - ((KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ ), + &persistent_register_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA ,NULL ,NULL );if (IS_ERR (reg))return PTR_ERR (reg);
@@ -60,8 +80,7 @@ static key_ref_t key_create_persistent(struct user_namespace *ns, kuid_t uid, persistent =keyring_alloc (index_key->description, uid,INVALID_GID ,current_cred (), - ((KEY_POS_ALL & ~KEY_POS_SETATTR ) | -KEY_USR_VIEW |KEY_USR_READ ), + &persistent_keyring_acl,KEY_ALLOC_NOT_IN_QUOTA ,NULL , ns->persistent_keyring_register);if (IS_ERR (persistent))
security/keys/proc.c +11 -9
@@ -119,6 +119,7 @@ static void *proc_keys_start(struct seq_file *p, loff_t *_pos)key_serial_t pos = *_pos;struct key *key; +rcu_read_lock ();spin_lock (&key_serial_lock);if (*_pos >INT_MAX )
@@ -150,10 +151,12 @@ static void proc_keys_stop(struct seq_file *p, void *v)__releases (key_serial_lock) {spin_unlock (&key_serial_lock); +rcu_read_unlock (); }static int proc_keys_show (struct seq_file *m,void *v) { +const struct key_acl *acl;struct rb_node *_p = v; struct key *key = rb_entry(_p, struct key, serial_node);unsigned long flags;
@@ -161,6 +164,7 @@ static int proc_keys_show(struct seq_file *m, void *v)time64_t now, expiry;char xbuf[16 ];short state; +bool check_pos;u64 timo;int rc;
@@ -174,15 +178,15 @@ static int proc_keys_show(struct seq_file *m, void *v) KEYRING_SEARCH_RECURSE), }; - key_ref =make_key_ref (key,0 ); + acl =rcu_dereference (key->acl); + check_pos = acl->possessor_viewable;/* determine if the key is possessed by this process (a test we can * skip if the key does not indicate the possessor can view it */ -if (key->perm &KEY_POS_VIEW ) { -rcu_read_lock (); + key_ref =make_key_ref (key,0 ); +if (check_pos) { skey_ref =search_cred_keyrings_rcu (&ctx); -rcu_read_unlock ();if (!IS_ERR (skey_ref)) {key_ref_put (skey_ref); key_ref =make_key_ref (key,1 );
@@ -192,12 +196,10 @@ static int proc_keys_show(struct seq_file *m, void *v)/* check whether the current task is allowed to view the key */ rc =key_task_permission (key_ref, ctx.cred,KEY_NEED_VIEW );if (rc <0 ) -return 0 ; + goto out; now =ktime_get_real_seconds (); -rcu_read_lock (); -/* come up with a suitable timeout value */ expiry =READ_ONCE (key->expiry);if (expiry =0 ) {
@@ -236,7 +238,7 @@ static int proc_keys_show(struct seq_file *m, void *v)showflag (flags,'i' ,KEY_FLAG_INVALIDATED ),refcount_read (&key->usage), xbuf, - key->perm, +key_acl_to_perm (acl),from_kuid_munged (seq_user_ns (m), key->uid),from_kgid_munged (seq_user_ns (m), key->gid), key->type->name);
@@ -247,7 +249,7 @@ static int proc_keys_show(struct seq_file *m, void *v) key->type->describe (key, m);seq_putc (m,'\n' ); -rcu_read_unlock (); +out:return 0 ; }
security/keys/process_keys.c +64 -22
178 lines not on this page · raw message
security/keys/request_key.c +16 -18
@@ -139,8 +139,7 @@ static int call_sbin_request_key(struct key *authkey, void *aux) cred =get_current_cred (); keyring =keyring_alloc (desc, cred->fsuid, cred->fsgid, cred, -KEY_POS_ALL |KEY_USR_VIEW |KEY_USR_READ , -KEY_ALLOC_QUOTA_OVERRUN ,NULL ,NULL ); +NULL ,KEY_ALLOC_QUOTA_OVERRUN ,NULL ,NULL );put_cred (cred);if (IS_ERR (keyring)) { ret =PTR_ERR (keyring);
@@ -371,11 +370,11 @@ static int construct_alloc_key(struct keyring_search_context *ctx,struct key *dest_keyring, unsigned long flags, struct key_user *user, + struct key_acl *acl, struct key **_key) { struct assoc_array_edit *edit;struct key *key; -key_perm_t perm;key_ref_t key_ref;int ret;
@@ -385,17 +384,9 @@ static int construct_alloc_key(struct keyring_search_context *ctx, *_key =NULL ;mutex_lock (&user->cons_lock); - perm =KEY_POS_VIEW |KEY_POS_SEARCH |KEY_POS_LINK |KEY_POS_SETATTR ; - perm |=KEY_USR_VIEW ; -if (ctx->index_key.type->read) - perm |=KEY_POS_READ ; -if (ctx->index_key.type = &key_type_keyring || - ctx->index_key.type->update) - perm |=KEY_POS_WRITE ; - key =key_alloc (ctx->index_key.type, ctx->index_key.description, ctx->cred->fsuid, ctx->cred->fsgid, ctx->cred, - perm, flags,NULL ); + acl, flags,NULL );if (IS_ERR (key)) goto alloc_failed;
@@ -473,6 +464,7 @@ static struct key *construct_key_and_link(struct keyring_search_context *ctx,const char *callout_info, size_t callout_len, void *aux, + struct key_acl *acl, struct key *dest_keyring, unsigned long flags) {
@@ -495,7 +487,7 @@ static struct key *construct_key_and_link(struct keyring_search_context *ctx, goto error_put_dest_keyring; } - ret =construct_alloc_key (ctx, dest_keyring, flags, user, &key); + ret =construct_alloc_key (ctx, dest_keyring, flags, user, acl, &key);key_user_put (user);if (ret =0 ) {
@@ -533,6 +525,7 @@ static struct key *construct_key_and_link(struct keyring_search_context *ctx,* @callout_info: The data to pass to the instantiation upcall (or NULL). * @callout_len: The length of callout_info. * @aux: Auxiliary data for the upcall. +* @acl: The ACL to attach if a new key is created. * @dest_keyring: Where to cache the key. * @flags: Flags to key_alloc(). *
@@ -560,6 +553,7 @@ struct key *request_key_and_link(struct key_type *type,const void *callout_info, size_t callout_len, void *aux, + struct key_acl *acl, struct key *dest_keyring, unsigned long flags) {
@@ -634,7 +628,7 @@ struct key *request_key_and_link(struct key_type *type, goto error_free; key =construct_key_and_link (&ctx, callout_info, callout_len, - aux, dest_keyring, flags); + aux, acl, dest_keyring, flags); } error_free:
@@ -677,6 +671,7 @@ EXPORT_SYMBOL(wait_for_key_construction);* @description: The searchable description of the key. * @domain_tag: The domain in which the key operates. * @callout_info: The data to pass to the instantiation upcall (or NULL). +* @acl: The ACL to attach if a new key is created. * * As for request_key_and_link() except that it does not add the returned key * to a keyring if found, new keys are always allocated in the user's quota,
@@ -689,7 +684,8 @@ EXPORT_SYMBOL(wait_for_key_construction);struct key *request_key_tag (struct key_type *type,const char *description,struct key_tag *domain_tag, -const char *callout_info) +const char *callout_info, +struct key_acl *acl) {struct key *key;size_t callout_len =0 ;
@@ -699,7 +695,7 @@ struct key *request_key_tag(struct key_type *type, callout_len =strlen (callout_info); key =request_key_and_link (type, description, domain_tag, callout_info, callout_len, -NULL ,NULL ,KEY_ALLOC_IN_QUOTA ); +NULL , acl,NULL ,KEY_ALLOC_IN_QUOTA );if (!IS_ERR (key)) { ret =wait_for_key_construction (key, false);if (ret <0 ) {
@@ -719,6 +715,7 @@ EXPORT_SYMBOL(request_key_tag);* @callout_info: The data to pass to the instantiation upcall (or NULL). * @callout_len: The length of callout_info. * @aux: Auxiliary data for the upcall. +* @acl: The ACL to attach if a new key is created. * * As for request_key_and_link() except that it does not add the returned key * to a keyring if found and new keys are always allocated in the user's quota.
@@ -731,14 +728,15 @@ struct key *request_key_with_auxdata(struct key_type *type,struct key_tag *domain_tag, const void *callout_info, size_t callout_len, - void *aux) + void *aux, + struct key_acl *acl) { struct key *key;int ret; key =request_key_and_link (type, description, domain_tag, callout_info, callout_len, - aux,NULL ,KEY_ALLOC_IN_QUOTA ); + aux, acl,NULL ,KEY_ALLOC_IN_QUOTA );if (!IS_ERR (key)) { ret =wait_for_key_construction (key, false);if (ret <0 ) {
security/keys/request_key_auth.c +13 -2
@@ -28,6 +28,17 @@ static void request_key_auth_revoke(struct key *);static void request_key_auth_destroy (struct key *);static long request_key_auth_read (const struct key *,char __user *,size_t ); +static struct key_acl request_key_auth_acl = { + .usage =REFCOUNT_INIT (1 ), + .nr_ace =2 , + .possessor_viewable = true, + .aces = { +KEY_POSSESSOR_ACE (KEY_ACE_VIEW |KEY_ACE_READ |KEY_ACE_SEARCH | +KEY_ACE_LINK ), +KEY_OWNER_ACE (KEY_ACE_VIEW ), + } +}; +/* * The request-key authorisation key type definition. */
@@ -214,8 +225,8 @@ struct key *request_key_auth_new(struct key *target, const char *op, authkey =key_alloc (&key_type_request_key_auth, desc, cred->fsuid, cred->fsgid, cred, -KEY_POS_VIEW |KEY_POS_READ |KEY_POS_SEARCH |KEY_POS_LINK | -KEY_USR_VIEW ,KEY_ALLOC_NOT_IN_QUOTA ,NULL ); + &request_key_auth_acl, +KEY_ALLOC_NOT_IN_QUOTA ,NULL );if (IS_ERR (authkey)) { ret =PTR_ERR (authkey); goto error_free_rka;
security/selinux/hooks.c +15 -1
@@ -6481,6 +6481,7 @@ static int selinux_key_permission(key_ref_t key_ref, {struct key *key;struct key_security_struct *ksec; +unsigned oldstyle_perm;u32 sid;/* if no specific permissions are requested, we skip the
@@ -6489,13 +6490,26 @@ static int selinux_key_permission(key_ref_t key_ref,if (perm =0 )return 0 ; + oldstyle_perm = perm & (KEY_NEED_VIEW |KEY_NEED_READ |KEY_NEED_WRITE | +KEY_NEED_SEARCH |KEY_NEED_LINK ); +if (perm &KEY_NEED_SETSEC ) + oldstyle_perm |=OLD_KEY_NEED_SETATTR ; +if (perm &KEY_NEED_INVAL ) + oldstyle_perm |=KEY_NEED_SEARCH ; +if (perm &KEY_NEED_REVOKE && !(perm &OLD_KEY_NEED_SETATTR )) + oldstyle_perm |=KEY_NEED_WRITE ; +if (perm &KEY_NEED_JOIN ) + oldstyle_perm |=KEY_NEED_SEARCH ; +if (perm &KEY_NEED_CLEAR ) + oldstyle_perm |=KEY_NEED_WRITE ; + sid =cred_sid (cred); key =key_ref_to_ptr (key_ref); ksec = key->security;return avc_has_perm (&selinux_state, - sid, ksec->sid,SECCLASS_KEY , perm,NULL ); + sid, ksec->sid,SECCLASS_KEY , oldstyle_perm,NULL ); }static int selinux_key_getsecurity (struct key *key,char **_buffer)
security/smack/smack_lsm.c +2 -1
@@ -4285,7 +4285,8 @@ static int smack_key_permission(key_ref_t key_ref,#endif if (perm & (KEY_NEED_READ |KEY_NEED_SEARCH |KEY_NEED_VIEW )) request |=MAY_READ ; -if (perm & (KEY_NEED_WRITE |KEY_NEED_LINK |KEY_NEED_SETATTR )) +if (perm & (KEY_NEED_WRITE |KEY_NEED_LINK |KEY_NEED_SETSEC | +KEY_NEED_INVAL |KEY_NEED_REVOKE |KEY_NEED_CLEAR )) request |=MAY_WRITE ; rc =smk_access (tkp, keyp->security, request, &ad); rc =smk_bu_note ("key access" , tkp, keyp->security, request, rc);
Eric Biggers
maintainerRe: [PATCH 1/2] KEYS: Replace uid/gid/perm permissions checking with an ACL
Quoted 4 lines · David Howells
Replace the uid/gid/perm permissions checking on a key with an ACL to allow the SETATTR and SEARCH permissions to be split. This will also allow a greater range of subjects to represented.
This patch broke 'keyctl new_session', and hence broke all the fscrypt tests:
$ keyctl new_session keyctl_session_to_parent: Permission denied
Output of 'keyctl show' is
$ keyctl show Session Keyring 605894913 --alswrv 0 0 keyring: _ses 189223103 ----s-rv 0 0 \_ user: invocation_id
- Eric
Eric Biggers
maintainerRe: [PATCH 1/2] KEYS: Replace uid/gid/perm permissions checking with an ACL
Quoted 11 lines · Eric Biggers
Quoted 4 lines · David Howells
Replace the uid/gid/perm permissions checking on a key with an ACL to allow the SETATTR and SEARCH permissions to be split. This will also allow a greater range of subjects to represented.
This patch broke 'keyctl
new_session', and hence broke all the fscrypt tests:$ keyctl new_session keyctl_session_to_parent: Permission denied
Quoted 8 lines
Output of 'keyctl show' is
$ keyctl show Session Keyring 605894913 --alswrv 0 0 keyring: _ses 189223103 ----s-rv 0 0 \_ user: invocation_id- Eric
... and this also broke loading in-kernel X.509 certificates. See the other
thread: https://lore.kernel.org/lkml/27671.1562384658@turing-police/T/#u
- Eric
Eric Biggers
maintainerRe: [PATCH 1/2] KEYS: Replace uid/gid/perm permissions checking with an ACL
In reply to Eric BiggersHi David,
Quoted 11 lines · Eric Biggers
Quoted 4 lines · David Howells
Replace the uid/gid/perm permissions checking on a key with an ACL to allow the SETATTR and SEARCH permissions to be split. This will also allow a greater range of subjects to represented.
This patch broke 'keyctl
new_session', and hence broke all the fscrypt tests:$ keyctl new_session keyctl_session_to_parent: Permission denied
Quoted 8 lines
Output of 'keyctl show' is
$ keyctl show Session Keyring 605894913 --alswrv 0 0 keyring: _ses 189223103 ----s-rv 0 0 \_ user: invocation_id- Eric
This bug is still present in next-20190729.
- Eric
Eric Biggers
maintainerRe: [PATCH 1/2] KEYS: Replace uid/gid/perm permissions checking with an ACL
Quoted 21 lines · Eric Biggers
Hi David,
Quoted 18 lines · Eric Biggers
Quoted 4 lines · David Howells
Replace the uid/gid/perm permissions checking on a key with an ACL to allow the SETATTR and SEARCH permissions to be split. This will also allow a greater range of subjects to represented.
This patch broke 'keyctl
new_session', and hence broke all the fscrypt tests:$ keyctl new_session keyctl_session_to_parent: Permission deniedOutput of 'keyctl show' is
$ keyctl show Session Keyring 605894913 --alswrv 0 0 keyring: _ses 189223103 ----s-rv 0 0 \_ user: invocation_id
Quoted 5 lines
Quoted 1 line
- Eric
This bug is still present in next-20190729.
- Eric
This fixes it:
security/keys/process_keys.c +1 -1
@@ -58,7 +58,7 @@ static struct key_acl session_keyring_acl = { .possessor_viewable = true, .nr_ace = 2, .aces = { - KEY_POSSESSOR_ACE(KEY_ACE__PERMS & ~KEY_ACE_JOIN), + KEY_POSSESSOR_ACE(KEY_ACE__PERMS), KEY_OWNER_ACE(KEY_ACE_VIEW | KEY_ACE_READ), } };
The old permissions were KEY_POS_ALL | KEY_USR_VIEW | KEY_USR_READ, so I'm not sure why JOIN permission was removed?
- Eric
Eric Biggers
maintainerRe: [PATCH 1/2] KEYS: Replace uid/gid/perm permissions checking with an ACL
Quoted 45 lines · Eric Biggers
Quoted 21 lines · Eric Biggers
Hi David,
Quoted 18 lines · Eric Biggers
Quoted 4 lines · David Howells
Replace the uid/gid/perm permissions checking on a key with an ACL to allow the SETATTR and SEARCH permissions to be split. This will also allow a greater range of subjects to represented.
This patch broke 'keyctl
new_session', and hence broke all the fscrypt tests:$ keyctl new_session keyctl_session_to_parent: Permission deniedOutput of 'keyctl show' is
$ keyctl show Session Keyring 605894913 --alswrv 0 0 keyring: _ses 189223103 ----s-rv 0 0 \_ user: invocation_idQuoted 5 lines
Quoted 1 line
- Eric
This bug is still present in next-20190729.
- Eric
This fixes it:
security/keys/process_keys.c +1
-1@@ -58,7 +58,7 @@ static struct key_acl session_keyring_acl = { .possessor_viewable = true, .nr_ace = 2, .aces = { - KEY_POSSESSOR_ACE(KEY_ACE__PERMS & ~KEY_ACE_JOIN), + KEY_POSSESSOR_ACE(KEY_ACE__PERMS), KEY_OWNER_ACE(KEY_ACE_VIEW | KEY_ACE_READ), } };
Quoted 4 lines
The old permissions were
KEY_POS_ALL|KEY_USR_VIEW|KEY_USR_READ, so I'm not sure why JOIN permission was removed?- Eric
Ping. This is still broken in linux-next.
- Eric
Eric Biggers
maintainerRe: [PATCH 1/2] KEYS: Replace uid/gid/perm permissions checking with an ACL
Quoted 46 lines · Eric Biggers
Quoted 45 lines · Eric Biggers
Quoted 21 lines · Eric Biggers
Hi David,
Quoted 18 lines · Eric Biggers
Quoted 4 lines · David Howells
Replace the uid/gid/perm permissions checking on a key with an ACL to allow the SETATTR and SEARCH permissions to be split. This will also allow a greater range of subjects to represented.
This patch broke 'keyctl
new_session', and hence broke all the fscrypt tests:$ keyctl new_session keyctl_session_to_parent: Permission deniedOutput of 'keyctl show' is
$ keyctl show Session Keyring 605894913 --alswrv 0 0 keyring: _ses 189223103 ----s-rv 0 0 \_ user: invocation_idQuoted 5 lines
Quoted 1 line
- Eric
This bug is still present in next-20190729.
- Eric
This fixes it:
security/keys/process_keys.c +1
-1@@ -58,7 +58,7 @@ static struct key_acl session_keyring_acl = { .possessor_viewable = true, .nr_ace = 2, .aces = { - KEY_POSSESSOR_ACE(KEY_ACE__PERMS & ~KEY_ACE_JOIN), + KEY_POSSESSOR_ACE(KEY_ACE__PERMS), KEY_OWNER_ACE(KEY_ACE_VIEW | KEY_ACE_READ), } };
Quoted 7 lines
Quoted 4 lines
The old permissions were
KEY_POS_ALL|KEY_USR_VIEW|KEY_USR_READ, so I'm not sure why JOIN permission was removed?- Eric
Ping. This is still broken in linux-next.
David, any comment on this? This is still broken in linux-next.
- Eric
Eric Biggers
maintainerPATCH 1/1 keys: Fix permissions assigned to anonymous session keyrings
From: Eric Biggers <[email protected]>
JOIN permission was incorrectly removed from anonymous session keyrings when the old-style key permissions were translated to an ACL, thus breaking 'keyctl new_session'.
--- security/keys/process_keys.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
security/keys/process_keys.c +1 -1
@@ -58,7 +58,7 @@ static struct key_acl session_keyring_acl = { .possessor_viewable = true, .nr_ace = 2, .aces = { - KEY_POSSESSOR_ACE(KEY_ACE__PERMS & ~KEY_ACE_JOIN), + KEY_POSSESSOR_ACE(KEY_ACE__PERMS), KEY_OWNER_ACE(KEY_ACE_VIEW | KEY_ACE_READ), } };
Signature · 1 line
2.23.0.187.g17f5b7556c-goog
David Howells
maintainerPATCH 2/2 KEYS: Provide KEYCTL_GRANT_PERMISSION
In reply to David HowellsProvide a keyctl() operation to grant/remove permissions. The grant operation, wrapped by libkeyutils, looks like:
int ret = keyctl_grant_permission(key_serial_t key,
enum key_ace_subject_type type, unsigned int subject, unsigned int perm);
Where key is the key to be modified, type and subject represent the subject to which permission is to be granted (or removed) and perm is the set of permissions to be granted. 0 is returned on success. SET_SECURITY permission is required for this.
The subject type currently must be KEY_ACE_SUBJ_STANDARD for the moment (other subject types will come along later).
For subject type KEY_ACE_SUBJ_STANDARD, the following subject values are available:
KEY_ACE_POSSESSOR The possessor of the key
KEY_ACE_OWNER The owner of the key
KEY_ACE_GROUP The key's group
KEY_ACE_EVERYONE Everyone
perm lists the permissions to be granted:
KEY_ACE_VIEW Can view the key metadata
KEY_ACE_READ Can read the key content
KEY_ACE_WRITE Can update/modify the key content
KEY_ACE_SEARCH Can find the key by searching/requesting
KEY_ACE_LINK Can make a link to the key
KEY_ACE_SET_SECURITY Can set security
KEY_ACE_INVAL Can invalidate
KEY_ACE_REVOKE Can revoke
KEY_ACE_JOIN Can join this keyring
KEY_ACE_CLEAR Can clear this keyring
If an ACE already exists for the subject, then the permissions mask will be overwritten; if perm is 0, it will be deleted.
Currently, the internal ACL is limited to a maximum of 16 entries.
For example:
int ret = keyctl_grant_permission(key, KEY_ACE_SUBJ_STANDARD, KEY_ACE_OWNER, KEY_ACE_VIEW | KEY_ACE_READ);
---
include/uapi/linux/keyctl.h | 1 security/keys/compat.c | 2 + security/keys/internal.h | 5 ++ security/keys/keyctl.c | 5 ++ security/keys/permission.c | 119 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 132 insertions(+)
include/uapi/linux/keyctl.h +1 -0
@@ -131,6 +131,7 @@ enum key_ace_standard_subject {#define KEYCTL_PKEY_VERIFY 28/* Verify a public key signature */ #define KEYCTL_RESTRICT_KEYRING 29/* Restrict keys allowed to link to a keyring */ #define KEYCTL_MOVE 30/* Move keys between keyrings */ +#define KEYCTL_GRANT_PERMISSION 31/* Grant a permit to a key */ /* keyctl structures */ struct keyctl_dh_params {
security/keys/compat.c +2 -0
@@ -161,6 +161,8 @@ COMPAT_SYSCALL_DEFINE5(keyctl, u32, option,case KEYCTL_MOVE :return keyctl_keyring_move (arg2, arg3, arg4, arg5); +case KEYCTL_GRANT_PERMISSION : +return keyctl_grant_permission (arg2, arg3, arg4, arg5);default :return -EOPNOTSUPP ;
security/keys/internal.h +5 -0
@@ -336,6 +336,11 @@ static inline long keyctl_pkey_e_d_s(int op, }#endif +extern long keyctl_grant_permission (key_serial_t keyid, +enum key_ace_subject_type type, +unsigned int subject, +unsigned int perm); +/* * Debugging key validation */
security/keys/keyctl.c +5 -0
@@ -1860,6 +1860,11 @@ SYSCALL_DEFINE5(keyctl, int, option, unsigned long, arg2, unsigned long, arg3, (key_serial_t )arg3, (key_serial_t )arg4, (unsigned int)arg5); +case KEYCTL_GRANT_PERMISSION : +return keyctl_grant_permission ((key_serial_t )arg2, + (enum key_ace_subject_type )arg3, + (unsigned int )arg4, + (unsigned int )arg5);default :return -EOPNOTSUPP ;
security/keys/permission.c +119 -0
122 lines not on this page · raw message
Eric Biggers
maintainerRe: [PATCH 2/2] KEYS: Provide KEYCTL_GRANT_PERMISSION
Quoted 42 lines · David Howells
Provide a
keyctl()operation to grant/remove permissions. The grant operation, wrapped by libkeyutils, looks like:int ret = keyctl_grant_permission(key_serial_t key,
enumkey_ace_subject_typetype, unsigned int subject, unsigned int perm);Where key is the key to be modified, type and subject represent the subject to which permission is to be granted (or removed) and perm is the set of permissions to be granted. 0 is returned on success.
SET_SECURITYpermission is required for this.The subject type currently must be
KEY_ACE_SUBJ_STANDARDfor the moment (other subject types will come along later).For subject type
KEY_ACE_SUBJ_STANDARD, the following subject values are available:
KEY_ACE_POSSESSORThe possessor of the key
KEY_ACE_OWNERThe owner of the key
KEY_ACE_GROUPThe key's group
KEY_ACE_EVERYONEEveryoneperm lists the permissions to be granted:
KEY_ACE_VIEWCan view the key metadata
KEY_ACE_READCan read the key content
KEY_ACE_WRITECan update/modify the key content
KEY_ACE_SEARCHCan find the key by searching/requesting
KEY_ACE_LINKCan make a link to the key
KEY_ACE_SET_SECURITYCan set security
KEY_ACE_INVALCan invalidate
KEY_ACE_REVOKECan revoke
KEY_ACE_JOINCan join this keyring
KEY_ACE_CLEARCan clear this keyringIf an ACE already exists for the subject, then the permissions mask will be overwritten; if perm is 0, it will be deleted.
Currently, the internal ACL is limited to a maximum of 16 entries.
Quoted 8 lines
For example:
int ret = keyctl_grant_permission(key, KEY_ACE_SUBJ_STANDARD, KEY_ACE_OWNER, KEY_ACE_VIEW | KEY_ACE_READ);Signed-off-by David Howells <[email protected]>
Where is the documentation and tests for this? I want to add syzkaller definitions for this, but there is no documentation (a commit message doesn't count). I checked the 'next' branch of keyutils as well.
How is anyone supposed to use this if there is no documentation?
- Eric