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