aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/keys-request-key.txt
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/keys-request-key.txt
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/keys-request-key.txt')
-rw-r--r--Documentation/keys-request-key.txt25
1 files changed, 21 insertions, 4 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