+7 -6

security/keys/compat.c

reviewed

··· 1 1 - /* compat.c: 32-bit compatibility syscall for 64-bit systems 1 1 + /* 32-bit compatibility syscall for 64-bit systems 2 2 * 3 3 * Copyright (C) 2004-5 Red Hat, Inc. All Rights Reserved. 4 4 * Written by David Howells (dhowells@redhat.com) ··· 15 15 #include "internal.h" 16 16 17 17 /* 18 18 - * the key control system call, 32-bit compatibility version for 64-bit archs 19 19 - * - this should only be called if the 64-bit arch uses weird pointers in 20 20 - * 32-bit mode or doesn't guarantee that the top 32-bits of the argument 21 21 - * registers on taking a 32-bit syscall are zero 22 22 - * - if you can, you should call sys_keyctl directly 18 18 + * The key control system call, 32-bit compatibility version for 64-bit archs 19 19 + * 20 20 + * This should only be called if the 64-bit arch uses weird pointers in 32-bit 21 21 + * mode or doesn't guarantee that the top 32-bits of the argument registers on 22 22 + * taking a 32-bit syscall are zero. If you can, you should call sys_keyctl() 23 23 + * directly. 23 24 */ 24 25 asmlinkage long compat_sys_keyctl(u32 option, 25 26 u32 arg2, u32 arg3, u32 arg4, u32 arg5)

+7 -7

security/keys/gc.c

reviewed

··· 32 32 static time_t key_gc_new_timer; 33 33 34 34 /* 35 35 - * Schedule a garbage collection run 36 36 - * - precision isn't particularly important 35 35 + * Schedule a garbage collection run. 36 36 + * - time precision isn't particularly important 37 37 */ 38 38 void key_schedule_gc(time_t gc_at) 39 39 { ··· 61 61 } 62 62 63 63 /* 64 64 - * Garbage collect pointers from a keyring 65 65 - * - return true if we altered the keyring 64 64 + * Garbage collect pointers from a keyring. 65 65 + * 66 66 + * Return true if we altered the keyring. 66 67 */ 67 68 static bool key_gc_keyring(struct key *keyring, time_t limit) 68 69 __releases(key_serial_lock) ··· 108 107 } 109 108 110 109 /* 111 111 - * Garbage collector for keys 112 112 - * - this involves scanning the keyrings for dead, expired and revoked keys 113 113 - * that have overstayed their welcome 110 110 + * Garbage collector for keys. This involves scanning the keyrings for dead, 111 111 + * expired and revoked keys that have overstayed their welcome 114 112 */ 115 113 static void key_garbage_collector(struct work_struct *work) 116 114 {

+14 -12

security/keys/internal.h

reviewed

··· 1 1 - /* internal.h: authentication token and access key management internal defs 1 1 + /* Authentication token and access key management internal defs 2 2 * 3 3 * Copyright (C) 2003-5, 2007 Red Hat, Inc. All Rights Reserved. 4 4 * Written by David Howells (dhowells@redhat.com) ··· 35 35 36 36 /*****************************************************************************/ 37 37 /* 38 38 - * keep track of keys for a user 39 39 - * - this needs to be separate to user_struct to avoid a refcount-loop 40 40 - * (user_struct pins some keyrings which pin this struct) 41 41 - * - this also keeps track of keys under request from userspace for this UID 38 38 + * Keep track of keys for a user. 39 39 + * 40 40 + * This needs to be separate to user_struct to avoid a refcount-loop 41 41 + * (user_struct pins some keyrings which pin this struct). 42 42 + * 43 43 + * We also keep track of keys under request from userspace for this UID here. 42 44 */ 43 45 struct key_user { 44 46 struct rb_node node; ··· 64 62 extern void key_user_put(struct key_user *user); 65 63 66 64 /* 67 67 - * key quota limits 65 65 + * Key quota limits. 68 66 * - root has its own separate limits to everyone else 69 67 */ 70 68 extern unsigned key_quota_root_maxkeys; ··· 148 146 extern void keyring_gc(struct key *keyring, time_t limit); 149 147 extern void key_schedule_gc(time_t expiry_at); 150 148 151 151 - /* 152 152 - * check to see whether permission is granted to use a key in the desired way 153 153 - */ 154 149 extern int key_task_permission(const key_ref_t key_ref, 155 150 const struct cred *cred, 156 151 key_perm_t perm); 157 152 153 153 + /* 154 154 + * Check to see whether permission is granted to use a key in the desired way. 155 155 + */ 158 156 static inline int key_permission(const key_ref_t key_ref, key_perm_t perm) 159 157 { 160 158 return key_task_permission(key_ref, current_cred(), perm); ··· 170 168 #define KEY_ALL 0x3f /* all the above permissions */ 171 169 172 170 /* 173 173 - * request_key authorisation 171 171 + * Authorisation record for request_key(). 174 172 */ 175 173 struct request_key_auth { 176 174 struct key *target_key; ··· 190 188 extern struct key *key_get_instantiation_authkey(key_serial_t target_id); 191 189 192 190 /* 193 193 - * keyctl functions 191 191 + * keyctl() functions 194 192 */ 195 193 extern long keyctl_get_keyring_ID(key_serial_t, int); 196 194 extern long keyctl_join_session_keyring(const char __user *); ··· 216 214 extern long keyctl_session_to_parent(void); 217 215 218 216 /* 219 219 - * debugging key validation 217 217 + * Debugging key validation 220 218 */ 221 219 #ifdef KEY_DEBUGGING 222 220 extern void __key_check(const struct key *);

+173 -67

security/keys/key.c

reviewed

··· 39 39 static void key_cleanup(struct work_struct *work); 40 40 static DECLARE_WORK(key_cleanup_task, key_cleanup); 41 41 42 42 - /* we serialise key instantiation and link */ 42 42 + /* We serialise key instantiation and link */ 43 43 DEFINE_MUTEX(key_construction_mutex); 44 44 45 45 - /* any key who's type gets unegistered will be re-typed to this */ 45 45 + /* Any key who's type gets unegistered will be re-typed to this */ 46 46 static struct key_type key_type_dead = { 47 47 .name = "dead", 48 48 }; ··· 57 57 #endif 58 58 59 59 /* 60 60 - * get the key quota record for a user, allocating a new record if one doesn't 61 61 - * already exist 60 60 + * Get the key quota record for a user, allocating a new record if one doesn't 61 61 + * already exist. 62 62 */ 63 63 struct key_user *key_user_lookup(uid_t uid, struct user_namespace *user_ns) 64 64 { ··· 66 66 struct rb_node *parent = NULL; 67 67 struct rb_node **p; 68 68 69 69 - try_again: 69 69 + try_again: 70 70 p = &key_user_tree.rb_node; 71 71 spin_lock(&key_user_lock); 72 72 ··· 123 123 goto out; 124 124 125 125 /* okay - we found a user record for this UID */ 126 126 - found: 126 126 + found: 127 127 atomic_inc(&user->usage); 128 128 spin_unlock(&key_user_lock); 129 129 kfree(candidate); 130 130 - out: 130 130 + out: 131 131 return user; 132 132 } 133 133 134 134 /* 135 135 - * dispose of a user structure 135 135 + * Dispose of a user structure 136 136 */ 137 137 void key_user_put(struct key_user *user) 138 138 { ··· 146 146 } 147 147 148 148 /* 149 149 - * assign a key the next unique serial number 150 150 - * - these are assigned randomly to avoid security issues through covert 151 151 - * channel problems 149 149 + * Allocate a serial number for a key. These are assigned randomly to avoid 150 150 + * security issues through covert channel problems. 152 151 */ 153 152 static inline void key_alloc_serial(struct key *key) 154 153 { ··· 207 208 } 208 209 } 209 210 210 210 - /* 211 211 - * allocate a key of the specified type 212 212 - * - update the user's quota to reflect the existence of the key 213 213 - * - called from a key-type operation with key_types_sem read-locked by 214 214 - * key_create_or_update() 215 215 - * - this prevents unregistration of the key type 216 216 - * - upon return the key is as yet uninstantiated; the caller needs to either 217 217 - * instantiate the key or discard it before returning 211 211 + /** 212 212 + * key_alloc - Allocate a key of the specified type. 213 213 + * @type: The type of key to allocate. 214 214 + * @desc: The key description to allow the key to be searched out. 215 215 + * @uid: The owner of the new key. 216 216 + * @gid: The group ID for the new key's group permissions. 217 217 + * @cred: The credentials specifying UID namespace. 218 218 + * @perm: The permissions mask of the new key. 219 219 + * @flags: Flags specifying quota properties. 220 220 + * 221 221 + * Allocate a key of the specified type with the attributes given. The key is 222 222 + * returned in an uninstantiated state and the caller needs to instantiate the 223 223 + * key before returning. 224 224 + * 225 225 + * The user's key count quota is updated to reflect the creation of the key and 226 226 + * the user's key data quota has the default for the key type reserved. The 227 227 + * instantiation function should amend this as necessary. If insufficient 228 228 + * quota is available, -EDQUOT will be returned. 229 229 + * 230 230 + * The LSM security modules can prevent a key being created, in which case 231 231 + * -EACCES will be returned. 232 232 + * 233 233 + * Returns a pointer to the new key if successful and an error code otherwise. 234 234 + * 235 235 + * Note that the caller needs to ensure the key type isn't uninstantiated. 236 236 + * Internally this can be done by locking key_types_sem. Externally, this can 237 237 + * be done by either never unregistering the key type, or making sure 238 238 + * key_alloc() calls don't race with module unloading. 218 239 */ 219 240 struct key *key_alloc(struct key_type *type, const char *desc, 220 241 uid_t uid, gid_t gid, const struct cred *cred, ··· 357 338 key = ERR_PTR(-EDQUOT); 358 339 goto error; 359 340 } 360 360 - 361 341 EXPORT_SYMBOL(key_alloc); 362 342 363 363 - /* 364 364 - * reserve an amount of quota for the key's payload 343 343 + /** 344 344 + * key_payload_reserve - Adjust data quota reservation for the key's payload 345 345 + * @key: The key to make the reservation for. 346 346 + * @datalen: The amount of data payload the caller now wants. 347 347 + * 348 348 + * Adjust the amount of the owning user's key data quota that a key reserves. 349 349 + * If the amount is increased, then -EDQUOT may be returned if there isn't 350 350 + * enough free quota available. 351 351 + * 352 352 + * If successful, 0 is returned. 365 353 */ 366 354 int key_payload_reserve(struct key *key, size_t datalen) 367 355 { ··· 402 376 403 377 return ret; 404 378 } 405 405 - 406 379 EXPORT_SYMBOL(key_payload_reserve); 407 380 408 381 /* 409 409 - * instantiate a key and link it into the target keyring atomically 410 410 - * - called with the target keyring's semaphore writelocked 382 382 + * Instantiate a key and link it into the target keyring atomically. Must be 383 383 + * called with the target keyring's semaphore writelocked. The target key's 384 384 + * semaphore need not be locked as instantiation is serialised by 385 385 + * key_construction_mutex. 411 386 */ 412 387 static int __key_instantiate_and_link(struct key *key, 413 388 const void *data, ··· 459 432 return ret; 460 433 } 461 434 462 462 - /* 463 463 - * instantiate a key and link it into the target keyring atomically 435 435 + /** 436 436 + * key_instantiate_and_link - Instantiate a key and link it into the keyring. 437 437 + * @key: The key to instantiate. 438 438 + * @data: The data to use to instantiate the keyring. 439 439 + * @datalen: The length of @data. 440 440 + * @keyring: Keyring to create a link in on success (or NULL). 441 441 + * @authkey: The authorisation token permitting instantiation. 442 442 + * 443 443 + * Instantiate a key that's in the uninstantiated state using the provided data 444 444 + * and, if successful, link it in to the destination keyring if one is 445 445 + * supplied. 446 446 + * 447 447 + * If successful, 0 is returned, the authorisation token is revoked and anyone 448 448 + * waiting for the key is woken up. If the key was already instantiated, 449 449 + * -EBUSY will be returned. 464 450 */ 465 451 int key_instantiate_and_link(struct key *key, 466 452 const void *data, ··· 502 462 503 463 EXPORT_SYMBOL(key_instantiate_and_link); 504 464 505 505 - /* 506 506 - * negatively instantiate a key and link it into the target keyring atomically 465 465 + /** 466 466 + * key_negate_and_link - Negatively instantiate a key and link it into the keyring. 467 467 + * @key: The key to instantiate. 468 468 + * @timeout: The timeout on the negative key. 469 469 + * @keyring: Keyring to create a link in on success (or NULL). 470 470 + * @authkey: The authorisation token permitting instantiation. 471 471 + * 472 472 + * Negatively instantiate a key that's in the uninstantiated state and, if 473 473 + * successful, set its timeout and link it in to the destination keyring if one 474 474 + * is supplied. The key and any links to the key will be automatically garbage 475 475 + * collected after the timeout expires. 476 476 + * 477 477 + * Negative keys are used to rate limit repeated request_key() calls by causing 478 478 + * them to return -ENOKEY until the negative key expires. 479 479 + * 480 480 + * If successful, 0 is returned, the authorisation token is revoked and anyone 481 481 + * waiting for the key is woken up. If the key was already instantiated, 482 482 + * -EBUSY will be returned. 507 483 */ 508 484 int key_negate_and_link(struct key *key, 509 485 unsigned timeout, ··· 581 525 EXPORT_SYMBOL(key_negate_and_link); 582 526 583 527 /* 584 584 - * do cleaning up in process context so that we don't have to disable 585 585 - * interrupts all over the place 528 528 + * Garbage collect keys in process context so that we don't have to disable 529 529 + * interrupts all over the place. 530 530 + * 531 531 + * key_put() schedules this rather than trying to do the cleanup itself, which 532 532 + * means key_put() doesn't have to sleep. 586 533 */ 587 534 static void key_cleanup(struct work_struct *work) 588 535 { 589 536 struct rb_node *_n; 590 537 struct key *key; 591 538 592 592 - go_again: 539 539 + go_again: 593 540 /* look for a dead key in the tree */ 594 541 spin_lock(&key_serial_lock); 595 542 ··· 606 547 spin_unlock(&key_serial_lock); 607 548 return; 608 549 609 609 - found_dead_key: 550 550 + found_dead_key: 610 551 /* we found a dead key - once we've removed it from the tree, we can 611 552 * drop the lock */ 612 553 rb_erase(&key->serial_node, &key_serial_tree); ··· 645 586 goto go_again; 646 587 } 647 588 648 648 - /* 649 649 - * dispose of a reference to a key 650 650 - * - when all the references are gone, we schedule the cleanup task to come and 651 651 - * pull it out of the tree in definite process context 589 589 + /** 590 590 + * key_put - Discard a reference to a key. 591 591 + * @key: The key to discard a reference from. 592 592 + * 593 593 + * Discard a reference to a key, and when all the references are gone, we 594 594 + * schedule the cleanup task to come and pull it out of the tree in process 595 595 + * context at some later time. 652 596 */ 653 597 void key_put(struct key *key) 654 598 { ··· 662 600 schedule_work(&key_cleanup_task); 663 601 } 664 602 } 665 665 - 666 603 EXPORT_SYMBOL(key_put); 667 604 668 605 /* 669 669 - * find a key by its serial number 606 606 + * Find a key by its serial number. 670 607 */ 671 608 struct key *key_lookup(key_serial_t id) 672 609 { ··· 687 626 goto found; 688 627 } 689 628 690 690 - not_found: 629 629 + not_found: 691 630 key = ERR_PTR(-ENOKEY); 692 631 goto error; 693 632 694 694 - found: 633 633 + found: 695 634 /* pretend it doesn't exist if it is awaiting deletion */ 696 635 if (atomic_read(&key->usage) == 0) 697 636 goto not_found; ··· 701 640 */ 702 641 atomic_inc(&key->usage); 703 642 704 704 - error: 643 643 + error: 705 644 spin_unlock(&key_serial_lock); 706 645 return key; 707 646 } 708 647 709 648 /* 710 710 - * find and lock the specified key type against removal 711 711 - * - we return with the sem readlocked 649 649 + * Find and lock the specified key type against removal. 650 650 + * 651 651 + * We return with the sem read-locked if successful. If the type wasn't 652 652 + * available -ENOKEY is returned instead. 712 653 */ 713 654 struct key_type *key_type_lookup(const char *type) 714 655 { ··· 728 665 up_read(&key_types_sem); 729 666 ktype = ERR_PTR(-ENOKEY); 730 667 731 731 - found_kernel_type: 668 668 + found_kernel_type: 732 669 return ktype; 733 670 } 734 671 735 672 /* 736 736 - * unlock a key type 673 673 + * Unlock a key type locked by key_type_lookup(). 737 674 */ 738 675 void key_type_put(struct key_type *ktype) 739 676 { ··· 741 678 } 742 679 743 680 /* 744 744 - * attempt to update an existing key 745 745 - * - the key has an incremented refcount 746 746 - * - we need to put the key if we get an error 681 681 + * Attempt to update an existing key. 682 682 + * 683 683 + * The key is given to us with an incremented refcount that we need to discard 684 684 + * if we get an error. 747 685 */ 748 686 static inline key_ref_t __key_update(key_ref_t key_ref, 749 687 const void *payload, size_t plen) ··· 781 717 goto out; 782 718 } 783 719 784 784 - /* 785 785 - * search the specified keyring for a key of the same description; if one is 786 786 - * found, update it, otherwise add a new one 720 720 + /** 721 721 + * key_create_or_update - Update or create and instantiate a key. 722 722 + * @keyring_ref: A pointer to the destination keyring with possession flag. 723 723 + * @type: The type of key. 724 724 + * @description: The searchable description for the key. 725 725 + * @payload: The data to use to instantiate or update the key. 726 726 + * @plen: The length of @payload. 727 727 + * @perm: The permissions mask for a new key. 728 728 + * @flags: The quota flags for a new key. 729 729 + * 730 730 + * Search the destination keyring for a key of the same description and if one 731 731 + * is found, update it, otherwise create and instantiate a new one and create a 732 732 + * link to it from that keyring. 733 733 + * 734 734 + * If perm is KEY_PERM_UNDEF then an appropriate key permissions mask will be 735 735 + * concocted. 736 736 + * 737 737 + * Returns a pointer to the new key if successful, -ENODEV if the key type 738 738 + * wasn't available, -ENOTDIR if the keyring wasn't a keyring, -EACCES if the 739 739 + * caller isn't permitted to modify the keyring or the LSM did not permit 740 740 + * creation of the key. 741 741 + * 742 742 + * On success, the possession flag from the keyring ref will be tacked on to 743 743 + * the key ref before it is returned. 787 744 */ 788 745 key_ref_t key_create_or_update(key_ref_t keyring_ref, 789 746 const char *type, ··· 912 827 key_ref = __key_update(key_ref, payload, plen); 913 828 goto error; 914 829 } 915 915 - 916 830 EXPORT_SYMBOL(key_create_or_update); 917 831 918 918 - /* 919 919 - * update a key 832 832 + /** 833 833 + * key_update - Update a key's contents. 834 834 + * @key_ref: The pointer (plus possession flag) to the key. 835 835 + * @payload: The data to be used to update the key. 836 836 + * @plen: The length of @payload. 837 837 + * 838 838 + * Attempt to update the contents of a key with the given payload data. The 839 839 + * caller must be granted Write permission on the key. Negative keys can be 840 840 + * instantiated by this method. 841 841 + * 842 842 + * Returns 0 on success, -EACCES if not permitted and -EOPNOTSUPP if the key 843 843 + * type does not support updating. The key type may return other errors. 920 844 */ 921 845 int key_update(key_ref_t key_ref, const void *payload, size_t plen) 922 846 { ··· 955 861 error: 956 862 return ret; 957 863 } 958 958 - 959 864 EXPORT_SYMBOL(key_update); 960 865 961 961 - /* 962 962 - * revoke a key 866 866 + /** 867 867 + * key_revoke - Revoke a key. 868 868 + * @key: The key to be revoked. 869 869 + * 870 870 + * Mark a key as being revoked and ask the type to free up its resources. The 871 871 + * revocation timeout is set and the key and all its links will be 872 872 + * automatically garbage collected after key_gc_delay amount of time if they 873 873 + * are not manually dealt with first. 963 874 */ 964 875 void key_revoke(struct key *key) 965 876 { ··· 993 894 994 895 up_write(&key->sem); 995 896 } 996 996 - 997 897 EXPORT_SYMBOL(key_revoke); 998 898 999 999 - /* 1000 1000 - * register a type of key 899 899 + /** 900 900 + * register_key_type - Register a type of key. 901 901 + * @ktype: The new key type. 902 902 + * 903 903 + * Register a new key type. 904 904 + * 905 905 + * Returns 0 on success or -EEXIST if a type of this name already exists. 1001 906 */ 1002 907 int register_key_type(struct key_type *ktype) 1003 908 { ··· 1021 918 list_add(&ktype->link, &key_types_list); 1022 919 ret = 0; 1023 920 1024 1024 - out: 921 921 + out: 1025 922 up_write(&key_types_sem); 1026 923 return ret; 1027 924 } 1028 1028 - 1029 925 EXPORT_SYMBOL(register_key_type); 1030 926 1031 1031 - /* 1032 1032 - * unregister a type of key 927 927 + /** 928 928 + * unregister_key_type - Unregister a type of key. 929 929 + * @ktype: The key type. 930 930 + * 931 931 + * Unregister a key type and mark all the extant keys of this type as dead. 932 932 + * Those keys of this type are then destroyed to get rid of their payloads and 933 933 + * they and their links will be garbage collected as soon as possible. 1033 934 */ 1034 935 void unregister_key_type(struct key_type *ktype) 1035 936 { ··· 1081 974 1082 975 key_schedule_gc(0); 1083 976 } 1084 1084 - 1085 977 EXPORT_SYMBOL(unregister_key_type); 1086 978 1087 979 /* 1088 1088 - * initialise the key management stuff 980 980 + * Initialise the key management state. 1089 981 */ 1090 982 void __init key_init(void) 1091 983 {

+186 -92

security/keys/keyctl.c

reviewed

··· 1 1 - /* keyctl.c: userspace keyctl operations 1 1 + /* Userspace key control operations 2 2 * 3 3 * Copyright (C) 2004-5 Red Hat, Inc. All Rights Reserved. 4 4 * Written by David Howells (dhowells@redhat.com) ··· 31 31 int ret; 32 32 33 33 ret = strncpy_from_user(type, _type, len); 34 34 - 35 34 if (ret < 0) 36 35 return ret; 37 37 - 38 36 if (ret == 0 || ret >= len) 39 37 return -EINVAL; 40 40 - 41 38 if (type[0] == '.') 42 39 return -EPERM; 43 43 - 44 40 type[len - 1] = '\0'; 45 45 - 46 41 return 0; 47 42 } 48 43 49 44 /* 50 50 - * extract the description of a new key from userspace and either add it as a 51 51 - * new key to the specified keyring or update a matching key in that keyring 52 52 - * - the keyring must be writable 53 53 - * - returns the new key's serial number 54 54 - * - implements add_key() 45 45 + * Extract the description of a new key from userspace and either add it as a 46 46 + * new key to the specified keyring or update a matching key in that keyring. 47 47 + * 48 48 + * The keyring must be writable so that we can attach the key to it. 49 49 + * 50 50 + * If successful, the new key's serial number is returned, otherwise an error 51 51 + * code is returned. 55 52 */ 56 53 SYSCALL_DEFINE5(add_key, const char __user *, _type, 57 54 const char __user *, _description, ··· 131 134 } 132 135 133 136 /* 134 134 - * search the process keyrings for a matching key 135 135 - * - nested keyrings may also be searched if they have Search permission 136 136 - * - if a key is found, it will be attached to the destination keyring if 137 137 - * there's one specified 138 138 - * - /sbin/request-key will be invoked if _callout_info is non-NULL 139 139 - * - the _callout_info string will be passed to /sbin/request-key 140 140 - * - if the _callout_info string is empty, it will be rendered as "-" 141 141 - * - implements request_key() 137 137 + * Search the process keyrings and keyring trees linked from those for a 138 138 + * matching key. Keyrings must have appropriate Search permission to be 139 139 + * searched. 140 140 + * 141 141 + * If a key is found, it will be attached to the destination keyring if there's 142 142 + * one specified and the serial number of the key will be returned. 143 143 + * 144 144 + * If no key is found, /sbin/request-key will be invoked if _callout_info is 145 145 + * non-NULL in an attempt to create a key. The _callout_info string will be 146 146 + * passed to /sbin/request-key to aid with completing the request. If the 147 147 + * _callout_info string is "" then it will be changed to "-". 142 148 */ 143 149 SYSCALL_DEFINE4(request_key, const char __user *, _type, 144 150 const char __user *, _description, ··· 222 222 } 223 223 224 224 /* 225 225 - * get the ID of the specified process keyring 226 226 - * - the keyring must have search permission to be found 227 227 - * - implements keyctl(KEYCTL_GET_KEYRING_ID) 225 225 + * Get the ID of the specified process keyring. 226 226 + * 227 227 + * The requested keyring must have search permission to be found. 228 228 + * 229 229 + * If successful, the ID of the requested keyring will be returned. 228 230 */ 229 231 long keyctl_get_keyring_ID(key_serial_t id, int create) 230 232 { ··· 245 243 key_ref_put(key_ref); 246 244 error: 247 245 return ret; 248 248 - 249 249 - } /* end keyctl_get_keyring_ID() */ 246 246 + } 250 247 251 248 /* 252 252 - * join the session keyring 253 253 - * - implements keyctl(KEYCTL_JOIN_SESSION_KEYRING) 249 249 + * Join a (named) session keyring. 250 250 + * 251 251 + * Create and join an anonymous session keyring or join a named session 252 252 + * keyring, creating it if necessary. A named session keyring must have Search 253 253 + * permission for it to be joined. Session keyrings without this permit will 254 254 + * be skipped over. 255 255 + * 256 256 + * If successful, the ID of the joined session keyring will be returned. 254 257 */ 255 258 long keyctl_join_session_keyring(const char __user *_name) 256 259 { ··· 281 274 } 282 275 283 276 /* 284 284 - * update a key's data payload 285 285 - * - the key must be writable 286 286 - * - implements keyctl(KEYCTL_UPDATE) 277 277 + * Update a key's data payload from the given data. 278 278 + * 279 279 + * The key must grant the caller Write permission and the key type must support 280 280 + * updating for this to work. A negative key can be positively instantiated 281 281 + * with this call. 282 282 + * 283 283 + * If successful, 0 will be returned. If the key type does not support 284 284 + * updating, then -EOPNOTSUPP will be returned. 287 285 */ 288 286 long keyctl_update_key(key_serial_t id, 289 287 const void __user *_payload, ··· 333 321 } 334 322 335 323 /* 336 336 - * revoke a key 337 337 - * - the key must be writable 338 338 - * - implements keyctl(KEYCTL_REVOKE) 324 324 + * Revoke a key. 325 325 + * 326 326 + * The key must be grant the caller Write or Setattr permission for this to 327 327 + * work. The key type should give up its quota claim when revoked. The key 328 328 + * and any links to the key will be automatically garbage collected after a 329 329 + * certain amount of time (/proc/sys/kernel/keys/gc_delay). 330 330 + * 331 331 + * If successful, 0 is returned. 339 332 */ 340 333 long keyctl_revoke_key(key_serial_t id) 341 334 { ··· 368 351 } 369 352 370 353 /* 371 371 - * clear the specified process keyring 372 372 - * - the keyring must be writable 373 373 - * - implements keyctl(KEYCTL_CLEAR) 354 354 + * Clear the specified keyring, creating an empty process keyring if one of the 355 355 + * special keyring IDs is used. 356 356 + * 357 357 + * The keyring must grant the caller Write permission for this to work. If 358 358 + * successful, 0 will be returned. 374 359 */ 375 360 long keyctl_keyring_clear(key_serial_t ringid) 376 361 { ··· 393 374 } 394 375 395 376 /* 396 396 - * link a key into a keyring 397 397 - * - the keyring must be writable 398 398 - * - the key must be linkable 399 399 - * - implements keyctl(KEYCTL_LINK) 377 377 + * Create a link from a keyring to a key if there's no matching key in the 378 378 + * keyring, otherwise replace the link to the matching key with a link to the 379 379 + * new key. 380 380 + * 381 381 + * The key must grant the caller Link permission and the the keyring must grant 382 382 + * the caller Write permission. Furthermore, if an additional link is created, 383 383 + * the keyring's quota will be extended. 384 384 + * 385 385 + * If successful, 0 will be returned. 400 386 */ 401 387 long keyctl_keyring_link(key_serial_t id, key_serial_t ringid) 402 388 { ··· 430 406 } 431 407 432 408 /* 433 433 - * unlink the first attachment of a key from a keyring 434 434 - * - the keyring must be writable 435 435 - * - we don't need any permissions on the key 436 436 - * - implements keyctl(KEYCTL_UNLINK) 409 409 + * Unlink a key from a keyring. 410 410 + * 411 411 + * The keyring must grant the caller Write permission for this to work; the key 412 412 + * itself need not grant the caller anything. If the last link to a key is 413 413 + * removed then that key will be scheduled for destruction. 414 414 + * 415 415 + * If successful, 0 will be returned. 437 416 */ 438 417 long keyctl_keyring_unlink(key_serial_t id, key_serial_t ringid) 439 418 { ··· 465 438 } 466 439 467 440 /* 468 468 - * describe a user key 469 469 - * - the key must have view permission 470 470 - * - if there's a buffer, we place up to buflen bytes of data into it 471 471 - * - unless there's an error, we return the amount of description available, 472 472 - * irrespective of how much we may have copied 473 473 - * - the description is formatted thus: 441 441 + * Return a description of a key to userspace. 442 442 + * 443 443 + * The key must grant the caller View permission for this to work. 444 444 + * 445 445 + * If there's a buffer, we place up to buflen bytes of data into it formatted 446 446 + * in the following way: 447 447 + * 474 448 * type;uid;gid;perm;description<NUL> 475 475 - * - implements keyctl(KEYCTL_DESCRIBE) 449 449 + * 450 450 + * If successful, we return the amount of description available, irrespective 451 451 + * of how much we may have copied into the buffer. 476 452 */ 477 453 long keyctl_describe_key(key_serial_t keyid, 478 454 char __user *buffer, ··· 546 516 } 547 517 548 518 /* 549 549 - * search the specified keyring for a matching key 550 550 - * - the start keyring must be searchable 551 551 - * - nested keyrings may also be searched if they are searchable 552 552 - * - only keys with search permission may be found 553 553 - * - if a key is found, it will be attached to the destination keyring if 554 554 - * there's one specified 555 555 - * - implements keyctl(KEYCTL_SEARCH) 519 519 + * Search the specified keyring and any keyrings it links to for a matching 520 520 + * key. Only keyrings that grant the caller Search permission will be searched 521 521 + * (this includes the starting keyring). Only keys with Search permission can 522 522 + * be found. 523 523 + * 524 524 + * If successful, the found key will be linked to the destination keyring if 525 525 + * supplied and the key has Link permission, and the found key ID will be 526 526 + * returned. 556 527 */ 557 528 long keyctl_keyring_search(key_serial_t ringid, 558 529 const char __user *_type, ··· 640 609 } 641 610 642 611 /* 643 643 - * read a user key's payload 644 644 - * - the keyring must be readable or the key must be searchable from the 645 645 - * process's keyrings 646 646 - * - if there's a buffer, we place up to buflen bytes of data into it 647 647 - * - unless there's an error, we return the amount of data in the key, 648 648 - * irrespective of how much we may have copied 649 649 - * - implements keyctl(KEYCTL_READ) 612 612 + * Read a key's payload. 613 613 + * 614 614 + * The key must either grant the caller Read permission, or it must grant the 615 615 + * caller Search permission when searched for from the process keyrings. 616 616 + * 617 617 + * If successful, we place up to buflen bytes of data into the buffer, if one 618 618 + * is provided, and return the amount of data that is available in the key, 619 619 + * irrespective of how much we copied into the buffer. 650 620 */ 651 621 long keyctl_read_key(key_serial_t keyid, char __user *buffer, size_t buflen) 652 622 { ··· 701 669 } 702 670 703 671 /* 704 704 - * change the ownership of a key 705 705 - * - the keyring owned by the changer 706 706 - * - if the uid or gid is -1, then that parameter is not changed 707 707 - * - implements keyctl(KEYCTL_CHOWN) 672 672 + * Change the ownership of a key 673 673 + * 674 674 + * The key must grant the caller Setattr permission for this to work, though 675 675 + * the key need not be fully instantiated yet. For the UID to be changed, or 676 676 + * for the GID to be changed to a group the caller is not a member of, the 677 677 + * caller must have sysadmin capability. If either uid or gid is -1 then that 678 678 + * attribute is not changed. 679 679 + * 680 680 + * If the UID is to be changed, the new user must have sufficient quota to 681 681 + * accept the key. The quota deduction will be removed from the old user to 682 682 + * the new user should the attribute be changed. 683 683 + * 684 684 + * If successful, 0 will be returned. 708 685 */ 709 686 long keyctl_chown_key(key_serial_t id, uid_t uid, gid_t gid) 710 687 { ··· 816 775 } 817 776 818 777 /* 819 819 - * change the permission mask on a key 820 820 - * - the keyring owned by the changer 821 821 - * - implements keyctl(KEYCTL_SETPERM) 778 778 + * Change the permission mask on a key. 779 779 + * 780 780 + * The key must grant the caller Setattr permission for this to work, though 781 781 + * the key need not be fully instantiated yet. If the caller does not have 782 782 + * sysadmin capability, it may only change the permission on keys that it owns. 822 783 */ 823 784 long keyctl_setperm_key(key_serial_t id, key_perm_t perm) 824 785 { ··· 858 815 } 859 816 860 817 /* 861 861 - * get the destination keyring for instantiation 818 818 + * Get the destination keyring for instantiation and check that the caller has 819 819 + * Write permission on it. 862 820 */ 863 821 static long get_instantiation_keyring(key_serial_t ringid, 864 822 struct request_key_auth *rka, ··· 896 852 } 897 853 898 854 /* 899 899 - * change the request_key authorisation key on the current process 855 855 + * Change the request_key authorisation key on the current process. 900 856 */ 901 857 static int keyctl_change_reqkey_auth(struct key *key) 902 858 { ··· 913 869 } 914 870 915 871 /* 916 916 - * instantiate the key with the specified payload, and, if one is given, link 917 917 - * the key into the keyring 872 872 + * Instantiate a key with the specified payload and link the key into the 873 873 + * destination keyring if one is given. 874 874 + * 875 875 + * The caller must have the appropriate instantiation permit set for this to 876 876 + * work (see keyctl_assume_authority). No other permissions are required. 877 877 + * 878 878 + * If successful, 0 will be returned. 918 879 */ 919 880 long keyctl_instantiate_key(key_serial_t id, 920 881 const void __user *_payload, ··· 997 948 } 998 949 999 950 /* 1000 1000 - * negatively instantiate the key with the given timeout (in seconds), and, if 1001 1001 - * one is given, link the key into the keyring 951 951 + * Negatively instantiate the key with the given timeout (in seconds) and link 952 952 + * the key into the destination keyring if one is given. 953 953 + * 954 954 + * The caller must have the appropriate instantiation permit set for this to 955 955 + * work (see keyctl_assume_authority). No other permissions are required. 956 956 + * 957 957 + * The key and any links to the key will be automatically garbage collected 958 958 + * after the timeout expires. 959 959 + * 960 960 + * Negative keys are used to rate limit repeated request_key() calls by causing 961 961 + * them to return -ENOKEY until the negative key expires. 962 962 + * 963 963 + * If successful, 0 will be returned. 1002 964 */ 1003 965 long keyctl_negate_key(key_serial_t id, unsigned timeout, key_serial_t ringid) 1004 966 { ··· 1053 993 } 1054 994 1055 995 /* 1056 1056 - * set the default keyring in which request_key() will cache keys 1057 1057 - * - return the old setting 996 996 + * Read or set the default keyring in which request_key() will cache keys and 997 997 + * return the old setting. 998 998 + * 999 999 + * If a process keyring is specified then this will be created if it doesn't 1000 1000 + * yet exist. The old setting will be returned if successful. 1058 1001 */ 1059 1002 long keyctl_set_reqkey_keyring(int reqkey_defl) 1060 1003 { ··· 1113 1050 } 1114 1051 1115 1052 /* 1116 1116 - * set or clear the timeout for a key 1053 1053 + * Set or clear the timeout on a key. 1054 1054 + * 1055 1055 + * Either the key must grant the caller Setattr permission or else the caller 1056 1056 + * must hold an instantiation authorisation token for the key. 1057 1057 + * 1058 1058 + * The timeout is either 0 to clear the timeout, or a number of seconds from 1059 1059 + * the current time. The key and any links to the key will be automatically 1060 1060 + * garbage collected after the timeout expires. 1061 1061 + * 1062 1062 + * If successful, 0 is returned. 1117 1063 */ 1118 1064 long keyctl_set_timeout(key_serial_t id, unsigned timeout) 1119 1065 { ··· 1177 1105 } 1178 1106 1179 1107 /* 1180 1180 - * assume the authority to instantiate the specified key 1108 1108 + * Assume (or clear) the authority to instantiate the specified key. 1109 1109 + * 1110 1110 + * This sets the authoritative token currently in force for key instantiation. 1111 1111 + * This must be done for a key to be instantiated. It has the effect of making 1112 1112 + * available all the keys from the caller of the request_key() that created a 1113 1113 + * key to request_key() calls made by the caller of this function. 1114 1114 + * 1115 1115 + * The caller must have the instantiation key in their process keyrings with a 1116 1116 + * Search permission grant available to the caller. 1117 1117 + * 1118 1118 + * If the ID given is 0, then the setting will be cleared and 0 returned. 1119 1119 + * 1120 1120 + * If the ID given has a matching an authorisation key, then that key will be 1121 1121 + * set and its ID will be returned. The authorisation key can be read to get 1122 1122 + * the callout information passed to request_key(). 1181 1123 */ 1182 1124 long keyctl_assume_authority(key_serial_t id) 1183 1125 { ··· 1231 1145 } 1232 1146 1233 1147 /* 1234 1234 - * get the security label of a key 1235 1235 - * - the key must grant us view permission 1236 1236 - * - if there's a buffer, we place up to buflen bytes of data into it 1237 1237 - * - unless there's an error, we return the amount of information available, 1238 1238 - * irrespective of how much we may have copied (including the terminal NUL) 1239 1239 - * - implements keyctl(KEYCTL_GET_SECURITY) 1148 1148 + * Get a key's the LSM security label. 1149 1149 + * 1150 1150 + * The key must grant the caller View permission for this to work. 1151 1151 + * 1152 1152 + * If there's a buffer, then up to buflen bytes of data will be placed into it. 1153 1153 + * 1154 1154 + * If successful, the amount of information available will be returned, 1155 1155 + * irrespective of how much was copied (including the terminal NUL). 1240 1156 */ 1241 1157 long keyctl_get_security(key_serial_t keyid, 1242 1158 char __user *buffer, ··· 1293 1205 } 1294 1206 1295 1207 /* 1296 1296 - * attempt to install the calling process's session keyring on the process's 1297 1297 - * parent process 1298 1298 - * - the keyring must exist and must grant us LINK permission 1299 1299 - * - implements keyctl(KEYCTL_SESSION_TO_PARENT) 1208 1208 + * Attempt to install the calling process's session keyring on the process's 1209 1209 + * parent process. 1210 1210 + * 1211 1211 + * The keyring must exist and must grant the caller LINK permission, and the 1212 1212 + * parent process must be single-threaded and must have the same effective 1213 1213 + * ownership as this process and mustn't be SUID/SGID. 1214 1214 + * 1215 1215 + * The keyring will be emplaced on the parent when it next resumes userspace. 1216 1216 + * 1217 1217 + * If successful, 0 will be returned. 1300 1218 */ 1301 1219 long keyctl_session_to_parent(void) 1302 1220 { ··· 1406 1312 } 1407 1313 1408 1314 /* 1409 1409 - * the key control system call 1315 1315 + * The key control system call 1410 1316 */ 1411 1317 SYSCALL_DEFINE5(keyctl, int, option, unsigned long, arg2, unsigned long, arg3, 1412 1318 unsigned long, arg4, unsigned long, arg5)

+159 -72

security/keys/keyring.c

reviewed

··· 26 26 rwsem_is_locked((struct rw_semaphore *)&(keyring)->sem))) 27 27 28 28 /* 29 29 - * when plumbing the depths of the key tree, this sets a hard limit set on how 30 30 - * deep we're willing to go 29 29 + * When plumbing the depths of the key tree, this sets a hard limit 30 30 + * set on how deep we're willing to go. 31 31 */ 32 32 #define KEYRING_SEARCH_MAX_DEPTH 6 33 33 34 34 /* 35 35 - * we keep all named keyrings in a hash to speed looking them up 35 35 + * We keep all named keyrings in a hash to speed looking them up. 36 36 */ 37 37 #define KEYRING_NAME_HASH_SIZE (1 << 5) 38 38 ··· 50 50 } 51 51 52 52 /* 53 53 - * the keyring type definition 53 53 + * The keyring key type definition. Keyrings are simply keys of this type and 54 54 + * can be treated as ordinary keys in addition to having their own special 55 55 + * operations. 54 56 */ 55 57 static int keyring_instantiate(struct key *keyring, 56 58 const void *data, size_t datalen); ··· 73 71 .describe = keyring_describe, 74 72 .read = keyring_read, 75 73 }; 76 76 - 77 74 EXPORT_SYMBOL(key_type_keyring); 78 75 79 76 /* 80 80 - * semaphore to serialise link/link calls to prevent two link calls in parallel 81 81 - * introducing a cycle 77 77 + * Semaphore to serialise link/link calls to prevent two link calls in parallel 78 78 + * introducing a cycle. 82 79 */ 83 80 static DECLARE_RWSEM(keyring_serialise_link_sem); 84 81 85 82 /* 86 86 - * publish the name of a keyring so that it can be found by name (if it has 87 87 - * one) 83 83 + * Publish the name of a keyring so that it can be found by name (if it has 84 84 + * one). 88 85 */ 89 86 static void keyring_publish_name(struct key *keyring) 90 87 { ··· 105 104 } 106 105 107 106 /* 108 108 - * initialise a keyring 109 109 - * - we object if we were given any data 107 107 + * Initialise a keyring. 108 108 + * 109 109 + * Returns 0 on success, -EINVAL if given any data. 110 110 */ 111 111 static int keyring_instantiate(struct key *keyring, 112 112 const void *data, size_t datalen) ··· 125 123 } 126 124 127 125 /* 128 128 - * match keyrings on their name 126 126 + * Match keyrings on their name 129 127 */ 130 128 static int keyring_match(const struct key *keyring, const void *description) 131 129 { ··· 134 132 } 135 133 136 134 /* 137 137 - * dispose of the data dangling from the corpse of a keyring 135 135 + * Clean up a keyring when it is destroyed. Unpublish its name if it had one 136 136 + * and dispose of its data. 138 137 */ 139 138 static void keyring_destroy(struct key *keyring) 140 139 { ··· 163 160 } 164 161 165 162 /* 166 166 - * describe the keyring 163 163 + * Describe a keyring for /proc. 167 164 */ 168 165 static void keyring_describe(const struct key *keyring, struct seq_file *m) 169 166 { ··· 184 181 } 185 182 186 183 /* 187 187 - * read a list of key IDs from the keyring's contents 188 188 - * - the keyring's semaphore is read-locked 184 184 + * Read a list of key IDs from the keyring's contents in binary form 185 185 + * 186 186 + * The keyring's semaphore is read-locked by the caller. 189 187 */ 190 188 static long keyring_read(const struct key *keyring, 191 189 char __user *buffer, size_t buflen) ··· 237 233 } 238 234 239 235 /* 240 240 - * allocate a keyring and link into the destination keyring 236 236 + * Allocate a keyring and link into the destination keyring. 241 237 */ 242 238 struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid, 243 239 const struct cred *cred, unsigned long flags, ··· 262 258 return keyring; 263 259 } 264 260 265 265 - /* 266 266 - * search the supplied keyring tree for a key that matches the criterion 267 267 - * - perform a breadth-then-depth search up to the prescribed limit 268 268 - * - we only find keys on which we have search permission 269 269 - * - we use the supplied match function to see if the description (or other 270 270 - * feature of interest) matches 271 271 - * - we rely on RCU to prevent the keyring lists from disappearing on us 272 272 - * - we return -EAGAIN if we didn't find any matching key 273 273 - * - we return -ENOKEY if we only found negative matching keys 274 274 - * - we propagate the possession attribute from the keyring ref to the key ref 261 261 + /** 262 262 + * keyring_search_aux - Search a keyring tree for a key matching some criteria 263 263 + * @keyring_ref: A pointer to the keyring with possession indicator. 264 264 + * @cred: The credentials to use for permissions checks. 265 265 + * @type: The type of key to search for. 266 266 + * @description: Parameter for @match. 267 267 + * @match: Function to rule on whether or not a key is the one required. 268 268 + * 269 269 + * Search the supplied keyring tree for a key that matches the criteria given. 270 270 + * The root keyring and any linked keyrings must grant Search permission to the 271 271 + * caller to be searchable and keys can only be found if they too grant Search 272 272 + * to the caller. The possession flag on the root keyring pointer controls use 273 273 + * of the possessor bits in permissions checking of the entire tree. In 274 274 + * addition, the LSM gets to forbid keyring searches and key matches. 275 275 + * 276 276 + * The search is performed as a breadth-then-depth search up to the prescribed 277 277 + * limit (KEYRING_SEARCH_MAX_DEPTH). 278 278 + * 279 279 + * Keys are matched to the type provided and are then filtered by the match 280 280 + * function, which is given the description to use in any way it sees fit. The 281 281 + * match function may use any attributes of a key that it wishes to to 282 282 + * determine the match. Normally the match function from the key type would be 283 283 + * used. 284 284 + * 285 285 + * RCU is used to prevent the keyring key lists from disappearing without the 286 286 + * need to take lots of locks. 287 287 + * 288 288 + * Returns a pointer to the found key and increments the key usage count if 289 289 + * successful; -EAGAIN if no matching keys were found, or if expired or revoked 290 290 + * keys were found; -ENOKEY if only negative keys were found; -ENOTDIR if the 291 291 + * specified keyring wasn't a keyring. 292 292 + * 293 293 + * In the case of a successful return, the possession attribute from 294 294 + * @keyring_ref is propagated to the returned key reference. 275 295 */ 276 296 key_ref_t keyring_search_aux(key_ref_t keyring_ref, 277 297 const struct cred *cred, ··· 459 431 return key_ref; 460 432 } 461 433 462 462 - /* 463 463 - * search the supplied keyring tree for a key that matches the criterion 464 464 - * - perform a breadth-then-depth search up to the prescribed limit 465 465 - * - we only find keys on which we have search permission 466 466 - * - we readlock the keyrings as we search down the tree 467 467 - * - we return -EAGAIN if we didn't find any matching key 468 468 - * - we return -ENOKEY if we only found negative matching keys 434 434 + /** 435 435 + * keyring_search - Search the supplied keyring tree for a matching key 436 436 + * @keyring: The root of the keyring tree to be searched. 437 437 + * @type: The type of keyring we want to find. 438 438 + * @description: The name of the keyring we want to find. 439 439 + * 440 440 + * As keyring_search_aux() above, but using the current task's credentials and 441 441 + * type's default matching function. 469 442 */ 470 443 key_ref_t keyring_search(key_ref_t keyring, 471 444 struct key_type *type, ··· 478 449 return keyring_search_aux(keyring, current->cred, 479 450 type, description, type->match); 480 451 } 481 481 - 482 452 EXPORT_SYMBOL(keyring_search); 483 453 484 454 /* 485 485 - * search the given keyring only (no recursion) 486 486 - * - keyring must be locked by caller 487 487 - * - caller must guarantee that the keyring is a keyring 455 455 + * Search the given keyring only (no recursion). 456 456 + * 457 457 + * The caller must guarantee that the keyring is a keyring and that the 458 458 + * permission is granted to search the keyring as no check is made here. 459 459 + * 460 460 + * RCU is used to make it unnecessary to lock the keyring key list here. 461 461 + * 462 462 + * Returns a pointer to the found key with usage count incremented if 463 463 + * successful and returns -ENOKEY if not found. Revoked keys and keys not 464 464 + * providing the requested permission are skipped over. 465 465 + * 466 466 + * If successful, the possession indicator is propagated from the keyring ref 467 467 + * to the returned key reference. 488 468 */ 489 469 key_ref_t __keyring_search_one(key_ref_t keyring_ref, 490 470 const struct key_type *ktype, ··· 536 498 } 537 499 538 500 /* 539 539 - * find a keyring with the specified name 540 540 - * - all named keyrings are searched 541 541 - * - normally only finds keyrings with search permission for the current process 501 501 + * Find a keyring with the specified name. 502 502 + * 503 503 + * All named keyrings in the current user namespace are searched, provided they 504 504 + * grant Search permission directly to the caller (unless this check is 505 505 + * skipped). Keyrings whose usage points have reached zero or who have been 506 506 + * revoked are skipped. 507 507 + * 508 508 + * Returns a pointer to the keyring with the keyring's refcount having being 509 509 + * incremented on success. -ENOKEY is returned if a key could not be found. 542 510 */ 543 511 struct key *find_keyring_by_name(const char *name, bool skip_perm_check) 544 512 { ··· 595 551 } 596 552 597 553 /* 598 598 - * see if a cycle will will be created by inserting acyclic tree B in acyclic 599 599 - * tree A at the topmost level (ie: as a direct child of A) 600 600 - * - since we are adding B to A at the top level, checking for cycles should 601 601 - * just be a matter of seeing if node A is somewhere in tree B 554 554 + * See if a cycle will will be created by inserting acyclic tree B in acyclic 555 555 + * tree A at the topmost level (ie: as a direct child of A). 556 556 + * 557 557 + * Since we are adding B to A at the top level, checking for cycles should just 558 558 + * be a matter of seeing if node A is somewhere in tree B. 602 559 */ 603 560 static int keyring_detect_cycle(struct key *A, struct key *B) 604 561 { ··· 682 637 } 683 638 684 639 /* 685 685 - * dispose of a keyring list after the RCU grace period, freeing the unlinked 640 640 + * Dispose of a keyring list after the RCU grace period, freeing the unlinked 686 641 * key 687 642 */ 688 643 static void keyring_unlink_rcu_disposal(struct rcu_head *rcu) ··· 696 651 } 697 652 698 653 /* 699 699 - * preallocate memory so that a key can be linked into to a keyring 654 654 + * Preallocate memory so that a key can be linked into to a keyring. 700 655 */ 701 656 int __key_link_begin(struct key *keyring, const struct key_type *type, 702 657 const char *description, ··· 813 768 } 814 769 815 770 /* 816 816 - * check already instantiated keys aren't going to be a problem 817 817 - * - the caller must have called __key_link_begin() 818 818 - * - don't need to call this for keys that were created since __key_link_begin() 819 819 - * was called 771 771 + * Check already instantiated keys aren't going to be a problem. 772 772 + * 773 773 + * The caller must have called __key_link_begin(). Don't need to call this for 774 774 + * keys that were created since __key_link_begin() was called. 820 775 */ 821 776 int __key_link_check_live_key(struct key *keyring, struct key *key) 822 777 { ··· 828 783 } 829 784 830 785 /* 831 831 - * link a key into to a keyring 832 832 - * - must be called with __key_link_begin() having being called 833 833 - * - discard already extant link to matching key if there is one 786 786 + * Link a key into to a keyring. 787 787 + * 788 788 + * Must be called with __key_link_begin() having being called. Discards any 789 789 + * already extant link to matching key if there is one, so that each keyring 790 790 + * holds at most one link to any given key of a particular type+description 791 791 + * combination. 834 792 */ 835 793 void __key_link(struct key *keyring, struct key *key, 836 794 struct keyring_list **_prealloc) ··· 876 828 } 877 829 878 830 /* 879 879 - * finish linking a key into to a keyring 880 880 - * - must be called with __key_link_begin() having being called 831 831 + * Finish linking a key into to a keyring. 832 832 + * 833 833 + * Must be called with __key_link_begin() having being called. 881 834 */ 882 835 void __key_link_end(struct key *keyring, struct key_type *type, 883 836 struct keyring_list *prealloc) ··· 899 850 up_write(&keyring->sem); 900 851 } 901 852 902 902 - /* 903 903 - * link a key to a keyring 853 853 + /** 854 854 + * key_link - Link a key to a keyring 855 855 + * @keyring: The keyring to make the link in. 856 856 + * @key: The key to link to. 857 857 + * 858 858 + * Make a link in a keyring to a key, such that the keyring holds a reference 859 859 + * on that key and the key can potentially be found by searching that keyring. 860 860 + * 861 861 + * This function will write-lock the keyring's semaphore and will consume some 862 862 + * of the user's key data quota to hold the link. 863 863 + * 864 864 + * Returns 0 if successful, -ENOTDIR if the keyring isn't a keyring, 865 865 + * -EKEYREVOKED if the keyring has been revoked, -ENFILE if the keyring is 866 866 + * full, -EDQUOT if there is insufficient key data quota remaining to add 867 867 + * another link or -ENOMEM if there's insufficient memory. 868 868 + * 869 869 + * It is assumed that the caller has checked that it is permitted for a link to 870 870 + * be made (the keyring should have Write permission and the key Link 871 871 + * permission). 904 872 */ 905 873 int key_link(struct key *keyring, struct key *key) 906 874 { ··· 937 871 938 872 return ret; 939 873 } 940 940 - 941 874 EXPORT_SYMBOL(key_link); 942 875 943 943 - /* 944 944 - * unlink the first link to a key from a keyring 876 876 + /** 877 877 + * key_unlink - Unlink the first link to a key from a keyring. 878 878 + * @keyring: The keyring to remove the link from. 879 879 + * @key: The key the link is to. 880 880 + * 881 881 + * Remove a link from a keyring to a key. 882 882 + * 883 883 + * This function will write-lock the keyring's semaphore. 884 884 + * 885 885 + * Returns 0 if successful, -ENOTDIR if the keyring isn't a keyring, -ENOENT if 886 886 + * the key isn't linked to by the keyring or -ENOMEM if there's insufficient 887 887 + * memory. 888 888 + * 889 889 + * It is assumed that the caller has checked that it is permitted for a link to 890 890 + * be removed (the keyring should have Write permission; no permissions are 891 891 + * required on the key). 945 892 */ 946 893 int key_unlink(struct key *keyring, struct key *key) 947 894 { ··· 1023 944 up_write(&keyring->sem); 1024 945 goto error; 1025 946 } 1026 1026 - 1027 947 EXPORT_SYMBOL(key_unlink); 1028 948 1029 949 /* 1030 1030 - * dispose of a keyring list after the RCU grace period, releasing the keys it 1031 1031 - * links to 950 950 + * Dispose of a keyring list after the RCU grace period, releasing the keys it 951 951 + * links to. 1032 952 */ 1033 953 static void keyring_clear_rcu_disposal(struct rcu_head *rcu) 1034 954 { ··· 1042 964 kfree(klist); 1043 965 } 1044 966 1045 1045 - /* 1046 1046 - * clear the specified process keyring 1047 1047 - * - implements keyctl(KEYCTL_CLEAR) 967 967 + /** 968 968 + * keyring_clear - Clear a keyring 969 969 + * @keyring: The keyring to clear. 970 970 + * 971 971 + * Clear the contents of the specified keyring. 972 972 + * 973 973 + * Returns 0 if successful or -ENOTDIR if the keyring isn't a keyring. 1048 974 */ 1049 975 int keyring_clear(struct key *keyring) 1050 976 { ··· 1081 999 1082 1000 return ret; 1083 1001 } 1084 1084 - 1085 1002 EXPORT_SYMBOL(keyring_clear); 1086 1003 1087 1004 /* 1088 1088 - * dispose of the links from a revoked keyring 1089 1089 - * - called with the key sem write-locked 1005 1005 + * Dispose of the links from a revoked keyring. 1006 1006 + * 1007 1007 + * This is called with the key sem write-locked. 1090 1008 */ 1091 1009 static void keyring_revoke(struct key *keyring) 1092 1010 { ··· 1104 1022 } 1105 1023 1106 1024 /* 1107 1107 - * Determine whether a key is dead 1025 1025 + * Determine whether a key is dead. 1108 1026 */ 1109 1027 static bool key_is_dead(struct key *key, time_t limit) 1110 1028 { ··· 1113 1031 } 1114 1032 1115 1033 /* 1116 1116 - * Collect garbage from the contents of a keyring 1034 1034 + * Collect garbage from the contents of a keyring, replacing the old list with 1035 1035 + * a new one with the pointers all shuffled down. 1036 1036 + * 1037 1037 + * Dead keys are classed as oned that are flagged as being dead or are revoked, 1038 1038 + * expired or negative keys that were revoked or expired before the specified 1039 1039 + * limit. 1117 1040 */ 1118 1041 void keyring_gc(struct key *keyring, time_t limit) 1119 1042 {

+15 -10

security/keys/permission.c

reviewed

··· 1 1 - /* permission.c: key permission determination 1 1 + /* Key permission checking 2 2 * 3 3 * Copyright (C) 2005 Red Hat, Inc. All Rights Reserved. 4 4 * Written by David Howells (dhowells@redhat.com) ··· 15 15 16 16 /** 17 17 * key_task_permission - Check a key can be used 18 18 - * @key_ref: The key to check 19 19 - * @cred: The credentials to use 20 20 - * @perm: The permissions to check for 18 18 + * @key_ref: The key to check. 19 19 + * @cred: The credentials to use. 20 20 + * @perm: The permissions to check for. 21 21 * 22 22 * Check to see whether permission is granted to use a key in the desired way, 23 23 * but permit the security modules to override. 24 24 * 25 25 - * The caller must hold either a ref on cred or must hold the RCU readlock or a 26 26 - * spinlock. 25 25 + * The caller must hold either a ref on cred or must hold the RCU readlock. 26 26 + * 27 27 + * Returns 0 if successful, -EACCES if access is denied based on the 28 28 + * permissions bits or the LSM check. 27 29 */ 28 30 int key_task_permission(const key_ref_t key_ref, const struct cred *cred, 29 31 key_perm_t perm) ··· 81 79 /* let LSM be the final arbiter */ 82 80 return security_key_permission(key_ref, cred, perm); 83 81 } 84 84 - 85 82 EXPORT_SYMBOL(key_task_permission); 86 83 87 87 - /* 88 88 - * validate a key 84 84 + /** 85 85 + * key_validate - Validate a key. 86 86 + * @key: The key to be validated. 87 87 + * 88 88 + * Check that a key is valid, returning 0 if the key is okay, -EKEYREVOKED if 89 89 + * the key's type has been removed or if the key has been revoked or 90 90 + * -EKEYEXPIRED if the key has expired. 89 91 */ 90 92 int key_validate(struct key *key) 91 93 { ··· 115 109 error: 116 110 return ret; 117 111 } 118 118 - 119 112 EXPORT_SYMBOL(key_validate);

+6 -4

security/keys/proc.c

reviewed

··· 1 1 - /* proc.c: proc files for key database enumeration 1 1 + /* procfs files for key database enumeration 2 2 * 3 3 * Copyright (C) 2004 Red Hat, Inc. All Rights Reserved. 4 4 * Written by David Howells (dhowells@redhat.com) ··· 61 61 }; 62 62 63 63 /* 64 64 - * declare the /proc files 64 64 + * Declare the /proc files. 65 65 */ 66 66 static int __init key_proc_init(void) 67 67 { ··· 83 83 __initcall(key_proc_init); 84 84 85 85 /* 86 86 - * implement "/proc/keys" to provides a list of the keys on the system 86 86 + * Implement "/proc/keys" to provide a list of the keys on the system that 87 87 + * grant View permission to the caller. 87 88 */ 88 89 #ifdef CONFIG_KEYS_DEBUG_PROC_KEYS 89 90 ··· 292 291 } 293 292 294 293 /* 295 295 - * implement "/proc/key-users" to provides a list of the key users 294 294 + * Implement "/proc/key-users" to provides a list of the key users and their 295 295 + * quotas. 296 296 */ 297 297 static int proc_key_users_open(struct inode *inode, struct file *file) 298 298 {

+75 -37

security/keys/process_keys.c

reviewed

··· 1 1 - /* Management of a process's keyrings 1 1 + /* Manage a process's keyrings 2 2 * 3 3 * Copyright (C) 2004-2005, 2008 Red Hat, Inc. All Rights Reserved. 4 4 * Written by David Howells (dhowells@redhat.com) ··· 21 21 #include <asm/uaccess.h> 22 22 #include "internal.h" 23 23 24 24 - /* session keyring create vs join semaphore */ 24 24 + /* Session keyring create vs join semaphore */ 25 25 static DEFINE_MUTEX(key_session_mutex); 26 26 27 27 - /* user keyring creation semaphore */ 27 27 + /* User keyring creation semaphore */ 28 28 static DEFINE_MUTEX(key_user_keyring_mutex); 29 29 30 30 - /* the root user's tracking struct */ 30 30 + /* The root user's tracking struct */ 31 31 struct key_user root_key_user = { 32 32 .usage = ATOMIC_INIT(3), 33 33 .cons_lock = __MUTEX_INITIALIZER(root_key_user.cons_lock), ··· 39 39 }; 40 40 41 41 /* 42 42 - * install user and user session keyrings for a particular UID 42 42 + * Install the user and user session keyrings for the current process's UID. 43 43 */ 44 44 int install_user_keyrings(void) 45 45 { ··· 121 121 } 122 122 123 123 /* 124 124 - * install a fresh thread keyring directly to new credentials 124 124 + * Install a fresh thread keyring directly to new credentials. This keyring is 125 125 + * allowed to overrun the quota. 125 126 */ 126 127 int install_thread_keyring_to_cred(struct cred *new) 127 128 { ··· 138 137 } 139 138 140 139 /* 141 141 - * install a fresh thread keyring, discarding the old one 140 140 + * Install a fresh thread keyring, discarding the old one. 142 141 */ 143 142 static int install_thread_keyring(void) 144 143 { ··· 161 160 } 162 161 163 162 /* 164 164 - * install a process keyring directly to a credentials struct 165 165 - * - returns -EEXIST if there was already a process keyring, 0 if one installed, 166 166 - * and other -ve on any other error 163 163 + * Install a process keyring directly to a credentials struct. 164 164 + * 165 165 + * Returns -EEXIST if there was already a process keyring, 0 if one installed, 166 166 + * and other value on any other error 167 167 */ 168 168 int install_process_keyring_to_cred(struct cred *new) 169 169 { ··· 193 191 } 194 192 195 193 /* 196 196 - * make sure a process keyring is installed 197 197 - * - we 194 194 + * Make sure a process keyring is installed for the current process. The 195 195 + * existing process keyring is not replaced. 196 196 + * 197 197 + * Returns 0 if there is a process keyring by the end of this function, some 198 198 + * error otherwise. 198 199 */ 199 200 static int install_process_keyring(void) 200 201 { ··· 218 213 } 219 214 220 215 /* 221 221 - * install a session keyring directly to a credentials struct 216 216 + * Install a session keyring directly to a credentials struct. 222 217 */ 223 218 int install_session_keyring_to_cred(struct cred *cred, struct key *keyring) 224 219 { ··· 258 253 } 259 254 260 255 /* 261 261 - * install a session keyring, discarding the old one 262 262 - * - if a keyring is not supplied, an empty one is invented 256 256 + * Install a session keyring, discarding the old one. If a keyring is not 257 257 + * supplied, an empty one is invented. 263 258 */ 264 259 static int install_session_keyring(struct key *keyring) 265 260 { ··· 280 275 } 281 276 282 277 /* 283 283 - * the filesystem user ID changed 278 278 + * Handle the fsuid changing. 284 279 */ 285 280 void key_fsuid_changed(struct task_struct *tsk) 286 281 { ··· 294 289 } 295 290 296 291 /* 297 297 - * the filesystem group ID changed 292 292 + * Handle the fsgid changing. 298 293 */ 299 294 void key_fsgid_changed(struct task_struct *tsk) 300 295 { ··· 308 303 } 309 304 310 305 /* 311 311 - * search only my process keyrings for the first matching key 312 312 - * - we use the supplied match function to see if the description (or other 313 313 - * feature of interest) matches 314 314 - * - we return -EAGAIN if we didn't find any matching key 315 315 - * - we return -ENOKEY if we found only negative matching keys 306 306 + * Search the process keyrings attached to the supplied cred for the first 307 307 + * matching key. 308 308 + * 309 309 + * The search criteria are the type and the match function. The description is 310 310 + * given to the match function as a parameter, but doesn't otherwise influence 311 311 + * the search. Typically the match function will compare the description 312 312 + * parameter to the key's description. 313 313 + * 314 314 + * This can only search keyrings that grant Search permission to the supplied 315 315 + * credentials. Keyrings linked to searched keyrings will also be searched if 316 316 + * they grant Search permission too. Keys can only be found if they grant 317 317 + * Search permission to the credentials. 318 318 + * 319 319 + * Returns a pointer to the key with the key usage count incremented if 320 320 + * successful, -EAGAIN if we didn't find any matching key or -ENOKEY if we only 321 321 + * matched negative keys. 322 322 + * 323 323 + * In the case of a successful return, the possession attribute is set on the 324 324 + * returned key reference. 316 325 */ 317 326 key_ref_t search_my_process_keyrings(struct key_type *type, 318 327 const void *description, ··· 442 423 } 443 424 444 425 /* 445 445 - * search the process keyrings for the first matching key 446 446 - * - we use the supplied match function to see if the description (or other 447 447 - * feature of interest) matches 448 448 - * - we return -EAGAIN if we didn't find any matching key 449 449 - * - we return -ENOKEY if we found only negative matching keys 426 426 + * Search the process keyrings attached to the supplied cred for the first 427 427 + * matching key in the manner of search_my_process_keyrings(), but also search 428 428 + * the keys attached to the assumed authorisation key using its credentials if 429 429 + * one is available. 430 430 + * 431 431 + * Return same as search_my_process_keyrings(). 450 432 */ 451 433 key_ref_t search_process_keyrings(struct key_type *type, 452 434 const void *description, ··· 505 485 } 506 486 507 487 /* 508 508 - * see if the key we're looking at is the target key 488 488 + * See if the key we're looking at is the target key. 509 489 */ 510 490 int lookup_user_key_possessed(const struct key *key, const void *target) 511 491 { ··· 513 493 } 514 494 515 495 /* 516 516 - * lookup a key given a key ID from userspace with a given permissions mask 517 517 - * - don't create special keyrings unless so requested 518 518 - * - partially constructed keys aren't found unless requested 496 496 + * Look up a key ID given us by userspace with a given permissions mask to get 497 497 + * the key it refers to. 498 498 + * 499 499 + * Flags can be passed to request that special keyrings be created if referred 500 500 + * to directly, to permit partially constructed keys to be found and to skip 501 501 + * validity and permission checks on the found key. 502 502 + * 503 503 + * Returns a pointer to the key with an incremented usage count if successful; 504 504 + * -EINVAL if the key ID is invalid; -ENOKEY if the key ID does not correspond 505 505 + * to a key or the best found key was a negative key; -EKEYREVOKED or 506 506 + * -EKEYEXPIRED if the best found key was revoked or expired; -EACCES if the 507 507 + * found key doesn't grant the requested permit or the LSM denied access to it; 508 508 + * or -ENOMEM if a special keyring couldn't be created. 509 509 + * 510 510 + * In the case of a successful return, the possession attribute is set on the 511 511 + * returned key reference. 519 512 */ 520 513 key_ref_t lookup_user_key(key_serial_t id, unsigned long lflags, 521 514 key_perm_t perm) ··· 736 703 } 737 704 738 705 /* 739 739 - * join the named keyring as the session keyring if possible, or attempt to 740 740 - * create a new one of that name if not 741 741 - * - if the name is NULL, an empty anonymous keyring is installed instead 742 742 - * - named session keyring joining is done with a semaphore held 706 706 + * Join the named keyring as the session keyring if possible else attempt to 707 707 + * create a new one of that name and join that. 708 708 + * 709 709 + * If the name is NULL, an empty anonymous keyring will be installed as the 710 710 + * session keyring. 711 711 + * 712 712 + * Named session keyrings are joined with a semaphore held to prevent the 713 713 + * keyrings from going away whilst the attempt is made to going them and also 714 714 + * to prevent a race in creating compatible session keyrings. 743 715 */ 744 716 long join_session_keyring(const char *name) 745 717 { ··· 816 778 } 817 779 818 780 /* 819 819 - * Replace a process's session keyring when that process resumes userspace on 820 820 - * behalf of one of its children 781 781 + * Replace a process's session keyring on behalf of one of its children when 782 782 + * the target process is about to resume userspace execution. 821 783 */ 822 784 void key_replace_session_keyring(void) 823 785 {

+121 -43

security/keys/request_key.c

reviewed

··· 39 39 return signal_pending(current) ? -ERESTARTSYS : 0; 40 40 } 41 41 42 42 - /* 43 43 - * call to complete the construction of a key 42 42 + /** 43 43 + * complete_request_key - Complete the construction of a key. 44 44 + * @cons: The key construction record. 45 45 + * @error: The success or failute of the construction. 46 46 + * 47 47 + * Complete the attempt to construct a key. The key will be negated 48 48 + * if an error is indicated. The authorisation key will be revoked 49 49 + * unconditionally. 44 50 */ 45 51 void complete_request_key(struct key_construction *cons, int error) 46 52 { ··· 64 58 } 65 59 EXPORT_SYMBOL(complete_request_key); 66 60 61 61 + /* 62 62 + * Initialise a usermode helper that is going to have a specific session 63 63 + * keyring. 64 64 + * 65 65 + * This is called in context of freshly forked kthread before kernel_execve(), 66 66 + * so we can simply install the desired session_keyring at this point. 67 67 + */ 67 68 static int umh_keys_init(struct subprocess_info *info) 68 69 { 69 70 struct cred *cred = (struct cred*)current_cred(); 70 71 struct key *keyring = info->data; 71 71 - /* 72 72 - * This is called in context of freshly forked kthread before 73 73 - * kernel_execve(), we can just change our ->session_keyring. 74 74 - */ 72 72 + 75 73 return install_session_keyring_to_cred(cred, keyring); 76 74 } 77 75 76 76 + /* 77 77 + * Clean up a usermode helper with session keyring. 78 78 + */ 78 79 static void umh_keys_cleanup(struct subprocess_info *info) 79 80 { 80 81 struct key *keyring = info->data; 81 82 key_put(keyring); 82 83 } 83 84 85 85 + /* 86 86 + * Call a usermode helper with a specific session keyring. 87 87 + */ 84 88 static int call_usermodehelper_keys(char *path, char **argv, char **envp, 85 89 struct key *session_keyring, enum umh_wait wait) 86 90 { ··· 107 91 } 108 92 109 93 /* 110 110 - * request userspace finish the construction of a key 94 94 + * Request userspace finish the construction of a key 111 95 * - execute "/sbin/request-key <op> <key> <uid> <gid> <keyring> <keyring> <keyring>" 112 96 */ 113 97 static int call_sbin_request_key(struct key_construction *cons, ··· 214 198 } 215 199 216 200 /* 217 217 - * call out to userspace for key construction 218 218 - * - we ignore program failure and go on key status instead 201 201 + * Call out to userspace for key construction. 202 202 + * 203 203 + * Program failure is ignored in favour of key status. 219 204 */ 220 205 static int construct_key(struct key *key, const void *callout_info, 221 206 size_t callout_len, void *aux, ··· 263 246 } 264 247 265 248 /* 266 266 - * get the appropriate destination keyring for the request 267 267 - * - we return whatever keyring we select with an extra reference upon it which 268 268 - * the caller must release 249 249 + * Get the appropriate destination keyring for the request. 250 250 + * 251 251 + * The keyring selected is returned with an extra reference upon it which the 252 252 + * caller must release. 269 253 */ 270 254 static void construct_get_dest_keyring(struct key **_dest_keyring) 271 255 { ··· 339 321 } 340 322 341 323 /* 342 342 - * allocate a new key in under-construction state and attempt to link it in to 343 343 - * the requested place 344 344 - * - may return a key that's already under construction instead 324 324 + * Allocate a new key in under-construction state and attempt to link it in to 325 325 + * the requested keyring. 326 326 + * 327 327 + * May return a key that's already under construction instead if there was a 328 328 + * race between two thread calling request_key(). 345 329 */ 346 330 static int construct_alloc_key(struct key_type *type, 347 331 const char *description, ··· 434 414 } 435 415 436 416 /* 437 437 - * commence key construction 417 417 + * Commence key construction. 438 418 */ 439 419 static struct key *construct_key_and_link(struct key_type *type, 440 420 const char *description, ··· 485 465 return ERR_PTR(ret); 486 466 } 487 467 488 488 - /* 489 489 - * request a key 490 490 - * - search the process's keyrings 491 491 - * - check the list of keys being created or updated 492 492 - * - call out to userspace for a key if supplementary info was provided 493 493 - * - cache the key in an appropriate keyring 468 468 + /** 469 469 + * request_key_and_link - Request a key and cache it in a keyring. 470 470 + * @type: The type of key we want. 471 471 + * @description: The searchable description of the key. 472 472 + * @callout_info: The data to pass to the instantiation upcall (or NULL). 473 473 + * @callout_len: The length of callout_info. 474 474 + * @aux: Auxiliary data for the upcall. 475 475 + * @dest_keyring: Where to cache the key. 476 476 + * @flags: Flags to key_alloc(). 477 477 + * 478 478 + * A key matching the specified criteria is searched for in the process's 479 479 + * keyrings and returned with its usage count incremented if found. Otherwise, 480 480 + * if callout_info is not NULL, a key will be allocated and some service 481 481 + * (probably in userspace) will be asked to instantiate it. 482 482 + * 483 483 + * If successfully found or created, the key will be linked to the destination 484 484 + * keyring if one is provided. 485 485 + * 486 486 + * Returns a pointer to the key if successful; -EACCES, -ENOKEY, -EKEYREVOKED 487 487 + * or -EKEYEXPIRED if an inaccessible, negative, revoked or expired key was 488 488 + * found; -ENOKEY if no key was found and no @callout_info was given; -EDQUOT 489 489 + * if insufficient key quota was available to create a new key; or -ENOMEM if 490 490 + * insufficient memory was available. 491 491 + * 492 492 + * If the returned key was created, then it may still be under construction, 493 493 + * and wait_for_key_construction() should be used to wait for that to complete. 494 494 */ 495 495 struct key *request_key_and_link(struct key_type *type, 496 496 const char *description, ··· 564 524 return key; 565 525 } 566 526 567 567 - /* 568 568 - * wait for construction of a key to complete 527 527 + /** 528 528 + * wait_for_key_construction - Wait for construction of a key to complete 529 529 + * @key: The key being waited for. 530 530 + * @intr: Whether to wait interruptibly. 531 531 + * 532 532 + * Wait for a key to finish being constructed. 533 533 + * 534 534 + * Returns 0 if successful; -ERESTARTSYS if the wait was interrupted; -ENOKEY 535 535 + * if the key was negated; or -EKEYREVOKED or -EKEYEXPIRED if the key was 536 536 + * revoked or expired. 569 537 */ 570 538 int wait_for_key_construction(struct key *key, bool intr) 571 539 { ··· 590 542 } 591 543 EXPORT_SYMBOL(wait_for_key_construction); 592 544 593 593 - /* 594 594 - * request a key 595 595 - * - search the process's keyrings 596 596 - * - check the list of keys being created or updated 597 597 - * - call out to userspace for a key if supplementary info was provided 598 598 - * - waits uninterruptible for creation to complete 545 545 + /** 546 546 + * request_key - Request a key and wait for construction 547 547 + * @type: Type of key. 548 548 + * @description: The searchable description of the key. 549 549 + * @callout_info: The data to pass to the instantiation upcall (or NULL). 550 550 + * 551 551 + * As for request_key_and_link() except that it does not add the returned key 552 552 + * to a keyring if found, new keys are always allocated in the user's quota, 553 553 + * the callout_info must be a NUL-terminated string and no auxiliary data can 554 554 + * be passed. 555 555 + * 556 556 + * Furthermore, it then works as wait_for_key_construction() to wait for the 557 557 + * completion of keys undergoing construction with a non-interruptible wait. 599 558 */ 600 559 struct key *request_key(struct key_type *type, 601 560 const char *description, ··· 627 572 } 628 573 EXPORT_SYMBOL(request_key); 629 574 630 630 - /* 631 631 - * request a key with auxiliary data for the upcaller 632 632 - * - search the process's keyrings 633 633 - * - check the list of keys being created or updated 634 634 - * - call out to userspace for a key if supplementary info was provided 635 635 - * - waits uninterruptible for creation to complete 575 575 + /** 576 576 + * request_key_with_auxdata - Request a key with auxiliary data for the upcaller 577 577 + * @type: The type of key we want. 578 578 + * @description: The searchable description of the key. 579 579 + * @callout_info: The data to pass to the instantiation upcall (or NULL). 580 580 + * @callout_len: The length of callout_info. 581 581 + * @aux: Auxiliary data for the upcall. 582 582 + * 583 583 + * As for request_key_and_link() except that it does not add the returned key 584 584 + * to a keyring if found and new keys are always allocated in the user's quota. 585 585 + * 586 586 + * Furthermore, it then works as wait_for_key_construction() to wait for the 587 587 + * completion of keys undergoing construction with a non-interruptible wait. 636 588 */ 637 589 struct key *request_key_with_auxdata(struct key_type *type, 638 590 const char *description, ··· 664 602 EXPORT_SYMBOL(request_key_with_auxdata); 665 603 666 604 /* 667 667 - * request a key (allow async construction) 668 668 - * - search the process's keyrings 669 669 - * - check the list of keys being created or updated 670 670 - * - call out to userspace for a key if supplementary info was provided 605 605 + * request_key_async - Request a key (allow async construction) 606 606 + * @type: Type of key. 607 607 + * @description: The searchable description of the key. 608 608 + * @callout_info: The data to pass to the instantiation upcall (or NULL). 609 609 + * @callout_len: The length of callout_info. 610 610 + * 611 611 + * As for request_key_and_link() except that it does not add the returned key 612 612 + * to a keyring if found, new keys are always allocated in the user's quota and 613 613 + * no auxiliary data can be passed. 614 614 + * 615 615 + * The caller should call wait_for_key_construction() to wait for the 616 616 + * completion of the returned key if it is still undergoing construction. 671 617 */ 672 618 struct key *request_key_async(struct key_type *type, 673 619 const char *description, ··· 690 620 691 621 /* 692 622 * request a key with auxiliary data for the upcaller (allow async construction) 693 693 - * - search the process's keyrings 694 694 - * - check the list of keys being created or updated 695 695 - * - call out to userspace for a key if supplementary info was provided 623 623 + * @type: Type of key. 624 624 + * @description: The searchable description of the key. 625 625 + * @callout_info: The data to pass to the instantiation upcall (or NULL). 626 626 + * @callout_len: The length of callout_info. 627 627 + * @aux: Auxiliary data for the upcall. 628 628 + * 629 629 + * As for request_key_and_link() except that it does not add the returned key 630 630 + * to a keyring if found and new keys are always allocated in the user's quota. 631 631 + * 632 632 + * The caller should call wait_for_key_construction() to wait for the 633 633 + * completion of the returned key if it is still undergoing construction. 696 634 */ 697 635 struct key *request_key_async_with_auxdata(struct key_type *type, 698 636 const char *description,

+14 -16

security/keys/request_key_auth.c

reviewed

··· 1 1 - /* request_key_auth.c: request key authorisation controlling key def 1 1 + /* Request key authorisation token key definition. 2 2 * 3 3 * Copyright (C) 2005 Red Hat, Inc. All Rights Reserved. 4 4 * Written by David Howells (dhowells@redhat.com) ··· 26 26 static long request_key_auth_read(const struct key *, char __user *, size_t); 27 27 28 28 /* 29 29 - * the request-key authorisation key type definition 29 29 + * The request-key authorisation key type definition. 30 30 */ 31 31 struct key_type key_type_request_key_auth = { 32 32 .name = ".request_key_auth", ··· 39 39 }; 40 40 41 41 /* 42 42 - * instantiate a request-key authorisation key 42 42 + * Instantiate a request-key authorisation key. 43 43 */ 44 44 static int request_key_auth_instantiate(struct key *key, 45 45 const void *data, ··· 50 50 } 51 51 52 52 /* 53 53 - * reading a request-key authorisation key retrieves the callout information 53 53 + * Describe an authorisation token. 54 54 */ 55 55 static void request_key_auth_describe(const struct key *key, 56 56 struct seq_file *m) ··· 63 63 } 64 64 65 65 /* 66 66 - * read the callout_info data 66 66 + * Read the callout_info data (retrieves the callout information). 67 67 * - the key's semaphore is read-locked 68 68 */ 69 69 static long request_key_auth_read(const struct key *key, ··· 89 89 } 90 90 91 91 /* 92 92 - * handle revocation of an authorisation token key 93 93 - * - called with the key sem write-locked 92 92 + * Handle revocation of an authorisation token key. 93 93 + * 94 94 + * Called with the key sem write-locked. 94 95 */ 95 96 static void request_key_auth_revoke(struct key *key) 96 97 { ··· 106 105 } 107 106 108 107 /* 109 109 - * destroy an instantiation authorisation token key 108 108 + * Destroy an instantiation authorisation token key. 110 109 */ 111 110 static void request_key_auth_destroy(struct key *key) 112 111 { ··· 126 125 } 127 126 128 127 /* 129 129 - * create an authorisation token for /sbin/request-key or whoever to gain 130 130 - * access to the caller's security data 128 128 + * Create an authorisation token for /sbin/request-key or whoever to gain 129 129 + * access to the caller's security data. 131 130 */ 132 131 struct key *request_key_auth_new(struct key *target, const void *callout_info, 133 132 size_t callout_len, struct key *dest_keyring) ··· 221 220 } 222 221 223 222 /* 224 224 - * see if an authorisation key is associated with a particular key 223 223 + * See if an authorisation key is associated with a particular key. 225 224 */ 226 225 static int key_get_instantiation_authkey_match(const struct key *key, 227 226 const void *_id) ··· 233 232 } 234 233 235 234 /* 236 236 - * get the authorisation key for instantiation of a specific key if attached to 237 237 - * the current process's keyrings 238 238 - * - this key is inserted into a keyring and that is set as /sbin/request-key's 239 239 - * session keyring 240 240 - * - a target_id of zero specifies any valid token 235 235 + * Search the current process's keyrings for the authorisation key for 236 236 + * instantiation of a key. 241 237 */ 242 238 struct key *key_get_instantiation_authkey(key_serial_t target_id) 243 239 {