aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Howells <dhowells@redhat.com>2005-09-28 12:03:15 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2005-09-28 12:10:47 -0400
commit664cceb0093b755739e56572b836a99104ee8a75 (patch)
treedbaa3ab802803879f29532db4d8a91a54294cf88 /Documentation
parent5134fc15b643dc36eb9aa77e4318b886844a9ac5 (diff)
[PATCH] Keys: Add possessor permissions to keys [try #3]
The attached patch adds extra permission grants to keys for the possessor of a key in addition to the owner, group and other permissions bits. This makes SUID binaries easier to support without going as far as labelling keys and key targets using the LSM facilities. This patch adds a second "pointer type" to key structures (struct key_ref *) that can have the bottom bit of the address set to indicate the possession of a key. This is propagated through searches from the keyring to the discovered key. It has been made a separate type so that the compiler can spot attempts to dereference a potentially incorrect pointer. The "possession" attribute can't be attached to a key structure directly as it's not an intrinsic property of a key. Pointers to keys have been replaced with struct key_ref *'s wherever possession information needs to be passed through. This does assume that the bottom bit of the pointer will always be zero on return from kmem_cache_alloc(). The key reference type has been made into a typedef so that at least it can be located in the sources, even though it's basically a pointer to an undefined type. I've also renamed the accessor functions to be more useful, and all reference variables should now end in "_ref". Signed-Off-By: David Howells <dhowells@redhat.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/keys.txt74
1 files changed, 55 insertions, 19 deletions
diff --git a/Documentation/keys.txt b/Documentation/keys.txt
index 0321ded4b9ae..b22e7c8d059a 100644
--- a/Documentation/keys.txt
+++ b/Documentation/keys.txt
@@ -195,8 +195,8 @@ KEY ACCESS PERMISSIONS
195====================== 195======================
196 196
197Keys have an owner user ID, a group access ID, and a permissions mask. The mask 197Keys have an owner user ID, a group access ID, and a permissions mask. The mask
198has up to eight bits each for user, group and other access. Only five of each 198has up to eight bits each for possessor, user, group and other access. Only
199set of eight bits are defined. These permissions granted are: 199five of each set of eight bits are defined. These permissions granted are:
200 200
201 (*) View 201 (*) View
202 202
@@ -241,16 +241,16 @@ about the status of the key service:
241 type, description and permissions. The payload of the key is not available 241 type, description and permissions. The payload of the key is not available
242 this way: 242 this way:
243 243
244 SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY 244 SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY
245 00000001 I----- 39 perm 1f0000 0 0 keyring _uid_ses.0: 1/4 245 00000001 I----- 39 perm 1f1f0000 0 0 keyring _uid_ses.0: 1/4
246 00000002 I----- 2 perm 1f0000 0 0 keyring _uid.0: empty 246 00000002 I----- 2 perm 1f1f0000 0 0 keyring _uid.0: empty
247 00000007 I----- 1 perm 1f0000 0 0 keyring _pid.1: empty 247 00000007 I----- 1 perm 1f1f0000 0 0 keyring _pid.1: empty
248 0000018d I----- 1 perm 1f0000 0 0 keyring _pid.412: empty 248 0000018d I----- 1 perm 1f1f0000 0 0 keyring _pid.412: empty
249 000004d2 I--Q-- 1 perm 1f0000 32 -1 keyring _uid.32: 1/4 249 000004d2 I--Q-- 1 perm 1f1f0000 32 -1 keyring _uid.32: 1/4
250 000004d3 I--Q-- 3 perm 1f0000 32 -1 keyring _uid_ses.32: empty 250 000004d3 I--Q-- 3 perm 1f1f0000 32 -1 keyring _uid_ses.32: empty
251 00000892 I--QU- 1 perm 1f0000 0 0 user metal:copper: 0 251 00000892 I--QU- 1 perm 1f000000 0 0 user metal:copper: 0
252 00000893 I--Q-N 1 35s 1f0000 0 0 user metal:silver: 0 252 00000893 I--Q-N 1 35s 1f1f0000 0 0 user metal:silver: 0
253 00000894 I--Q-- 1 10h 1f0000 0 0 user metal:gold: 0 253 00000894 I--Q-- 1 10h 001f0000 0 0 user metal:gold: 0
254 254
255 The flags are: 255 The flags are:
256 256
@@ -637,6 +637,34 @@ call, and the key released upon close. How to deal with conflicting keys due to
637two different users opening the same file is left to the filesystem author to 637two different users opening the same file is left to the filesystem author to
638solve. 638solve.
639 639
640Note that there are two different types of pointers to keys that may be
641encountered:
642
643 (*) struct key *
644
645 This simply points to the key structure itself. Key structures will be at
646 least four-byte aligned.
647
648 (*) key_ref_t
649
650 This is equivalent to a struct key *, but the least significant bit is set
651 if the caller "possesses" the key. By "possession" it is meant that the
652 calling processes has a searchable link to the key from one of its
653 keyrings. There are three functions for dealing with these:
654
655 key_ref_t make_key_ref(const struct key *key,
656 unsigned long possession);
657
658 struct key *key_ref_to_ptr(const key_ref_t key_ref);
659
660 unsigned long is_key_possessed(const key_ref_t key_ref);
661
662 The first function constructs a key reference from a key pointer and
663 possession information (which must be 0 or 1 and not any other value).
664
665 The second function retrieves the key pointer from a reference and the
666 third retrieves the possession flag.
667
640When accessing a key's payload contents, certain precautions must be taken to 668When accessing a key's payload contents, certain precautions must be taken to
641prevent access vs modification races. See the section "Notes on accessing 669prevent access vs modification races. See the section "Notes on accessing
642payload contents" for more information. 670payload contents" for more information.
@@ -665,7 +693,11 @@ payload contents" for more information.
665 693
666 void key_put(struct key *key); 694 void key_put(struct key *key);
667 695
668 This can be called from interrupt context. If CONFIG_KEYS is not set then 696 Or:
697
698 void key_ref_put(key_ref_t key_ref);
699
700 These can be called from interrupt context. If CONFIG_KEYS is not set then
669 the argument will not be parsed. 701 the argument will not be parsed.
670 702
671 703
@@ -689,13 +721,17 @@ payload contents" for more information.
689 721
690(*) If a keyring was found in the search, this can be further searched by: 722(*) If a keyring was found in the search, this can be further searched by:
691 723
692 struct key *keyring_search(struct key *keyring, 724 key_ref_t keyring_search(key_ref_t keyring_ref,
693 const struct key_type *type, 725 const struct key_type *type,
694 const char *description) 726 const char *description)
695 727
696 This searches the keyring tree specified for a matching key. Error ENOKEY 728 This searches the keyring tree specified for a matching key. Error ENOKEY
697 is returned upon failure. If successful, the returned key will need to be 729 is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful,
698 released. 730 the returned key will need to be released.
731
732 The possession attribute from the keyring reference is used to control
733 access through the permissions mask and is propagated to the returned key
734 reference pointer if successful.
699 735
700 736
701(*) To check the validity of a key, this function can be called: 737(*) To check the validity of a key, this function can be called:
@@ -732,7 +768,7 @@ More complex payload contents must be allocated and a pointer to them set in
732key->payload.data. One of the following ways must be selected to access the 768key->payload.data. One of the following ways must be selected to access the
733data: 769data:
734 770
735 (1) Unmodifyable key type. 771 (1) Unmodifiable key type.
736 772
737 If the key type does not have a modify method, then the key's payload can 773 If the key type does not have a modify method, then the key's payload can
738 be accessed without any form of locking, provided that it's known to be 774 be accessed without any form of locking, provided that it's known to be