diff options
Diffstat (limited to 'Documentation/keys.txt')
-rw-r--r-- | Documentation/keys.txt | 89 |
1 files changed, 85 insertions, 4 deletions
diff --git a/Documentation/keys.txt b/Documentation/keys.txt index aaa01b0e3ee9..e373f0212843 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt | |||
@@ -19,6 +19,7 @@ This document has the following sections: | |||
19 | - Key overview | 19 | - Key overview |
20 | - Key service overview | 20 | - Key service overview |
21 | - Key access permissions | 21 | - Key access permissions |
22 | - SELinux support | ||
22 | - New procfs files | 23 | - New procfs files |
23 | - Userspace system call interface | 24 | - Userspace system call interface |
24 | - Kernel services | 25 | - Kernel services |
@@ -232,6 +233,39 @@ For changing the ownership, group ID or permissions mask, being the owner of | |||
232 | the key or having the sysadmin capability is sufficient. | 233 | the key or having the sysadmin capability is sufficient. |
233 | 234 | ||
234 | 235 | ||
236 | =============== | ||
237 | SELINUX SUPPORT | ||
238 | =============== | ||
239 | |||
240 | The security class "key" has been added to SELinux so that mandatory access | ||
241 | controls can be applied to keys created within various contexts. This support | ||
242 | is preliminary, and is likely to change quite significantly in the near future. | ||
243 | Currently, all of the basic permissions explained above are provided in SELinux | ||
244 | as well; SELinux is simply invoked after all basic permission checks have been | ||
245 | performed. | ||
246 | |||
247 | The value of the file /proc/self/attr/keycreate influences the labeling of | ||
248 | newly-created keys. If the contents of that file correspond to an SELinux | ||
249 | security context, then the key will be assigned that context. Otherwise, the | ||
250 | key will be assigned the current context of the task that invoked the key | ||
251 | creation request. Tasks must be granted explicit permission to assign a | ||
252 | particular context to newly-created keys, using the "create" permission in the | ||
253 | key security class. | ||
254 | |||
255 | The default keyrings associated with users will be labeled with the default | ||
256 | context of the user if and only if the login programs have been instrumented to | ||
257 | properly initialize keycreate during the login process. Otherwise, they will | ||
258 | be labeled with the context of the login program itself. | ||
259 | |||
260 | Note, however, that the default keyrings associated with the root user are | ||
261 | labeled with the default kernel context, since they are created early in the | ||
262 | boot process, before root has a chance to log in. | ||
263 | |||
264 | The keyrings associated with new threads are each labeled with the context of | ||
265 | their associated thread, and both session and process keyrings are handled | ||
266 | similarly. | ||
267 | |||
268 | |||
235 | ================ | 269 | ================ |
236 | NEW PROCFS FILES | 270 | NEW PROCFS FILES |
237 | ================ | 271 | ================ |
@@ -241,9 +275,17 @@ about the status of the key service: | |||
241 | 275 | ||
242 | (*) /proc/keys | 276 | (*) /proc/keys |
243 | 277 | ||
244 | This lists all the keys on the system, giving information about their | 278 | This lists the keys that are currently viewable by the task reading the |
245 | type, description and permissions. The payload of the key is not available | 279 | file, giving information about their type, description and permissions. |
246 | this way: | 280 | It is not possible to view the payload of the key this way, though some |
281 | information about it may be given. | ||
282 | |||
283 | The only keys included in the list are those that grant View permission to | ||
284 | the reading process whether or not it possesses them. Note that LSM | ||
285 | security checks are still performed, and may further filter out keys that | ||
286 | the current process is not authorised to view. | ||
287 | |||
288 | The contents of the file look like this: | ||
247 | 289 | ||
248 | SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY | 290 | SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY |
249 | 00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/4 | 291 | 00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/4 |
@@ -271,7 +313,7 @@ about the status of the key service: | |||
271 | (*) /proc/key-users | 313 | (*) /proc/key-users |
272 | 314 | ||
273 | This file lists the tracking data for each user that has at least one key | 315 | This file lists the tracking data for each user that has at least one key |
274 | on the system. Such data includes quota information and statistics: | 316 | on the system. Such data includes quota information and statistics: |
275 | 317 | ||
276 | [root@andromeda root]# cat /proc/key-users | 318 | [root@andromeda root]# cat /proc/key-users |
277 | 0: 46 45/45 1/100 13/10000 | 319 | 0: 46 45/45 1/100 13/10000 |
@@ -738,6 +780,17 @@ payload contents" for more information. | |||
738 | See also Documentation/keys-request-key.txt. | 780 | See also Documentation/keys-request-key.txt. |
739 | 781 | ||
740 | 782 | ||
783 | (*) To search for a key, passing auxiliary data to the upcaller, call: | ||
784 | |||
785 | struct key *request_key_with_auxdata(const struct key_type *type, | ||
786 | const char *description, | ||
787 | const char *callout_string, | ||
788 | void *aux); | ||
789 | |||
790 | This is identical to request_key(), except that the auxiliary data is | ||
791 | passed to the key_type->request_key() op if it exists. | ||
792 | |||
793 | |||
741 | (*) When it is no longer required, the key should be released using: | 794 | (*) When it is no longer required, the key should be released using: |
742 | 795 | ||
743 | void key_put(struct key *key); | 796 | void key_put(struct key *key); |
@@ -935,6 +988,16 @@ The structure has a number of fields, some of which are mandatory: | |||
935 | It is not safe to sleep in this method; the caller may hold spinlocks. | 988 | It is not safe to sleep in this method; the caller may hold spinlocks. |
936 | 989 | ||
937 | 990 | ||
991 | (*) void (*revoke)(struct key *key); | ||
992 | |||
993 | This method is optional. It is called to discard part of the payload | ||
994 | data upon a key being revoked. The caller will have the key semaphore | ||
995 | write-locked. | ||
996 | |||
997 | It is safe to sleep in this method, though care should be taken to avoid | ||
998 | a deadlock against the key semaphore. | ||
999 | |||
1000 | |||
938 | (*) void (*destroy)(struct key *key); | 1001 | (*) void (*destroy)(struct key *key); |
939 | 1002 | ||
940 | This method is optional. It is called to discard the payload data on a key | 1003 | This method is optional. It is called to discard the payload data on a key |
@@ -979,6 +1042,24 @@ The structure has a number of fields, some of which are mandatory: | |||
979 | as might happen when the userspace buffer is accessed. | 1042 | as might happen when the userspace buffer is accessed. |
980 | 1043 | ||
981 | 1044 | ||
1045 | (*) int (*request_key)(struct key *key, struct key *authkey, const char *op, | ||
1046 | void *aux); | ||
1047 | |||
1048 | This method is optional. If provided, request_key() and | ||
1049 | request_key_with_auxdata() will invoke this function rather than | ||
1050 | upcalling to /sbin/request-key to operate upon a key of this type. | ||
1051 | |||
1052 | The aux parameter is as passed to request_key_with_auxdata() or is NULL | ||
1053 | otherwise. Also passed are the key to be operated upon, the | ||
1054 | authorisation key for this operation and the operation type (currently | ||
1055 | only "create"). | ||
1056 | |||
1057 | This function should return only when the upcall is complete. Upon return | ||
1058 | the authorisation key will be revoked, and the target key will be | ||
1059 | negatively instantiated if it is still uninstantiated. The error will be | ||
1060 | returned to the caller of request_key*(). | ||
1061 | |||
1062 | |||
982 | ============================ | 1063 | ============================ |
983 | REQUEST-KEY CALLBACK SERVICE | 1064 | REQUEST-KEY CALLBACK SERVICE |
984 | ============================ | 1065 | ============================ |