aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Howells <dhowells@redhat.com>2005-06-24 01:00:49 -0400
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-06-24 03:05:18 -0400
commit76d8aeabfeb1c42641a81c44280177b9a08670d8 (patch)
tree0a584439bb44e440717aa77a1398ba9eea24a137 /Documentation
parent7286aa9b9ab35f20b1ff16d867f4535701df99b5 (diff)
[PATCH] keys: Discard key spinlock and use RCU for key payload
The attached patch changes the key implementation in a number of ways: (1) It removes the spinlock from the key structure. (2) The key flags are now accessed using atomic bitops instead of write-locking the key spinlock and using C bitwise operators. The three instantiation flags are dealt with with the construction semaphore held during the request_key/instantiate/negate sequence, thus rendering the spinlock superfluous. The key flags are also now bit numbers not bit masks. (3) The key payload is now accessed using RCU. This permits the recursive keyring search algorithm to be simplified greatly since no locks need be taken other than the usual RCU preemption disablement. Searching now does not require any locks or semaphores to be held; merely that the starting keyring be pinned. (4) The keyring payload now includes an RCU head so that it can be disposed of by call_rcu(). This requires that the payload be copied on unlink to prevent introducing races in copy-down vs search-up. (5) The user key payload is now a structure with the data following it. It includes an RCU head like the keyring payload and for the same reason. It also contains a data length because the data length in the key may be changed on another CPU whilst an RCU protected read is in progress on the payload. This would then see the supposed RCU payload and the on-key data length getting out of sync. I'm tempted to drop the key's datalen entirely, except that it's used in conjunction with quota management and so is a little tricky to get rid of. (6) Update the keys documentation. Signed-Off-By: David Howells <dhowells@redhat.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/keys.txt285
1 files changed, 172 insertions, 113 deletions
diff --git a/Documentation/keys.txt b/Documentation/keys.txt
index 36d80aeeaf28..3df40c1fe15a 100644
--- a/Documentation/keys.txt
+++ b/Documentation/keys.txt
@@ -22,6 +22,7 @@ This document has the following sections:
22 - New procfs files 22 - New procfs files
23 - Userspace system call interface 23 - Userspace system call interface
24 - Kernel services 24 - Kernel services
25 - Notes on accessing payload contents
25 - Defining a key type 26 - Defining a key type
26 - Request-key callback service 27 - Request-key callback service
27 - Key access filesystem 28 - Key access filesystem
@@ -45,27 +46,26 @@ Each key has a number of attributes:
45 - State. 46 - State.
46 47
47 48
48 (*) Each key is issued a serial number of type key_serial_t that is unique 49 (*) Each key is issued a serial number of type key_serial_t that is unique for
49 for the lifetime of that key. All serial numbers are positive non-zero 50 the lifetime of that key. All serial numbers are positive non-zero 32-bit
50 32-bit integers. 51 integers.
51 52
52 Userspace programs can use a key's serial numbers as a way to gain access 53 Userspace programs can use a key's serial numbers as a way to gain access
53 to it, subject to permission checking. 54 to it, subject to permission checking.
54 55
55 (*) Each key is of a defined "type". Types must be registered inside the 56 (*) Each key is of a defined "type". Types must be registered inside the
56 kernel by a kernel service (such as a filesystem) before keys of that 57 kernel by a kernel service (such as a filesystem) before keys of that type
57 type can be added or used. Userspace programs cannot define new types 58 can be added or used. Userspace programs cannot define new types directly.
58 directly.
59 59
60 Key types are represented in the kernel by struct key_type. This defines 60 Key types are represented in the kernel by struct key_type. This defines a
61 a number of operations that can be performed on a key of that type. 61 number of operations that can be performed on a key of that type.
62 62
63 Should a type be removed from the system, all the keys of that type will 63 Should a type be removed from the system, all the keys of that type will
64 be invalidated. 64 be invalidated.
65 65
66 (*) Each key has a description. This should be a printable string. The key 66 (*) Each key has a description. This should be a printable string. The key
67 type provides an operation to perform a match between the description on 67 type provides an operation to perform a match between the description on a
68 a key and a criterion string. 68 key and a criterion string.
69 69
70 (*) Each key has an owner user ID, a group ID and a permissions mask. These 70 (*) Each key has an owner user ID, a group ID and a permissions mask. These
71 are used to control what a process may do to a key from userspace, and 71 are used to control what a process may do to a key from userspace, and
@@ -74,10 +74,10 @@ Each key has a number of attributes:
74 (*) Each key can be set to expire at a specific time by the key type's 74 (*) Each key can be set to expire at a specific time by the key type's
75 instantiation function. Keys can also be immortal. 75 instantiation function. Keys can also be immortal.
76 76
77 (*) Each key can have a payload. This is a quantity of data that represent 77 (*) Each key can have a payload. This is a quantity of data that represent the
78 the actual "key". In the case of a keyring, this is a list of keys to 78 actual "key". In the case of a keyring, this is a list of keys to which
79 which the keyring links; in the case of a user-defined key, it's an 79 the keyring links; in the case of a user-defined key, it's an arbitrary
80 arbitrary blob of data. 80 blob of data.
81 81
82 Having a payload is not required; and the payload can, in fact, just be a 82 Having a payload is not required; and the payload can, in fact, just be a
83 value stored in the struct key itself. 83 value stored in the struct key itself.
@@ -92,8 +92,8 @@ Each key has a number of attributes:
92 92
93 (*) Each key can be in one of a number of basic states: 93 (*) Each key can be in one of a number of basic states:
94 94
95 (*) Uninstantiated. The key exists, but does not have any data 95 (*) Uninstantiated. The key exists, but does not have any data attached.
96 attached. Keys being requested from userspace will be in this state. 96 Keys being requested from userspace will be in this state.
97 97
98 (*) Instantiated. This is the normal state. The key is fully formed, and 98 (*) Instantiated. This is the normal state. The key is fully formed, and
99 has data attached. 99 has data attached.
@@ -140,10 +140,10 @@ The key service provides a number of features besides keys:
140 clone, fork, vfork or execve occurs. A new keyring is created only when 140 clone, fork, vfork or execve occurs. A new keyring is created only when
141 required. 141 required.
142 142
143 The process-specific keyring is replaced with an empty one in the child 143 The process-specific keyring is replaced with an empty one in the child on
144 on clone, fork, vfork unless CLONE_THREAD is supplied, in which case it 144 clone, fork, vfork unless CLONE_THREAD is supplied, in which case it is
145 is shared. execve also discards the process's process keyring and creates 145 shared. execve also discards the process's process keyring and creates a
146 a new one. 146 new one.
147 147
148 The session-specific keyring is persistent across clone, fork, vfork and 148 The session-specific keyring is persistent across clone, fork, vfork and
149 execve, even when the latter executes a set-UID or set-GID binary. A 149 execve, even when the latter executes a set-UID or set-GID binary. A
@@ -177,11 +177,11 @@ The key service provides a number of features besides keys:
177 If a system call that modifies a key or keyring in some way would put the 177 If a system call that modifies a key or keyring in some way would put the
178 user over quota, the operation is refused and error EDQUOT is returned. 178 user over quota, the operation is refused and error EDQUOT is returned.
179 179
180 (*) There's a system call interface by which userspace programs can create 180 (*) There's a system call interface by which userspace programs can create and
181 and manipulate keys and keyrings. 181 manipulate keys and keyrings.
182 182
183 (*) There's a kernel interface by which services can register types and 183 (*) There's a kernel interface by which services can register types and search
184 search for keys. 184 for keys.
185 185
186 (*) There's a way for the a search done from the kernel to call back to 186 (*) There's a way for the a search done from the kernel to call back to
187 userspace to request a key that can't be found in a process's keyrings. 187 userspace to request a key that can't be found in a process's keyrings.
@@ -194,9 +194,9 @@ The key service provides a number of features besides keys:
194KEY ACCESS PERMISSIONS 194KEY ACCESS PERMISSIONS
195====================== 195======================
196 196
197Keys have an owner user ID, a group access ID, and a permissions mask. The 197Keys have an owner user ID, a group access ID, and a permissions mask. The mask
198mask has up to eight bits each for user, group and other access. Only five of 198has up to eight bits each for user, group and other access. Only five of each
199each set of eight bits are defined. These permissions granted are: 199set of eight bits are defined. These permissions granted are:
200 200
201 (*) View 201 (*) View
202 202
@@ -210,8 +210,8 @@ each set of eight bits are defined. These permissions granted are:
210 210
211 (*) Write 211 (*) Write
212 212
213 This permits a key's payload to be instantiated or updated, or it allows 213 This permits a key's payload to be instantiated or updated, or it allows a
214 a link to be added to or removed from a keyring. 214 link to be added to or removed from a keyring.
215 215
216 (*) Search 216 (*) Search
217 217
@@ -238,8 +238,8 @@ about the status of the key service:
238 (*) /proc/keys 238 (*) /proc/keys
239 239
240 This lists all the keys on the system, giving information about their 240 This lists all the keys on the system, giving information about their
241 type, description and permissions. The payload of the key is not 241 type, description and permissions. The payload of the key is not available
242 available 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 1f0000 0 0 keyring _uid_ses.0: 1/4
@@ -318,21 +318,21 @@ The main syscalls are:
318 If a key of the same type and description as that proposed already exists 318 If a key of the same type and description as that proposed already exists
319 in the keyring, this will try to update it with the given payload, or it 319 in the keyring, this will try to update it with the given payload, or it
320 will return error EEXIST if that function is not supported by the key 320 will return error EEXIST if that function is not supported by the key
321 type. The process must also have permission to write to the key to be 321 type. The process must also have permission to write to the key to be able
322 able to update it. The new key will have all user permissions granted and 322 to update it. The new key will have all user permissions granted and no
323 no group or third party permissions. 323 group or third party permissions.
324 324
325 Otherwise, this will attempt to create a new key of the specified type 325 Otherwise, this will attempt to create a new key of the specified type and
326 and description, and to instantiate it with the supplied payload and 326 description, and to instantiate it with the supplied payload and attach it
327 attach it to the keyring. In this case, an error will be generated if the 327 to the keyring. In this case, an error will be generated if the process
328 process does not have permission to write to the keyring. 328 does not have permission to write to the keyring.
329 329
330 The payload is optional, and the pointer can be NULL if not required by 330 The payload is optional, and the pointer can be NULL if not required by
331 the type. The payload is plen in size, and plen can be zero for an empty 331 the type. The payload is plen in size, and plen can be zero for an empty
332 payload. 332 payload.
333 333
334 A new keyring can be generated by setting type "keyring", the keyring 334 A new keyring can be generated by setting type "keyring", the keyring name
335 name as the description (or NULL) and setting the payload to NULL. 335 as the description (or NULL) and setting the payload to NULL.
336 336
337 User defined keys can be created by specifying type "user". It is 337 User defined keys can be created by specifying type "user". It is
338 recommended that a user defined key's description by prefixed with a type 338 recommended that a user defined key's description by prefixed with a type
@@ -369,9 +369,9 @@ The keyctl syscall functions are:
369 key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id, 369 key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id,
370 int create); 370 int create);
371 371
372 The special key specified by "id" is looked up (with the key being 372 The special key specified by "id" is looked up (with the key being created
373 created if necessary) and the ID of the key or keyring thus found is 373 if necessary) and the ID of the key or keyring thus found is returned if
374 returned if it exists. 374 it exists.
375 375
376 If the key does not yet exist, the key will be created if "create" is 376 If the key does not yet exist, the key will be created if "create" is
377 non-zero; and the error ENOKEY will be returned if "create" is zero. 377 non-zero; and the error ENOKEY will be returned if "create" is zero.
@@ -402,8 +402,8 @@ The keyctl syscall functions are:
402 402
403 This will try to update the specified key with the given payload, or it 403 This will try to update the specified key with the given payload, or it
404 will return error EOPNOTSUPP if that function is not supported by the key 404 will return error EOPNOTSUPP if that function is not supported by the key
405 type. The process must also have permission to write to the key to be 405 type. The process must also have permission to write to the key to be able
406 able to update it. 406 to update it.
407 407
408 The payload is of length plen, and may be absent or empty as for 408 The payload is of length plen, and may be absent or empty as for
409 add_key(). 409 add_key().
@@ -422,8 +422,8 @@ The keyctl syscall functions are:
422 422
423 long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid); 423 long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);
424 424
425 This function permits a key's owner and group ID to be changed. Either 425 This function permits a key's owner and group ID to be changed. Either one
426 one of uid or gid can be set to -1 to suppress that change. 426 of uid or gid can be set to -1 to suppress that change.
427 427
428 Only the superuser can change a key's owner to something other than the 428 Only the superuser can change a key's owner to something other than the
429 key's current owner. Similarly, only the superuser can change a key's 429 key's current owner. Similarly, only the superuser can change a key's
@@ -484,12 +484,12 @@ The keyctl syscall functions are:
484 484
485 long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key); 485 long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);
486 486
487 This function creates a link from the keyring to the key. The process 487 This function creates a link from the keyring to the key. The process must
488 must have write permission on the keyring and must have link permission 488 have write permission on the keyring and must have link permission on the
489 on the key. 489 key.
490 490
491 Should the keyring not be a keyring, error ENOTDIR will result; and if 491 Should the keyring not be a keyring, error ENOTDIR will result; and if the
492 the keyring is full, error ENFILE will result. 492 keyring is full, error ENFILE will result.
493 493
494 The link procedure checks the nesting of the keyrings, returning ELOOP if 494 The link procedure checks the nesting of the keyrings, returning ELOOP if
495 it appears to deep or EDEADLK if the link would introduce a cycle. 495 it appears to deep or EDEADLK if the link would introduce a cycle.
@@ -503,8 +503,8 @@ The keyctl syscall functions are:
503 specified key, and removes it if found. Subsequent links to that key are 503 specified key, and removes it if found. Subsequent links to that key are
504 ignored. The process must have write permission on the keyring. 504 ignored. The process must have write permission on the keyring.
505 505
506 If the keyring is not a keyring, error ENOTDIR will result; and if the 506 If the keyring is not a keyring, error ENOTDIR will result; and if the key
507 key is not present, error ENOENT will be the result. 507 is not present, error ENOENT will be the result.
508 508
509 509
510 (*) Search a keyring tree for a key: 510 (*) Search a keyring tree for a key:
@@ -513,9 +513,9 @@ The keyctl syscall functions are:
513 const char *type, const char *description, 513 const char *type, const char *description,
514 key_serial_t dest_keyring); 514 key_serial_t dest_keyring);
515 515
516 This searches the keyring tree headed by the specified keyring until a 516 This searches the keyring tree headed by the specified keyring until a key
517 key is found that matches the type and description criteria. Each keyring 517 is found that matches the type and description criteria. Each keyring is
518 is checked for keys before recursion into its children occurs. 518 checked for keys before recursion into its children occurs.
519 519
520 The process must have search permission on the top level keyring, or else 520 The process must have search permission on the top level keyring, or else
521 error EACCES will result. Only keyrings that the process has search 521 error EACCES will result. Only keyrings that the process has search
@@ -549,8 +549,8 @@ The keyctl syscall functions are:
549 As much of the data as can be fitted into the buffer will be copied to 549 As much of the data as can be fitted into the buffer will be copied to
550 userspace if the buffer pointer is not NULL. 550 userspace if the buffer pointer is not NULL.
551 551
552 On a successful return, the function will always return the amount of 552 On a successful return, the function will always return the amount of data
553 data available rather than the amount copied. 553 available rather than the amount copied.
554 554
555 555
556 (*) Instantiate a partially constructed key. 556 (*) Instantiate a partially constructed key.
@@ -568,8 +568,8 @@ The keyctl syscall functions are:
568 it, and the key must be uninstantiated. 568 it, and the key must be uninstantiated.
569 569
570 If a keyring is specified (non-zero), the key will also be linked into 570 If a keyring is specified (non-zero), the key will also be linked into
571 that keyring, however all the constraints applying in KEYCTL_LINK apply 571 that keyring, however all the constraints applying in KEYCTL_LINK apply in
572 in this case too. 572 this case too.
573 573
574 The payload and plen arguments describe the payload data as for add_key(). 574 The payload and plen arguments describe the payload data as for add_key().
575 575
@@ -587,8 +587,8 @@ The keyctl syscall functions are:
587 it, and the key must be uninstantiated. 587 it, and the key must be uninstantiated.
588 588
589 If a keyring is specified (non-zero), the key will also be linked into 589 If a keyring is specified (non-zero), the key will also be linked into
590 that keyring, however all the constraints applying in KEYCTL_LINK apply 590 that keyring, however all the constraints applying in KEYCTL_LINK apply in
591 in this case too. 591 this case too.
592 592
593 593
594=============== 594===============
@@ -601,17 +601,14 @@ be broken down into two areas: keys and key types.
601Dealing with keys is fairly straightforward. Firstly, the kernel service 601Dealing with keys is fairly straightforward. Firstly, the kernel service
602registers its type, then it searches for a key of that type. It should retain 602registers its type, then it searches for a key of that type. It should retain
603the key as long as it has need of it, and then it should release it. For a 603the key as long as it has need of it, and then it should release it. For a
604filesystem or device file, a search would probably be performed during the 604filesystem or device file, a search would probably be performed during the open
605open call, and the key released upon close. How to deal with conflicting keys 605call, and the key released upon close. How to deal with conflicting keys due to
606due to two different users opening the same file is left to the filesystem 606two different users opening the same file is left to the filesystem author to
607author to solve. 607solve.
608 608
609When accessing a key's payload data, key->lock should be at least read locked, 609When accessing a key's payload contents, certain precautions must be taken to
610or else the data may be changed by an update being performed from userspace 610prevent access vs modification races. See the section "Notes on accessing
611whilst the driver or filesystem is trying to access it. If no update method is 611payload contents" for more information.
612supplied, then the key's payload may be accessed without holding a lock as
613there is no way to change it, provided it can be guaranteed that the key's
614type definition won't go away.
615 612
616(*) To search for a key, call: 613(*) To search for a key, call:
617 614
@@ -690,6 +687,54 @@ type definition won't go away.
690 void unregister_key_type(struct key_type *type); 687 void unregister_key_type(struct key_type *type);
691 688
692 689
690===================================
691NOTES ON ACCESSING PAYLOAD CONTENTS
692===================================
693
694The simplest payload is just a number in key->payload.value. In this case,
695there's no need to indulge in RCU or locking when accessing the payload.
696
697More complex payload contents must be allocated and a pointer to them set in
698key->payload.data. One of the following ways must be selected to access the
699data:
700
701 (1) Unmodifyable key type.
702
703 If the key type does not have a modify method, then the key's payload can
704 be accessed without any form of locking, provided that it's known to be
705 instantiated (uninstantiated keys cannot be "found").
706
707 (2) The key's semaphore.
708
709 The semaphore could be used to govern access to the payload and to control
710 the payload pointer. It must be write-locked for modifications and would
711 have to be read-locked for general access. The disadvantage of doing this
712 is that the accessor may be required to sleep.
713
714 (3) RCU.
715
716 RCU must be used when the semaphore isn't already held; if the semaphore
717 is held then the contents can't change under you unexpectedly as the
718 semaphore must still be used to serialise modifications to the key. The
719 key management code takes care of this for the key type.
720
721 However, this means using:
722
723 rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock()
724
725 to read the pointer, and:
726
727 rcu_dereference() ... rcu_assign_pointer() ... call_rcu()
728
729 to set the pointer and dispose of the old contents after a grace period.
730 Note that only the key type should ever modify a key's payload.
731
732 Furthermore, an RCU controlled payload must hold a struct rcu_head for the
733 use of call_rcu() and, if the payload is of variable size, the length of
734 the payload. key->datalen cannot be relied upon to be consistent with the
735 payload just dereferenced if the key's semaphore is not held.
736
737
693=================== 738===================
694DEFINING A KEY TYPE 739DEFINING A KEY TYPE
695=================== 740===================
@@ -717,15 +762,15 @@ The structure has a number of fields, some of which are mandatory:
717 762
718 int key_payload_reserve(struct key *key, size_t datalen); 763 int key_payload_reserve(struct key *key, size_t datalen);
719 764
720 With the revised data length. Error EDQUOT will be returned if this is 765 With the revised data length. Error EDQUOT will be returned if this is not
721 not viable. 766 viable.
722 767
723 768
724 (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); 769 (*) int (*instantiate)(struct key *key, const void *data, size_t datalen);
725 770
726 This method is called to attach a payload to a key during construction. 771 This method is called to attach a payload to a key during construction.
727 The payload attached need not bear any relation to the data passed to 772 The payload attached need not bear any relation to the data passed to this
728 this function. 773 function.
729 774
730 If the amount of data attached to the key differs from the size in 775 If the amount of data attached to the key differs from the size in
731 keytype->def_datalen, then key_payload_reserve() should be called. 776 keytype->def_datalen, then key_payload_reserve() should be called.
@@ -734,38 +779,47 @@ The structure has a number of fields, some of which are mandatory:
734 The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents 779 The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
735 anything else from gaining access to the key. 780 anything else from gaining access to the key.
736 781
737 This method may sleep if it wishes. 782 It is safe to sleep in this method.
738 783
739 784
740 (*) int (*duplicate)(struct key *key, const struct key *source); 785 (*) int (*duplicate)(struct key *key, const struct key *source);
741 786
742 If this type of key can be duplicated, then this method should be 787 If this type of key can be duplicated, then this method should be
743 provided. It is called to copy the payload attached to the source into 788 provided. It is called to copy the payload attached to the source into the
744 the new key. The data length on the new key will have been updated and 789 new key. The data length on the new key will have been updated and the
745 the quota adjusted already. 790 quota adjusted already.
746 791
747 This method will be called with the source key's semaphore read-locked to 792 This method will be called with the source key's semaphore read-locked to
748 prevent its payload from being changed. It is safe to sleep here. 793 prevent its payload from being changed, thus RCU constraints need not be
794 applied to the source key.
795
796 This method does not have to lock the destination key in order to attach a
797 payload. The fact that KEY_FLAG_INSTANTIATED is not set in key->flags
798 prevents anything else from gaining access to the key.
799
800 It is safe to sleep in this method.
749 801
750 802
751 (*) int (*update)(struct key *key, const void *data, size_t datalen); 803 (*) int (*update)(struct key *key, const void *data, size_t datalen);
752 804
753 If this type of key can be updated, then this method should be 805 If this type of key can be updated, then this method should be provided.
754 provided. It is called to update a key's payload from the blob of data 806 It is called to update a key's payload from the blob of data provided.
755 provided.
756 807
757 key_payload_reserve() should be called if the data length might change 808 key_payload_reserve() should be called if the data length might change
758 before any changes are actually made. Note that if this succeeds, the 809 before any changes are actually made. Note that if this succeeds, the type
759 type is committed to changing the key because it's already been altered, 810 is committed to changing the key because it's already been altered, so all
760 so all memory allocation must be done first. 811 memory allocation must be done first.
812
813 The key will have its semaphore write-locked before this method is called,
814 but this only deters other writers; any changes to the key's payload must
815 be made under RCU conditions, and call_rcu() must be used to dispose of
816 the old payload.
761 817
762 key_payload_reserve() should be called with the key->lock write locked, 818 key_payload_reserve() should be called before the changes are made, but
763 and the changes to the key's attached payload should be made before the 819 after all allocations and other potentially failing function calls are
764 key is locked. 820 made.
765 821
766 The key will have its semaphore write-locked before this method is 822 It is safe to sleep in this method.
767 called. Any changes to the key should be made with the key's rwlock
768 write-locked also. It is safe to sleep here.
769 823
770 824
771 (*) int (*match)(const struct key *key, const void *desc); 825 (*) int (*match)(const struct key *key, const void *desc);
@@ -782,12 +836,12 @@ The structure has a number of fields, some of which are mandatory:
782 836
783 (*) void (*destroy)(struct key *key); 837 (*) void (*destroy)(struct key *key);
784 838
785 This method is optional. It is called to discard the payload data on a 839 This method is optional. It is called to discard the payload data on a key
786 key when it is being destroyed. 840 when it is being destroyed.
787 841
788 This method does not need to lock the key; it can consider the key as 842 This method does not need to lock the key to access the payload; it can
789 being inaccessible. Note that the key's type may have changed before this 843 consider the key as being inaccessible at this time. Note that the key's
790 function is called. 844 type may have been changed before this function is called.
791 845
792 It is not safe to sleep in this method; the caller may hold spinlocks. 846 It is not safe to sleep in this method; the caller may hold spinlocks.
793 847
@@ -797,26 +851,31 @@ The structure has a number of fields, some of which are mandatory:
797 This method is optional. It is called during /proc/keys reading to 851 This method is optional. It is called during /proc/keys reading to
798 summarise a key's description and payload in text form. 852 summarise a key's description and payload in text form.
799 853
800 This method will be called with the key's rwlock read-locked. This will 854 This method will be called with the RCU read lock held. rcu_dereference()
801 prevent the key's payload and state changing; also the description should 855 should be used to read the payload pointer if the payload is to be
802 not change. This also means it is not safe to sleep in this method. 856 accessed. key->datalen cannot be trusted to stay consistent with the
857 contents of the payload.
858
859 The description will not change, though the key's state may.
860
861 It is not safe to sleep in this method; the RCU read lock is held by the
862 caller.
803 863
804 864
805 (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen); 865 (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
806 866
807 This method is optional. It is called by KEYCTL_READ to translate the 867 This method is optional. It is called by KEYCTL_READ to translate the
808 key's payload into something a blob of data for userspace to deal 868 key's payload into something a blob of data for userspace to deal with.
809 with. Ideally, the blob should be in the same format as that passed in to 869 Ideally, the blob should be in the same format as that passed in to the
810 the instantiate and update methods. 870 instantiate and update methods.
811 871
812 If successful, the blob size that could be produced should be returned 872 If successful, the blob size that could be produced should be returned
813 rather than the size copied. 873 rather than the size copied.
814 874
815 This method will be called with the key's semaphore read-locked. This 875 This method will be called with the key's semaphore read-locked. This will
816 will prevent the key's payload changing. It is not necessary to also 876 prevent the key's payload changing. It is not necessary to use RCU locking
817 read-lock key->lock when accessing the key's payload. It is safe to sleep 877 when accessing the key's payload. It is safe to sleep in this method, such
818 in this method, such as might happen when the userspace buffer is 878 as might happen when the userspace buffer is accessed.
819 accessed.
820 879
821 880
822============================ 881============================
@@ -853,8 +912,8 @@ If it returns with the key remaining in the unconstructed state, the key will
853be marked as being negative, it will be added to the session keyring, and an 912be marked as being negative, it will be added to the session keyring, and an
854error will be returned to the key requestor. 913error will be returned to the key requestor.
855 914
856Supplementary information may be provided from whoever or whatever invoked 915Supplementary information may be provided from whoever or whatever invoked this
857this service. This will be passed as the <callout_info> parameter. If no such 916service. This will be passed as the <callout_info> parameter. If no such
858information was made available, then "-" will be passed as this parameter 917information was made available, then "-" will be passed as this parameter
859instead. 918instead.
860 919