]>
Commit | Line | Data |
---|---|---|
6dd17d23 MK |
1 | .\" |
2 | .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. | |
3 | .\" Written by David Howells (dhowells@redhat.com) | |
4 | .\" | |
5 | .\" This program is free software; you can redistribute it and/or | |
6 | .\" modify it under the terms of the GNU General Public License | |
7 | .\" as published by the Free Software Foundation; either version | |
8 | .\" 2 of the License, or (at your option) any later version. | |
9 | .\" | |
513051f7 | 10 | .TH REQUEST_KEY 2 2010-02-25 Linux "Linux Key Management Calls" |
6dd17d23 MK |
11 | .SH NAME |
12 | request_key \- Request a key from the kernel's key management facility | |
6dd17d23 MK |
13 | .SH SYNOPSIS |
14 | .nf | |
15 | .B #include <keyutils.h> | |
16 | .sp | |
17 | .BI "key_serial_t request_key(const char *" type ", const char *" description , | |
74819bb2 MK |
18 | .BI " const char *" callout_info , |
19 | .BI " key_serial_t " keyring ");" | |
6dd17d23 MK |
20 | .SH DESCRIPTION |
21 | .BR request_key () | |
22 | asks the kernel to find a key of the given | |
23 | .I type | |
24 | that matches the specified | |
25 | .I description | |
26 | and, if successful, to attach it to the nominated | |
27 | .I keyring | |
28 | and to return its serial number. | |
29 | .P | |
30 | .BR request_key () | |
31 | first recursively searches all the keyrings attached to the calling process in | |
32 | the order thread-specific keyring, process-specific keyring and then session | |
33 | keyring for a matching key. | |
34 | .P | |
35 | If | |
36 | .BR request_key () | |
37 | is called from a program invoked by | |
38 | .BR request_key () | |
39 | on behalf of some other process to generate a key, then the keyrings of that | |
40 | other process will be searched next, using that other process's UID, GID, | |
41 | groups and security context to control access. | |
42 | .P | |
43 | The keys in each keyring searched are checked for a match before any child | |
44 | keyrings are recursed into. Only keys that are | |
45 | .B searchable | |
46 | for the caller may be found, and only | |
47 | .B searchable | |
48 | keyrings may be searched. | |
49 | .P | |
50 | If the key is not found then, if | |
51 | .I callout_info | |
52 | is set, this function will attempt to look further afield. In such a case, the | |
53 | .I callout_info | |
54 | is passed to a userspace service such as | |
55 | .B /sbin/request\-key | |
56 | to generate the key. | |
57 | .P | |
58 | If that is unsuccessful also, then an error will be returned, and a temporary | |
59 | negative key will be installed in the nominated | |
60 | .IR keyring . | |
61 | This will expire after a few seconds, but will cause subsequent | |
62 | calls to | |
63 | .BR request_key () | |
64 | to fail until it does. | |
65 | .P | |
66 | The | |
67 | .I keyring | |
68 | serial number may be that of a valid keyring to which the caller has write | |
69 | permission, or it may be a special keyring ID: | |
70 | .TP | |
71 | .B KEY_SPEC_THREAD_KEYRING | |
72 | This specifies the caller's thread-specific keyring. | |
73 | .TP | |
74 | .B KEY_SPEC_PROCESS_KEYRING | |
75 | This specifies the caller's process-specific keyring. | |
76 | .TP | |
77 | .B KEY_SPEC_SESSION_KEYRING | |
78 | This specifies the caller's session-specific keyring. | |
79 | .TP | |
80 | .B KEY_SPEC_USER_KEYRING | |
81 | This specifies the caller's UID-specific keyring. | |
82 | .TP | |
83 | .B KEY_SPEC_USER_SESSION_KEYRING | |
84 | This specifies the caller's UID-session keyring. | |
85 | .P | |
86 | If a key is created, no matter whether it's a valid key or a negative key, it | |
87 | will displace any other key of the same type and description from the | |
88 | destination | |
89 | .IR keyring . | |
6dd17d23 MK |
90 | .SH RETURN VALUE |
91 | On success | |
92 | .BR request_key () | |
93 | returns the serial number of the key it found. | |
94 | On error, the value | |
95 | .B -1 | |
96 | will be returned and errno will have been set to an appropriate error. | |
6dd17d23 MK |
97 | .SH ERRORS |
98 | .TP | |
27807c32 MK |
99 | .B EACCES |
100 | The keyring wasn't available for modification by the user. | |
101 | .TP | |
102 | .B EINTR | |
103 | The request was interrupted by a signal. | |
104 | .TP | |
105 | .B EDQUOT | |
106 | The key quota for this user would be exceeded by creating this key or linking | |
107 | it to the keyring. | |
6dd17d23 MK |
108 | .TP |
109 | .B EKEYEXPIRED | |
110 | An expired key was found, but no replacement could be obtained. | |
111 | .TP | |
6dd17d23 MK |
112 | .B EKEYREJECTED |
113 | The attempt to generate a new key was rejected. | |
114 | .TP | |
27807c32 MK |
115 | .B EKEYREVOKED |
116 | A revoked key was found, but no replacement could be obtained. | |
117 | .TP | |
6dd17d23 MK |
118 | .B ENOMEM |
119 | Insufficient memory to create a key. | |
120 | .TP | |
27807c32 MK |
121 | .B ENOKEY |
122 | No matching key was found. | |
6dd17d23 MK |
123 | .SH LINKING |
124 | Although this is a Linux system call, it is not present in | |
125 | .I libc | |
126 | but can be found rather in | |
127 | .IR libkeyutils . | |
128 | When linking, | |
129 | .B -lkeyutils | |
130 | should be specified to the linker. | |
6dd17d23 MK |
131 | .SH SEE ALSO |
132 | .BR keyctl (1), | |
133 | .BR add_key (2), | |
134 | .BR keyctl (2), | |
135 | .BR request-key (8) |