aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Howells <dhowells@redhat.com>2007-10-17 02:29:46 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-10-17 11:42:57 -0400
commit76181c134f87479fa13bf2548ddf2999055d34d4 (patch)
tree34694341c190e7ecdd3111ee48e4b98602ff012f /Documentation
parent398c95bdf2c24d7866692a40ba04425aef238cdd (diff)
KEYS: Make request_key() and co fundamentally asynchronous
Make request_key() and co fundamentally asynchronous to make it easier for NFS to make use of them. There are now accessor functions that do asynchronous constructions, a wait function to wait for construction to complete, and a completion function for the key type to indicate completion of construction. Note that the construction queue is now gone. Instead, keys under construction are linked in to the appropriate keyring in advance, and that anyone encountering one must wait for it to be complete before they can use it. This is done automatically for userspace. The following auxiliary changes are also made: (1) Key type implementation stuff is split from linux/key.h into linux/key-type.h. (2) AF_RXRPC provides a way to allocate null rxrpc-type keys so that AFS does not need to call key_instantiate_and_link() directly. (3) Adjust the debugging macros so that they're -Wformat checked even if they are disabled, and make it so they can be enabled simply by defining __KDEBUG to be consistent with other code of mine. (3) Documentation. [alan@lxorguk.ukuu.org.uk: keys: missing word in documentation] Signed-off-by: David Howells <dhowells@redhat.com> Signed-off-by: Alan Cox <alan@redhat.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/keys-request-key.txt25
-rw-r--r--Documentation/keys.txt93
-rw-r--r--Documentation/networking/rxrpc.txt7
3 files changed, 107 insertions, 18 deletions
diff --git a/Documentation/keys-request-key.txt b/Documentation/keys-request-key.txt
index c1f64fdf84cb..266955d23ee6 100644
--- a/Documentation/keys-request-key.txt
+++ b/Documentation/keys-request-key.txt
@@ -20,6 +20,19 @@ or:
20 const char *callout_string, 20 const char *callout_string,
21 void *aux); 21 void *aux);
22 22
23or:
24
25 struct key *request_key_async(const struct key_type *type,
26 const char *description,
27 const char *callout_string);
28
29or:
30
31 struct key *request_key_async_with_auxdata(const struct key_type *type,
32 const char *description,
33 const char *callout_string,
34 void *aux);
35
23Or by userspace invoking the request_key system call: 36Or by userspace invoking the request_key system call:
24 37
25 key_serial_t request_key(const char *type, 38 key_serial_t request_key(const char *type,
@@ -32,10 +45,14 @@ does not need to link the key to a keyring to prevent it from being immediately
32destroyed. The kernel interface returns a pointer directly to the key, and 45destroyed. The kernel interface returns a pointer directly to the key, and
33it's up to the caller to destroy the key. 46it's up to the caller to destroy the key.
34 47
35The request_key_with_auxdata() call is like the in-kernel request_key() call, 48The request_key*_with_auxdata() calls are like the in-kernel request_key*()
36except that it permits auxiliary data to be passed to the upcaller (the default 49calls, except that they permit auxiliary data to be passed to the upcaller (the
37is NULL). This is only useful for those key types that define their own upcall 50default is NULL). This is only useful for those key types that define their
38mechanism rather than using /sbin/request-key. 51own upcall mechanism rather than using /sbin/request-key.
52
53The two async in-kernel calls may return keys that are still in the process of
54being constructed. The two non-async ones will wait for construction to
55complete first.
39 56
40The userspace interface links the key to a keyring associated with the process 57The userspace interface links the key to a keyring associated with the process
41to prevent the key from going away, and returns the serial number of the key to 58to prevent the key from going away, and returns the serial number of the key to
diff --git a/Documentation/keys.txt b/Documentation/keys.txt
index 947d57d53453..51652d39e61c 100644
--- a/Documentation/keys.txt
+++ b/Documentation/keys.txt
@@ -4,7 +4,7 @@
4 4
5This service allows cryptographic keys, authentication tokens, cross-domain 5This service allows cryptographic keys, authentication tokens, cross-domain
6user mappings, and similar to be cached in the kernel for the use of 6user mappings, and similar to be cached in the kernel for the use of
7filesystems other kernel services. 7filesystems and other kernel services.
8 8
9Keyrings are permitted; these are a special type of key that can hold links to 9Keyrings are permitted; these are a special type of key that can hold links to
10other keys. Processes each have three standard keyring subscriptions that a 10other keys. Processes each have three standard keyring subscriptions that a
@@ -726,6 +726,15 @@ call, and the key released upon close. How to deal with conflicting keys due to
726two different users opening the same file is left to the filesystem author to 726two different users opening the same file is left to the filesystem author to
727solve. 727solve.
728 728
729To access the key manager, the following header must be #included:
730
731 <linux/key.h>
732
733Specific key types should have a header file under include/keys/ that should be
734used to access that type. For keys of type "user", for example, that would be:
735
736 <keys/user-type.h>
737
729Note that there are two different types of pointers to keys that may be 738Note that there are two different types of pointers to keys that may be
730encountered: 739encountered:
731 740
@@ -791,6 +800,36 @@ payload contents" for more information.
791 passed to the key_type->request_key() op if it exists. 800 passed to the key_type->request_key() op if it exists.
792 801
793 802
803(*) A key can be requested asynchronously by calling one of:
804
805 struct key *request_key_async(const struct key_type *type,
806 const char *description,
807 const char *callout_string);
808
809 or:
810
811 struct key *request_key_async_with_auxdata(const struct key_type *type,
812 const char *description,
813 const char *callout_string,
814 void *aux);
815
816 which are asynchronous equivalents of request_key() and
817 request_key_with_auxdata() respectively.
818
819 These two functions return with the key potentially still under
820 construction. To wait for contruction completion, the following should be
821 called:
822
823 int wait_for_key_construction(struct key *key, bool intr);
824
825 The function will wait for the key to finish being constructed and then
826 invokes key_validate() to return an appropriate value to indicate the state
827 of the key (0 indicates the key is usable).
828
829 If intr is true, then the wait can be interrupted by a signal, in which
830 case error ERESTARTSYS will be returned.
831
832
794(*) When it is no longer required, the key should be released using: 833(*) When it is no longer required, the key should be released using:
795 834
796 void key_put(struct key *key); 835 void key_put(struct key *key);
@@ -924,7 +963,11 @@ DEFINING A KEY TYPE
924 963
925A kernel service may want to define its own key type. For instance, an AFS 964A kernel service may want to define its own key type. For instance, an AFS
926filesystem might want to define a Kerberos 5 ticket key type. To do this, it 965filesystem might want to define a Kerberos 5 ticket key type. To do this, it
927author fills in a struct key_type and registers it with the system. 966author fills in a key_type struct and registers it with the system.
967
968Source files that implement key types should include the following header file:
969
970 <linux/key-type.h>
928 971
929The structure has a number of fields, some of which are mandatory: 972The structure has a number of fields, some of which are mandatory:
930 973
@@ -1053,22 +1096,44 @@ The structure has a number of fields, some of which are mandatory:
1053 as might happen when the userspace buffer is accessed. 1096 as might happen when the userspace buffer is accessed.
1054 1097
1055 1098
1056 (*) int (*request_key)(struct key *key, struct key *authkey, const char *op, 1099 (*) int (*request_key)(struct key_construction *cons, const char *op,
1057 void *aux); 1100 void *aux);
1058 1101
1059 This method is optional. If provided, request_key() and 1102 This method is optional. If provided, request_key() and friends will
1060 request_key_with_auxdata() will invoke this function rather than 1103 invoke this function rather than upcalling to /sbin/request-key to operate
1061 upcalling to /sbin/request-key to operate upon a key of this type. 1104 upon a key of this type.
1105
1106 The aux parameter is as passed to request_key_async_with_auxdata() and
1107 similar or is NULL otherwise. Also passed are the construction record for
1108 the key to be operated upon and the operation type (currently only
1109 "create").
1110
1111 This method is permitted to return before the upcall is complete, but the
1112 following function must be called under all circumstances to complete the
1113 instantiation process, whether or not it succeeds, whether or not there's
1114 an error:
1115
1116 void complete_request_key(struct key_construction *cons, int error);
1117
1118 The error parameter should be 0 on success, -ve on error. The
1119 construction record is destroyed by this action and the authorisation key
1120 will be revoked. If an error is indicated, the key under construction
1121 will be negatively instantiated if it wasn't already instantiated.
1122
1123 If this method returns an error, that error will be returned to the
1124 caller of request_key*(). complete_request_key() must be called prior to
1125 returning.
1126
1127 The key under construction and the authorisation key can be found in the
1128 key_construction struct pointed to by cons:
1129
1130 (*) struct key *key;
1131
1132 The key under construction.
1062 1133
1063 The aux parameter is as passed to request_key_with_auxdata() or is NULL 1134 (*) struct key *authkey;
1064 otherwise. Also passed are the key to be operated upon, the
1065 authorisation key for this operation and the operation type (currently
1066 only "create").
1067 1135
1068 This function should return only when the upcall is complete. Upon return 1136 The authorisation key.
1069 the authorisation key will be revoked, and the target key will be
1070 negatively instantiated if it is still uninstantiated. The error will be
1071 returned to the caller of request_key*().
1072 1137
1073 1138
1074============================ 1139============================
diff --git a/Documentation/networking/rxrpc.txt b/Documentation/networking/rxrpc.txt
index cae231b1c134..c36b64b0020f 100644
--- a/Documentation/networking/rxrpc.txt
+++ b/Documentation/networking/rxrpc.txt
@@ -857,3 +857,10 @@ The kernel interface functions are as follows:
857 857
858 This is used to extract the error number from a message indicating either 858 This is used to extract the error number from a message indicating either
859 a local error occurred or a network error occurred. 859 a local error occurred or a network error occurred.
860
861 (*) Allocate a null key for doing anonymous security.
862
863 struct key *rxrpc_get_null_key(const char *keyname);
864
865 This is used to allocate a null RxRPC key that can be used to indicate
866 anonymous security for a particular domain.