| 1 |
.\" Copyright 2014, Red Hat, Inc. |
| 2 |
.\" Copyright 2016, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 6 |
.\" |
| 7 |
.TH keyrings 7 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
keyrings \- in-kernel key management and retention facility |
| 10 |
.SH DESCRIPTION |
| 11 |
The Linux key-management facility |
| 12 |
is primarily a way for various kernel components |
| 13 |
to retain or cache |
| 14 |
security data, |
| 15 |
authentication keys, |
| 16 |
encryption keys, |
| 17 |
and other data in the kernel. |
| 18 |
.P |
| 19 |
System call interfaces are provided |
| 20 |
so that user-space programs can manage those objects |
| 21 |
and also use the facility for their own purposes; |
| 22 |
see |
| 23 |
.BR add_key (2), |
| 24 |
.BR request_key (2), |
| 25 |
and |
| 26 |
.BR keyctl (2). |
| 27 |
.P |
| 28 |
A library and some user-space utilities are provided |
| 29 |
to allow access to the facility. |
| 30 |
See |
| 31 |
.BR keyctl (1), |
| 32 |
.BR keyctl (3), |
| 33 |
and |
| 34 |
.BR keyutils (7) |
| 35 |
for more information. |
| 36 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 37 |
.SS Keys |
| 38 |
A key has the following attributes: |
| 39 |
.TP |
| 40 |
Serial number (ID) |
| 41 |
This is a unique integer handle by which a key is referred to in system calls. |
| 42 |
The serial number is sometimes synonymously referred as the key ID. |
| 43 |
Programmatically, |
| 44 |
key serial numbers are represented using the type |
| 45 |
.IR key_serial_t . |
| 46 |
.TP |
| 47 |
Type |
| 48 |
A key's type defines what sort of data can be held in the key, |
| 49 |
how the proposed content of the key will be parsed, |
| 50 |
and how the payload will be used. |
| 51 |
.IP |
| 52 |
There are a number of general-purpose types available, |
| 53 |
plus some specialist types defined by specific kernel components. |
| 54 |
.TP |
| 55 |
Description (name) |
| 56 |
The key description is a printable string |
| 57 |
that is used as the search term for the key |
| 58 |
(in conjunction with the key type) |
| 59 |
as well as a display name. |
| 60 |
During searches, |
| 61 |
the description may be partially matched or exactly matched. |
| 62 |
.TP |
| 63 |
Payload (data) |
| 64 |
The payload is the actual content of a key. |
| 65 |
This is usually set when a key is created, |
| 66 |
but it is possible for the kernel to upcall to user space to finish the |
| 67 |
instantiation of a key if that key wasn't already known to the kernel |
| 68 |
when it was requested. |
| 69 |
For further details, |
| 70 |
see |
| 71 |
.BR request_key (2). |
| 72 |
.IP |
| 73 |
A key's payload can be read and updated |
| 74 |
if the key type supports it |
| 75 |
and if suitable permission is granted to the caller. |
| 76 |
.TP |
| 77 |
Access rights |
| 78 |
Much as files do, |
| 79 |
each key has |
| 80 |
an owning user ID, an owning group ID, and a security label. |
| 81 |
Each key also has a set of permissions, |
| 82 |
though there are more than for a normal UNIX file, |
| 83 |
and there is an additional category (possessor) |
| 84 |
beyond the usual user, group, and other |
| 85 |
(see |
| 86 |
.IR Possession , |
| 87 |
below). |
| 88 |
.IP |
| 89 |
Note that keys are quota controlled, |
| 90 |
since they require unswappable kernel memory. |
| 91 |
The owning user ID specifies whose quota is to be debited. |
| 92 |
.TP |
| 93 |
Expiration time |
| 94 |
Each key can have an expiration time set. |
| 95 |
When that time is reached, |
| 96 |
the key is marked as being expired and accesses to it fail with the error |
| 97 |
.BR EKEYEXPIRED . |
| 98 |
If not deleted, updated, or replaced, then, after a set amount of time, |
| 99 |
an expired key is automatically removed (garbage collected) |
| 100 |
along with all links to it, |
| 101 |
and attempts to access the key fail with the error |
| 102 |
.BR ENOKEY . |
| 103 |
.TP |
| 104 |
Reference count |
| 105 |
Each key has a reference count. |
| 106 |
Keys are referenced |
| 107 |
by keyrings, |
| 108 |
by currently active users, |
| 109 |
and by a process's credentials. |
| 110 |
When the reference count reaches zero, |
| 111 |
the key is scheduled for garbage collection. |
| 112 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 113 |
.SS Key types |
| 114 |
The kernel provides several basic types of key: |
| 115 |
.TP |
| 116 |
.I \[dq]keyring\[dq] |
| 117 |
.\" Note that keyrings use different fields in struct key in order to store |
| 118 |
.\" their data - index_key instead of type/description and name_link/keys |
| 119 |
.\" instead of payload. |
| 120 |
Keyrings are special keys which store a set of links |
| 121 |
to other keys (including other keyrings), |
| 122 |
analogous to a directory holding links to files. |
| 123 |
The main purpose of a keyring is |
| 124 |
to prevent other keys from being garbage collected |
| 125 |
because nothing refers to them. |
| 126 |
.IP |
| 127 |
Keyrings with descriptions (names) |
| 128 |
that begin with a period (\[aq].\[aq]) are reserved to the implementation. |
| 129 |
.TP |
| 130 |
.I \[dq]user\[dq] |
| 131 |
This is a general-purpose key type. |
| 132 |
The key is kept entirely within kernel memory. |
| 133 |
The payload may be read and updated by user-space applications. |
| 134 |
.IP |
| 135 |
The payload for keys of this type is a blob of arbitrary data |
| 136 |
of up to 32,767 bytes. |
| 137 |
.IP |
| 138 |
The description may be any valid string, |
| 139 |
though it is preferred that it start with a colon-delimited prefix |
| 140 |
representing the service to which the key is of interest |
| 141 |
(for instance |
| 142 |
.IR \[dq]afs:mykey\[dq] ). |
| 143 |
.TP |
| 144 |
.IR \[dq]logon\[dq] " (since Linux 3.3)" |
| 145 |
.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b |
| 146 |
This key type is essentially the same as |
| 147 |
.IR \[dq]user\[dq] , |
| 148 |
but it does not provide reading (i.e., the |
| 149 |
.BR keyctl (2) |
| 150 |
.B KEYCTL_READ |
| 151 |
operation), |
| 152 |
meaning that the key payload is never visible from user space. |
| 153 |
This is suitable for storing username-password pairs |
| 154 |
that should not be readable from user space. |
| 155 |
.IP |
| 156 |
The description of a |
| 157 |
.I \[dq]logon\[dq] |
| 158 |
key |
| 159 |
.I must |
| 160 |
start with a non-empty colon-delimited prefix whose purpose is |
| 161 |
to identify the service to which the key belongs. |
| 162 |
(Note that this differs from keys of the |
| 163 |
.I \[dq]user\[dq] |
| 164 |
type, |
| 165 |
where the inclusion of a prefix is recommended but is not enforced.) |
| 166 |
.TP |
| 167 |
.IR \[dq]big_key\[dq] " (since Linux 3.13)" |
| 168 |
.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 |
| 169 |
This key type is similar to the |
| 170 |
.I \[dq]user\[dq] |
| 171 |
key type, but it may hold a payload of up to 1\ MiB in size. |
| 172 |
This key type is useful for purposes such as holding Kerberos ticket caches. |
| 173 |
.IP |
| 174 |
The payload data may be stored in a tmpfs filesystem, |
| 175 |
rather than in kernel memory, |
| 176 |
if the data size exceeds the overhead of storing the data in the filesystem. |
| 177 |
(Storing the data in a filesystem requires filesystem structures |
| 178 |
to be allocated in the kernel. |
| 179 |
The size of these structures determines the size threshold |
| 180 |
above which the tmpfs storage method is used.) |
| 181 |
Since Linux 4.8, |
| 182 |
.\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef |
| 183 |
the payload data is encrypted when stored in tmpfs, |
| 184 |
thereby preventing it from being written unencrypted into swap space. |
| 185 |
.P |
| 186 |
There are more specialized key types available also, |
| 187 |
but they aren't discussed here |
| 188 |
because they aren't intended for normal user-space use. |
| 189 |
.P |
| 190 |
Key type names |
| 191 |
that begin with a period (\[aq].\[aq]) are reserved to the implementation. |
| 192 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 193 |
.SS Keyrings |
| 194 |
As previously mentioned, keyrings are a special type of key that contain |
| 195 |
links to other keys (which may include other keyrings). |
| 196 |
Keys may be linked to by multiple keyrings. |
| 197 |
Keyrings may be considered as analogous to UNIX directories |
| 198 |
where each directory contains a set of hard links to files. |
| 199 |
.P |
| 200 |
Various operations (system calls) may be applied only to keyrings: |
| 201 |
.TP |
| 202 |
Adding |
| 203 |
A key may be added to a keyring by system calls that create keys. |
| 204 |
This prevents the new key from being immediately deleted |
| 205 |
when the system call releases its last reference to the key. |
| 206 |
.TP |
| 207 |
Linking |
| 208 |
A link may be added to a keyring pointing to a key that is already known, |
| 209 |
provided this does not create a self-referential cycle. |
| 210 |
.TP |
| 211 |
Unlinking |
| 212 |
A link may be removed from a keyring. |
| 213 |
When the last link to a key is removed, |
| 214 |
that key will be scheduled for deletion by the garbage collector. |
| 215 |
.TP |
| 216 |
Clearing |
| 217 |
All the links may be removed from a keyring. |
| 218 |
.TP |
| 219 |
Searching |
| 220 |
A keyring may be considered the root of a tree or subtree in which keyrings |
| 221 |
form the branches and non-keyrings the leaves. |
| 222 |
This tree may be searched for a key matching |
| 223 |
a particular type and description. |
| 224 |
.P |
| 225 |
See |
| 226 |
.BR keyctl_clear (3), |
| 227 |
.BR keyctl_link (3), |
| 228 |
.BR keyctl_search (3), |
| 229 |
and |
| 230 |
.BR keyctl_unlink (3) |
| 231 |
for more information. |
| 232 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 233 |
.SS Anchoring keys |
| 234 |
To prevent a key from being garbage collected, |
| 235 |
it must be anchored to keep its reference count elevated |
| 236 |
when it is not in active use by the kernel. |
| 237 |
.P |
| 238 |
Keyrings are used to anchor other keys: |
| 239 |
each link is a reference on a key. |
| 240 |
Note that keyrings themselves are just keys and |
| 241 |
are also subject to the same anchoring requirement to prevent |
| 242 |
them being garbage collected. |
| 243 |
.P |
| 244 |
The kernel makes available a number of anchor keyrings. |
| 245 |
Note that some of these keyrings will be created only when first accessed. |
| 246 |
.TP |
| 247 |
Process keyrings |
| 248 |
Process credentials themselves reference keyrings with specific semantics. |
| 249 |
These keyrings are pinned as long as the set of credentials exists, |
| 250 |
which is usually as long as the process exists. |
| 251 |
.IP |
| 252 |
There are three keyrings with different inheritance/sharing rules: |
| 253 |
the |
| 254 |
.BR session\-keyring (7) |
| 255 |
(inherited and shared by all child processes), |
| 256 |
the |
| 257 |
.BR process\-keyring (7) |
| 258 |
(shared by all threads in a process) and |
| 259 |
the |
| 260 |
.BR thread\-keyring (7) |
| 261 |
(specific to a particular thread). |
| 262 |
.IP |
| 263 |
As an alternative to using the actual keyring IDs, |
| 264 |
in calls to |
| 265 |
.BR add_key (2), |
| 266 |
.BR keyctl (2), |
| 267 |
and |
| 268 |
.BR request_key (2), |
| 269 |
the special keyring values |
| 270 |
.BR KEY_SPEC_SESSION_KEYRING , |
| 271 |
.BR KEY_SPEC_PROCESS_KEYRING , |
| 272 |
and |
| 273 |
.B KEY_SPEC_THREAD_KEYRING |
| 274 |
can be used to refer to the caller's own instances of these keyrings. |
| 275 |
.TP |
| 276 |
User keyrings |
| 277 |
Each UID known to the kernel has a record that contains two keyrings: the |
| 278 |
.BR user\-keyring (7) |
| 279 |
and the |
| 280 |
.BR user\-session\-keyring (7). |
| 281 |
These exist for as long as the UID record in the kernel exists. |
| 282 |
.IP |
| 283 |
As an alternative to using the actual keyring IDs, |
| 284 |
in calls to |
| 285 |
.BR add_key (2), |
| 286 |
.BR keyctl (2), |
| 287 |
and |
| 288 |
.BR request_key (2), |
| 289 |
the special keyring values |
| 290 |
.B KEY_SPEC_USER_KEYRING |
| 291 |
and |
| 292 |
.B KEY_SPEC_USER_SESSION_KEYRING |
| 293 |
can be used to refer to the caller's own instances of these keyrings. |
| 294 |
.IP |
| 295 |
A link to the user keyring is placed in a new session keyring by |
| 296 |
.BR pam_keyinit (8) |
| 297 |
when a new login session is initiated. |
| 298 |
.TP |
| 299 |
Persistent keyrings |
| 300 |
There is a |
| 301 |
.BR persistent\-keyring (7) |
| 302 |
available to each UID known to the system. |
| 303 |
It may persist beyond the life of the UID record previously mentioned, |
| 304 |
but has an expiration time set such that it is automatically cleaned up |
| 305 |
after a set time. |
| 306 |
The persistent keyring permits, for example, |
| 307 |
.BR cron (8) |
| 308 |
scripts to use credentials that are left in the persistent keyring after |
| 309 |
the user logs out. |
| 310 |
.IP |
| 311 |
Note that the expiration time of the persistent keyring |
| 312 |
is reset every time the persistent key is requested. |
| 313 |
.TP |
| 314 |
Special keyrings |
| 315 |
There are special keyrings owned by the kernel that can anchor keys |
| 316 |
for special purposes. |
| 317 |
An example of this is the |
| 318 |
.I system\~keyring |
| 319 |
used for holding |
| 320 |
encryption keys for module signature verification. |
| 321 |
.IP |
| 322 |
These special keyrings are usually closed to direct alteration |
| 323 |
by user space. |
| 324 |
.P |
| 325 |
An originally planned "group keyring", |
| 326 |
for storing keys associated with each GID known to the kernel, |
| 327 |
is not so far implemented, is unlikely to be implemented. |
| 328 |
Nevertheless, the constant |
| 329 |
.B KEY_SPEC_GROUP_KEYRING |
| 330 |
has been defined for this keyring. |
| 331 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 332 |
.SS Possession |
| 333 |
The concept of possession is important to understanding the keyrings |
| 334 |
security model. |
| 335 |
Whether a thread possesses a key is determined by the following rules: |
| 336 |
.IP (1) 5 |
| 337 |
Any key or keyring that does not grant |
| 338 |
.I search |
| 339 |
permission to the caller is ignored in all the following rules. |
| 340 |
.IP (2) |
| 341 |
A thread possesses its |
| 342 |
.BR session\-keyring (7), |
| 343 |
.BR process\-keyring (7), |
| 344 |
and |
| 345 |
.BR thread\-keyring (7) |
| 346 |
directly because those keyrings are referred to by its credentials. |
| 347 |
.IP (3) |
| 348 |
If a keyring is possessed, then any key it links to is also possessed. |
| 349 |
.IP (4) |
| 350 |
If any key a keyring links to is itself a keyring, then rule (3) applies |
| 351 |
recursively. |
| 352 |
.IP (5) |
| 353 |
If a process is upcalled from the kernel to instantiate a key (see |
| 354 |
.BR request_key (2)), |
| 355 |
then it also possesses the requester's keyrings as in |
| 356 |
rule (1) as if it were the requester. |
| 357 |
.P |
| 358 |
Note that possession is not a fundamental property of a key, |
| 359 |
but must rather be calculated each time the key is needed. |
| 360 |
.P |
| 361 |
Possession is designed to allow set-user-ID programs run from, say |
| 362 |
a user's shell to access the user's keys. |
| 363 |
Granting permissions to the key possessor while denying them |
| 364 |
to the key owner and group allows the prevention of access to keys |
| 365 |
on the basis of UID and GID matches. |
| 366 |
.P |
| 367 |
When it creates the session keyring, |
| 368 |
.BR pam_keyinit (8) |
| 369 |
adds a link to the |
| 370 |
.BR user\-keyring (7), |
| 371 |
thus making the user keyring and anything it contains possessed by default. |
| 372 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 373 |
.SS Access rights |
| 374 |
Each key has the following security-related attributes: |
| 375 |
.IP \[bu] 3 |
| 376 |
The owning user ID |
| 377 |
.IP \[bu] |
| 378 |
The ID of a group that is permitted to access the key |
| 379 |
.IP \[bu] |
| 380 |
A security label |
| 381 |
.IP \[bu] |
| 382 |
A permissions mask |
| 383 |
.P |
| 384 |
The permissions mask contains four sets of rights. |
| 385 |
The first three sets are mutually exclusive. |
| 386 |
One and only one will be in force for a particular access check. |
| 387 |
In order of descending priority, these three sets are: |
| 388 |
.TP |
| 389 |
.I user |
| 390 |
The set specifies the rights granted |
| 391 |
if the key's user ID matches the caller's filesystem user ID. |
| 392 |
.TP |
| 393 |
.I group |
| 394 |
The set specifies the rights granted |
| 395 |
if the user ID didn't match and the key's group ID matches the caller's |
| 396 |
filesystem GID or one of the caller's supplementary group IDs. |
| 397 |
.TP |
| 398 |
.I other |
| 399 |
The set specifies the rights granted |
| 400 |
if neither the key's user ID nor group ID matched. |
| 401 |
.P |
| 402 |
The fourth set of rights is: |
| 403 |
.TP |
| 404 |
.I possessor |
| 405 |
The set specifies the rights granted |
| 406 |
if a key is determined to be possessed by the caller. |
| 407 |
.P |
| 408 |
The complete set of rights for a key is the union of whichever |
| 409 |
of the first three sets is applicable plus the fourth set |
| 410 |
if the key is possessed. |
| 411 |
.P |
| 412 |
The set of rights that may be granted in each of the four masks |
| 413 |
is as follows: |
| 414 |
.TP |
| 415 |
.I view |
| 416 |
The attributes of the key may be read. |
| 417 |
This includes the type, |
| 418 |
description, and access rights (excluding the security label). |
| 419 |
.TP |
| 420 |
.I read |
| 421 |
For a key: the payload of the key may be read. |
| 422 |
For a keyring: the list of serial numbers (keys) to |
| 423 |
which the keyring has links may be read. |
| 424 |
.TP |
| 425 |
.I write |
| 426 |
The payload of the key may be updated and the key may be revoked. |
| 427 |
For a keyring, links may be added to or removed from the keyring, |
| 428 |
and the keyring may be cleared completely (all links are removed), |
| 429 |
.TP |
| 430 |
.I search |
| 431 |
For a key (or a keyring): the key may be found by a search. |
| 432 |
For a keyring: keys and keyrings that are linked to by the |
| 433 |
keyring may be searched. |
| 434 |
.TP |
| 435 |
.I link |
| 436 |
Links may be created from keyrings to the key. |
| 437 |
The initial link to a key that is established when the key is created |
| 438 |
doesn't require this permission. |
| 439 |
.TP |
| 440 |
.I setattr |
| 441 |
The ownership details and security label of the key may be changed, |
| 442 |
the key's expiration time may be set, and the key may be revoked. |
| 443 |
.P |
| 444 |
In addition to access rights, any active Linux Security Module (LSM) may |
| 445 |
prevent access to a key if its policy so dictates. |
| 446 |
A key may be given a |
| 447 |
security label or other attribute by the LSM; |
| 448 |
this label is retrievable via |
| 449 |
.BR keyctl_get_security (3). |
| 450 |
.P |
| 451 |
See |
| 452 |
.BR keyctl_chown (3), |
| 453 |
.BR keyctl_describe (3), |
| 454 |
.BR keyctl_get_security (3), |
| 455 |
.BR keyctl_setperm (3), |
| 456 |
and |
| 457 |
.BR selinux (8) |
| 458 |
for more information. |
| 459 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 460 |
.SS Searching for keys |
| 461 |
One of the key features of the Linux key-management facility |
| 462 |
is the ability to find a key that a process is retaining. |
| 463 |
The |
| 464 |
.BR request_key (2) |
| 465 |
system call is the primary point of |
| 466 |
access for user-space applications to find a key. |
| 467 |
(Internally, the kernel has something similar available |
| 468 |
for use by internal components that make use of keys.) |
| 469 |
.P |
| 470 |
The search algorithm works as follows: |
| 471 |
.IP (1) 5 |
| 472 |
The process keyrings are searched in the following order: the |
| 473 |
.BR thread\-keyring (7) |
| 474 |
if it exists, the |
| 475 |
.BR process\-keyring (7) |
| 476 |
if it exists, and then either the |
| 477 |
.BR session\-keyring (7) |
| 478 |
if it exists or the |
| 479 |
.BR user\-session\-keyring (7) |
| 480 |
if that exists. |
| 481 |
.IP (2) |
| 482 |
If the caller was a process that was invoked by the |
| 483 |
.BR request_key (2) |
| 484 |
upcall mechanism, then the keyrings of the original caller of |
| 485 |
.BR request_key (2) |
| 486 |
will be searched as well. |
| 487 |
.IP (3) |
| 488 |
The search of a keyring tree is in breadth-first order: |
| 489 |
each keyring is searched first for a match, |
| 490 |
then the keyrings referred to by that keyring are searched. |
| 491 |
.IP (4) |
| 492 |
If a matching key is found that is valid, |
| 493 |
then the search terminates and that key is returned. |
| 494 |
.IP (5) |
| 495 |
If a matching key is found that has an error state attached, |
| 496 |
that error state is noted and the search continues. |
| 497 |
.IP (6) |
| 498 |
If no valid matching key is found, |
| 499 |
then the first noted error state is returned; |
| 500 |
otherwise, an |
| 501 |
.B ENOKEY |
| 502 |
error is returned. |
| 503 |
.P |
| 504 |
It is also possible to search a specific keyring, in which case only steps |
| 505 |
(3) to (6) apply. |
| 506 |
.P |
| 507 |
See |
| 508 |
.BR request_key (2) |
| 509 |
and |
| 510 |
.BR keyctl_search (3) |
| 511 |
for more information. |
| 512 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 513 |
.SS On-demand key creation |
| 514 |
If a key cannot be found, |
| 515 |
.BR request_key (2) |
| 516 |
will, if given a |
| 517 |
.I callout_info |
| 518 |
argument, create a new key and then upcall to user space to |
| 519 |
instantiate the key. |
| 520 |
This allows keys to be created on an as-needed basis. |
| 521 |
.P |
| 522 |
Typically, |
| 523 |
this will involve the kernel creating a new process that executes the |
| 524 |
.BR request\-key (8) |
| 525 |
program, which will then execute the appropriate handler based on its |
| 526 |
configuration. |
| 527 |
.P |
| 528 |
The handler is passed a special authorization key that allows it |
| 529 |
and only it to instantiate the new key. |
| 530 |
This is also used to permit searches performed by the |
| 531 |
handler program to also search the requester's keyrings. |
| 532 |
.P |
| 533 |
See |
| 534 |
.BR request_key (2), |
| 535 |
.BR keyctl_assume_authority (3), |
| 536 |
.BR keyctl_instantiate (3), |
| 537 |
.BR keyctl_negate (3), |
| 538 |
.BR keyctl_reject (3), |
| 539 |
.BR request\-key (8), |
| 540 |
and |
| 541 |
.BR request\-key.conf (5) |
| 542 |
for more information. |
| 543 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 544 |
.SS Users |
| 545 |
The Linux key-management facility has a number of users and usages, |
| 546 |
but is not limited to those that already exist. |
| 547 |
.P |
| 548 |
In-kernel users of this facility include: |
| 549 |
.TP |
| 550 |
Network filesystems - DNS |
| 551 |
The kernel uses the upcall mechanism provided by the keys to upcall to |
| 552 |
user space to do DNS lookups and then to cache the results. |
| 553 |
.TP |
| 554 |
AF_RXRPC and kAFS - Authentication |
| 555 |
The AF_RXRPC network protocol and the in-kernel AFS filesystem |
| 556 |
use keys to store the ticket needed to do secured or encrypted traffic. |
| 557 |
These are then looked up by |
| 558 |
network operations on AF_RXRPC and filesystem operations on kAFS. |
| 559 |
.TP |
| 560 |
NFS - User ID mapping |
| 561 |
The NFS filesystem uses keys to store mappings of |
| 562 |
foreign user IDs to local user IDs. |
| 563 |
.TP |
| 564 |
CIFS - Password |
| 565 |
The CIFS filesystem uses keys to store passwords for accessing remote shares. |
| 566 |
.TP |
| 567 |
Module verification |
| 568 |
The kernel build process can be made to cryptographically sign modules. |
| 569 |
That signature is then checked when a module is loaded. |
| 570 |
.P |
| 571 |
User-space users of this facility include: |
| 572 |
.TP |
| 573 |
Kerberos key storage |
| 574 |
The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication |
| 575 |
tokens which can be made to be automatically cleaned up a set time after |
| 576 |
the user last uses them, |
| 577 |
but until then permits them to hang around after the user |
| 578 |
has logged out so that |
| 579 |
.BR cron (8) |
| 580 |
scripts can use them. |
| 581 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 582 |
.SH FILES |
| 583 |
The kernel provides various |
| 584 |
.I /proc |
| 585 |
files that expose information about keys or define limits on key usage. |
| 586 |
.TP |
| 587 |
.IR /proc/keys " (since Linux 2.6.10)" |
| 588 |
This file exposes a list of the keys for which the reading thread has |
| 589 |
.I view |
| 590 |
permission, providing various information about each key. |
| 591 |
The thread need not possess the key for it to be visible in this file. |
| 592 |
.\" David Howells, Dec 2016 linux-man@: |
| 593 |
.\" This [The thread need not possess the key for it to be visible in |
| 594 |
.\" this file.] is correct. See proc_keys_show() in security/keys/proc.c: |
| 595 |
.\" |
| 596 |
.\" rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW); |
| 597 |
.\" if (rc < 0) |
| 598 |
.\" return 0; |
| 599 |
.\" |
| 600 |
.\"Possibly it shouldn't be, but for now it is. |
| 601 |
.\" |
| 602 |
.IP |
| 603 |
The only keys included in the list are those that grant |
| 604 |
.I view |
| 605 |
permission to the reading process |
| 606 |
(regardless of whether or not it possesses them). |
| 607 |
LSM security checks are still performed, |
| 608 |
and may filter out further keys that the process is not authorized to view. |
| 609 |
.IP |
| 610 |
An example of the data that one might see in this file |
| 611 |
(with the columns numbered for easy reference below) |
| 612 |
is the following: |
| 613 |
.IP |
| 614 |
.EX |
| 615 |
(1) (2) (3)(4) (5) (6) (7) (8) (9) |
| 616 |
009a2028 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12 |
| 617 |
1806c4ba I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 keyring _pid: 2 |
| 618 |
25d3a08f I\-\-Q\-\-\- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1 |
| 619 |
28576bd8 I\-\-Q\-\-\- 3 perm 3f010000 1000 1000 keyring _krb: 1 |
| 620 |
2c546d21 I\-\-Q\-\-\- 190 perm 3f030000 1000 1000 keyring _ses: 2 |
| 621 |
30a4e0be I\-\-\-\-\-\- 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1 |
| 622 |
32100fab I\-\-Q\-\-\- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2 |
| 623 |
32a387ea I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 keyring _pid: 2 |
| 624 |
3ce56aea I\-\-Q\-\-\- 5 perm 3f030000 1000 1000 keyring _ses: 1 |
| 625 |
.EE |
| 626 |
.IP |
| 627 |
The fields shown in each line of this file are as follows: |
| 628 |
.RS |
| 629 |
.TP |
| 630 |
ID (1) |
| 631 |
The ID (serial number) of the key, expressed in hexadecimal. |
| 632 |
.TP |
| 633 |
Flags (2) |
| 634 |
A set of flags describing the state of the key: |
| 635 |
.RS |
| 636 |
.TP |
| 637 |
I |
| 638 |
.\" KEY_FLAG_INSTANTIATED |
| 639 |
The key has been instantiated. |
| 640 |
.TP |
| 641 |
R |
| 642 |
.\" KEY_FLAG_REVOKED |
| 643 |
The key has been revoked. |
| 644 |
.TP |
| 645 |
D |
| 646 |
.\" KEY_FLAG_DEAD |
| 647 |
The key is dead (i.e., the key type has been unregistered). |
| 648 |
.\" unregister_key_type() in the kernel source |
| 649 |
(A key may be briefly in this state during garbage collection.) |
| 650 |
.TP |
| 651 |
Q |
| 652 |
.\" KEY_FLAG_IN_QUOTA |
| 653 |
The key contributes to the user's quota. |
| 654 |
.TP |
| 655 |
U |
| 656 |
.\" KEY_FLAG_USER_CONSTRUCT |
| 657 |
The key is under construction via a callback to user space; |
| 658 |
see |
| 659 |
.BR request\-key (2). |
| 660 |
.TP |
| 661 |
N |
| 662 |
.\" KEY_FLAG_NEGATIVE |
| 663 |
The key is negatively instantiated. |
| 664 |
.TP |
| 665 |
i |
| 666 |
.\" KEY_FLAG_INVALIDATED |
| 667 |
The key has been invalidated. |
| 668 |
.RE |
| 669 |
.TP |
| 670 |
Usage (3) |
| 671 |
This is a count of the number of kernel credential |
| 672 |
structures that are pinning the key |
| 673 |
(approximately: the number of threads and open file references |
| 674 |
that refer to this key). |
| 675 |
.TP |
| 676 |
Timeout (4) |
| 677 |
The amount of time until the key will expire, |
| 678 |
expressed in human-readable form (weeks, days, hours, minutes, and seconds). |
| 679 |
The string |
| 680 |
.I perm |
| 681 |
here means that the key is permanent (no timeout). |
| 682 |
The string |
| 683 |
.I expd |
| 684 |
means that the key has already expired, |
| 685 |
but has not yet been garbage collected. |
| 686 |
.TP |
| 687 |
Permissions (5) |
| 688 |
The key permissions, expressed as four hexadecimal bytes containing, |
| 689 |
from left to right, the possessor, user, group, and other permissions. |
| 690 |
Within each byte, the permission bits are as follows: |
| 691 |
.IP |
| 692 |
.PD 0 |
| 693 |
.RS 12 |
| 694 |
.TP |
| 695 |
0x01 |
| 696 |
.I view |
| 697 |
.TP |
| 698 |
0x02 |
| 699 |
.I read |
| 700 |
.TP |
| 701 |
0x04 |
| 702 |
.I write |
| 703 |
.TP |
| 704 |
0x08 |
| 705 |
.I search |
| 706 |
.TP |
| 707 |
0x10 |
| 708 |
.I link |
| 709 |
.TP |
| 710 |
0x20 |
| 711 |
.I setattr |
| 712 |
.RE |
| 713 |
.PD |
| 714 |
.TP |
| 715 |
UID (6) |
| 716 |
The user ID of the key owner. |
| 717 |
.TP |
| 718 |
GID (7) |
| 719 |
The group ID of the key. |
| 720 |
The value \-1 here means that the key has no group ID; |
| 721 |
this can occur in certain circumstances for keys created by the kernel. |
| 722 |
.TP |
| 723 |
Type (8) |
| 724 |
The key type (user, keyring, etc.) |
| 725 |
.TP |
| 726 |
Description (9) |
| 727 |
The key description (name). |
| 728 |
This field contains descriptive information about the key. |
| 729 |
For most key types, it has the form |
| 730 |
.IP |
| 731 |
.in +4n |
| 732 |
.EX |
| 733 |
name[: extra\-info] |
| 734 |
.EE |
| 735 |
.in |
| 736 |
.IP |
| 737 |
The |
| 738 |
.I name |
| 739 |
subfield is the key's description (name). |
| 740 |
The optional |
| 741 |
.I extra\-info |
| 742 |
field provides some further information about the key. |
| 743 |
The information that appears here depends on the key type, as follows: |
| 744 |
.RS |
| 745 |
.TP |
| 746 |
.I \[dq]user\[dq] |
| 747 |
.TQ |
| 748 |
.I \[dq]logon\[dq] |
| 749 |
The size in bytes of the key payload (expressed in decimal). |
| 750 |
.TP |
| 751 |
.I \[dq]keyring\[dq] |
| 752 |
The number of keys linked to the keyring, |
| 753 |
or the string |
| 754 |
.I empty |
| 755 |
if there are no keys linked to the keyring. |
| 756 |
.TP |
| 757 |
.I \[dq]big_key\[dq] |
| 758 |
The payload size in bytes, |
| 759 |
followed either by the string |
| 760 |
.IR [file] , |
| 761 |
if the key payload exceeds the threshold |
| 762 |
that means that the payload is stored in a (swappable) |
| 763 |
.BR tmpfs (5) |
| 764 |
filesystem, |
| 765 |
or otherwise the string |
| 766 |
.IR [buff] , |
| 767 |
indicating that the key is small enough to reside in kernel memory. |
| 768 |
.RE |
| 769 |
.IP |
| 770 |
For the |
| 771 |
.I \[dq].request_key_auth\[dq] |
| 772 |
key type |
| 773 |
(authorization key; |
| 774 |
see |
| 775 |
.BR request_key (2)), |
| 776 |
the description field has the form shown in the following example: |
| 777 |
.IP |
| 778 |
.in +4n |
| 779 |
.EX |
| 780 |
key:c9a9b19 pid:28880 ci:10 |
| 781 |
.EE |
| 782 |
.in |
| 783 |
.IP |
| 784 |
The three subfields are as follows: |
| 785 |
.RS |
| 786 |
.TP |
| 787 |
.I key |
| 788 |
The hexadecimal ID of the key being instantiated in the requesting program. |
| 789 |
.TP |
| 790 |
.I pid |
| 791 |
The PID of the requesting program. |
| 792 |
.TP |
| 793 |
.I ci |
| 794 |
The length of the callout data with which the requested key should |
| 795 |
be instantiated |
| 796 |
(i.e., the length of the payload associated with the authorization key). |
| 797 |
.RE |
| 798 |
.RE |
| 799 |
.TP |
| 800 |
.IR /proc/key\-users " (since Linux 2.6.10)" |
| 801 |
This file lists various information for each user ID that |
| 802 |
has at least one key on the system. |
| 803 |
An example of the data that one might see in this file is the following: |
| 804 |
.IP |
| 805 |
.in +4n |
| 806 |
.EX |
| 807 |
0: 10 9/9 2/1000000 22/25000000 |
| 808 |
42: 9 9/9 8/200 106/20000 |
| 809 |
1000: 11 11/11 10/200 271/20000 |
| 810 |
.EE |
| 811 |
.in |
| 812 |
.IP |
| 813 |
The fields shown in each line are as follows: |
| 814 |
.RS |
| 815 |
.TP |
| 816 |
.I uid |
| 817 |
The user ID. |
| 818 |
.TP |
| 819 |
.I usage |
| 820 |
This is a kernel-internal usage count for the kernel structure |
| 821 |
used to record key users. |
| 822 |
.TP |
| 823 |
.IR nkeys / nikeys |
| 824 |
The total number of keys owned by the user, |
| 825 |
and the number of those keys that have been instantiated. |
| 826 |
.TP |
| 827 |
.IR qnkeys / maxkeys |
| 828 |
The number of keys owned by the user, |
| 829 |
and the maximum number of keys that the user may own. |
| 830 |
.TP |
| 831 |
.IR qnbytes / maxbytes |
| 832 |
The number of bytes consumed in payloads of the keys owned by this user, |
| 833 |
and the upper limit on the number of bytes in key payloads for that user. |
| 834 |
.RE |
| 835 |
.TP |
| 836 |
.IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)" |
| 837 |
.\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b |
| 838 |
The value in this file specifies the interval, in seconds, |
| 839 |
after which revoked and expired keys will be garbage collected. |
| 840 |
The purpose of having such an interval is so that there is a window |
| 841 |
of time where user space can see an error (respectively |
| 842 |
.B EKEYREVOKED |
| 843 |
and |
| 844 |
.BR EKEYEXPIRED ) |
| 845 |
that indicates what happened to the key. |
| 846 |
.IP |
| 847 |
The default value in this file is 300 (i.e., 5 minutes). |
| 848 |
.TP |
| 849 |
.IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)" |
| 850 |
.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e |
| 851 |
This file defines an interval, in seconds, |
| 852 |
to which the persistent keyring's expiration timer is reset |
| 853 |
each time the keyring is accessed (via |
| 854 |
.BR keyctl_get_persistent (3) |
| 855 |
or the |
| 856 |
.BR keyctl (2) |
| 857 |
.B KEYCTL_GET_PERSISTENT |
| 858 |
operation.) |
| 859 |
.IP |
| 860 |
The default value in this file is 259200 (i.e., 3 days). |
| 861 |
.P |
| 862 |
The following files (which are writable by privileged processes) |
| 863 |
are used to enforce quotas on the number of keys |
| 864 |
and number of bytes of data that can be stored in key payloads: |
| 865 |
.TP |
| 866 |
.IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)" |
| 867 |
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 |
| 868 |
.\" Previously: KEYQUOTA_MAX_BYTES 10000 |
| 869 |
This is the maximum number of bytes of data that a nonroot user |
| 870 |
can hold in the payloads of the keys owned by the user. |
| 871 |
.IP |
| 872 |
The default value in this file is 20,000. |
| 873 |
.TP |
| 874 |
.IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)" |
| 875 |
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 |
| 876 |
.\" Previously: KEYQUOTA_MAX_KEYS 100 |
| 877 |
This is the maximum number of keys that a nonroot user may own. |
| 878 |
.IP |
| 879 |
The default value in this file is 200. |
| 880 |
.TP |
| 881 |
.IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)" |
| 882 |
This is the maximum number of bytes of data that the root user |
| 883 |
(UID 0 in the root user namespace) |
| 884 |
can hold in the payloads of the keys owned by root. |
| 885 |
.IP |
| 886 |
.\"738c5d190f6540539a04baf36ce21d46b5da04bd |
| 887 |
The default value in this file is 25,000,000 (20,000 before Linux 3.17). |
| 888 |
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 |
| 889 |
.TP |
| 890 |
.IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)" |
| 891 |
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 |
| 892 |
This is the maximum number of keys that the root user |
| 893 |
(UID 0 in the root user namespace) |
| 894 |
may own. |
| 895 |
.IP |
| 896 |
.\"738c5d190f6540539a04baf36ce21d46b5da04bd |
| 897 |
The default value in this file is 1,000,000 (200 before Linux 3.17). |
| 898 |
.P |
| 899 |
With respect to keyrings, |
| 900 |
note that each link in a keyring consumes 4 bytes of the keyring payload. |
| 901 |
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 902 |
.SH SEE ALSO |
| 903 |
.ad l |
| 904 |
.nh |
| 905 |
.BR keyctl (1), |
| 906 |
.BR add_key (2), |
| 907 |
.BR keyctl (2), |
| 908 |
.BR request_key (2), |
| 909 |
.BR keyctl (3), |
| 910 |
.BR keyutils (7), |
| 911 |
.BR persistent\-keyring (7), |
| 912 |
.BR process\-keyring (7), |
| 913 |
.BR session\-keyring (7), |
| 914 |
.BR thread\-keyring (7), |
| 915 |
.BR user\-keyring (7), |
| 916 |
.BR user\-session\-keyring (7), |
| 917 |
.BR pam_keyinit (8), |
| 918 |
.BR request\-key (8) |
| 919 |
.TP |
| 920 |
.I linux.git/Documentation/crypto/asymmetric\-keys.rst |
| 921 |
.TQ |
| 922 |
.I linux.git/\:Documentation/\:security/\:keys/ |