summaryrefslogtreecommitdiffstats
path: root/man2/keyctl.2
blob: 8f8ec1904891574370de3d7d460254d42e12a428 (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
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
.\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
.\" and Copyright (C) 2016 Eugene Syromyatnikov <evgsyr@gmail.com>
.\" A very few fragments remain from an earlier version of this page
.\" written by David Howells (dhowells@redhat.com)
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH keyctl 2 2024-02-25 "Linux man-pages 6.7"
.SH NAME
keyctl \- manipulate the kernel's key management facility
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.P
Alternatively, Linux Key Management Utilities
.RI ( libkeyutils ", " \-lkeyutils );
see VERSIONS.
.SH SYNOPSIS
.nf
.BR "#include <linux/keyctl.h>" "     /* Definition of " KEY* " constants */"
.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 ,
.BI "             unsigned long " arg3 ", unsigned long " arg4 ,
.BI "             unsigned long " arg5 );
.fi
.P
.IR Note :
glibc provides no wrapper for
.BR keyctl (),
necessitating the use of
.BR syscall (2).
.SH DESCRIPTION
.BR keyctl ()
allows user-space programs to perform key manipulation.
.P
The operation performed by
.BR keyctl ()
is determined by the value of the
.I operation
argument.
Each of these operations is wrapped by the
.I libkeyutils
library (provided by the
.I keyutils
package) into individual functions (noted below)
to permit the compiler to check types.
.P
The permitted values for
.I operation
are:
.TP
.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)"
Map a special key ID to a real key ID for this process.
.IP
This operation looks up the special key whose ID is provided in
.I arg2
(cast to
.IR key_serial_t ).
If the special key is found,
the ID of the corresponding real key is returned as the function result.
The following values may be specified in
.IR arg2 :
.RS
.TP
.B KEY_SPEC_THREAD_KEYRING
This specifies the calling thread's thread-specific keyring.
See
.BR thread\-keyring (7).
.TP
.B KEY_SPEC_PROCESS_KEYRING
This specifies the caller's process-specific keyring.
See
.BR process\-keyring (7).
.TP
.B KEY_SPEC_SESSION_KEYRING
This specifies the caller's session-specific keyring.
See
.BR session\-keyring (7).
.TP
.B KEY_SPEC_USER_KEYRING
This specifies the caller's UID-specific keyring.
See
.BR user\-keyring (7).
.TP
.B KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring.
See
.BR user\-session\-keyring (7).
.TP
.BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)"
.\"            commit b5f545c880a2a47947ba2118b2509644ab7a2969
This specifies the authorization key created by
.BR request_key (2)
and passed to the process it spawns to generate a key.
This key is available only in a
.BR request\-key (8)-style
program that was passed an authorization key by the kernel and
ceases to be available once the requested key has been instantiated; see
.BR request_key (2).
.TP
.BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)"
.\"            commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
This specifies the key ID for the
.BR request_key (2)
destination keyring.
This keyring is available only in a
.BR request\-key (8)-style
program that was passed an authorization key by the kernel and
ceases to be available once the requested key has been instantiated; see
.BR request_key (2).
.RE
.IP
The behavior if the key specified in
.I arg2
does not exist depends on the value of
.I arg3
(cast to
.IR int ).
If
.I arg3
contains a nonzero value, then\[em]if it is appropriate to do so
(e.g., when looking up the user, user-session, or session key)\[em]a new key
is created and its real key ID returned as the function result.
.\" The keyctl_get_keyring_ID.3 page says that a new key
.\" "will be created *if it is appropriate to do so**. What is the
.\" determiner for appropriate?
.\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY
.\" wouldn't get created but user/user-session/session keyring would
.\" be created.
Otherwise, the operation fails with the error
.BR ENOKEY .
.IP
If a valid key ID is specified in
.IR arg2 ,
and the key exists, then this operation simply returns the key ID.
If the key does not exist, the call fails with error
.BR ENOKEY .
.IP
The caller must have
.I search
permission on a keyring in order for it to be found.
.IP
The arguments
.I arg4
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_get_keyring_ID (3).
.TP
.BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)"
Replace the session keyring this process subscribes to with
a new session keyring.
.\" This may be useful in conjunction with some sort of
.\" session management framework that is employed by the application.
.IP
If
.I arg2
is NULL,
an anonymous keyring with the description "_ses" is created
and the process is subscribed to that keyring as its session keyring,
displacing the previous session keyring.
.IP
Otherwise,
.I arg2
(cast to
.IR "char\ *" )
is treated as the description (name) of a keyring,
and the behavior is as follows:
.RS
.IP \[bu] 3
If a keyring with a matching description exists,
the process will attempt to subscribe to that keyring
as its session keyring if possible;
if that is not possible, an error is returned.
In order to subscribe to the keyring,
the caller must have
.I search
permission on the keyring.
.IP \[bu]
If a keyring with a matching description does not exist,
then a new keyring with the specified description is created,
and the process is subscribed to that keyring as its session keyring.
.RE
.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_join_session_keyring (3).
.TP
.BR KEYCTL_UPDATE " (since Linux 2.6.10)"
Update a key's data payload.
.IP
The
.I arg2
argument (cast to
.IR key_serial_t )
specifies the ID of the key to be updated.
The
.I arg3
argument (cast to
.IR "void\ *" )
points to the new payload and
.I arg4
(cast to
.IR size_t )
contains the new payload size in bytes.
.IP
The caller must have
.I write
permission on the key specified and the key type must support updating.
.IP
A negatively instantiated key (see the description of
.BR KEYCTL_REJECT )
can be positively instantiated with this operation.
.IP
The
.I arg5
argument is ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_update (3).
.TP
.BR KEYCTL_REVOKE " (since Linux 2.6.10)"
Revoke the key with the ID provided in
.I arg2
(cast to
.IR key_serial_t ).
The key is scheduled for garbage collection;
it will no longer be findable,
and will be unavailable for further operations.
Further attempts to use the key will fail with the error
.BR EKEYREVOKED .
.IP
The caller must have
.I write
or
.I setattr
permission on the key.
.\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM
.\" error for KEYCTL_REVOKE. Does this need to be documented?
.\" David Howells: No significance for user space.
.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_revoke (3).
.TP
.BR KEYCTL_CHOWN " (since Linux 2.6.10)"
Change the ownership (user and group ID) of a key.
.IP
The
.I arg2
argument (cast to
.IR key_serial_t )
contains the key ID.
The
.I arg3
argument (cast to
.IR uid_t )
contains the new user ID (or \-1 in case the user ID shouldn't be changed).
The
.I arg4
argument (cast to
.IR gid_t )
contains the new group ID (or \-1 in case the group ID shouldn't be changed).
.IP
The key must grant the caller
.I setattr
permission.
.IP
For the UID to be changed, or for the GID to be changed to a group
the caller is not a member of, the caller must have the
.B CAP_SYS_ADMIN
capability (see
.BR capabilities (7)).
.IP
If the UID is to be changed, the new user must have sufficient
quota to accept the key.
The quota deduction will be removed from the old user
to the new user should the UID be changed.
.IP
The
.I arg5
argument is ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_chown (3).
.TP
.BR KEYCTL_SETPERM " (since Linux 2.6.10)"
Change the permissions of the key with the ID provided in the
.I arg2
argument (cast to
.IR key_serial_t )
to the permissions provided in the
.I arg3
argument (cast to
.IR key_perm_t ).
.IP
If the caller doesn't have the
.B CAP_SYS_ADMIN
capability, it can change permissions only for the keys it owns.
(More precisely: the caller's filesystem UID must match the UID of the key.)
.IP
The key must grant
.I setattr
permission to the caller
.I regardless
of the caller's capabilities.
.\" FIXME Above, is it really intended that a privileged process can't
.\" override the lack of the 'setattr' permission?
.IP
The permissions in
.I arg3
specify masks of available operations
for each of the following user categories:
.RS
.TP
.IR possessor " (since Linux 2.6.14)"
.\" commit 664cceb0093b755739e56572b836a99104ee8a75
This is the permission granted to a process that possesses the key
(has it attached searchably to one of the process's keyrings);
see
.BR keyrings (7).
.TP
.I user
This is the permission granted to a process
whose filesystem UID matches the UID of the key.
.TP
.I group
This is the permission granted to a process
whose filesystem GID or any of its supplementary GIDs
matches the GID of the key.
.TP
.I other
This is the permission granted to other processes
that do not match the
.I user
and
.I group
categories.
.RE
.IP
The
.IR user ,
.IR group ,
and
.I other
categories are exclusive: if a process matches the
.I user
category, it will not receive permissions granted in the
.I group
category; if a process matches the
.I user
or
.I group
category, then it will not receive permissions granted in the
.I other
category.
.IP
The
.I possessor
category grants permissions that are cumulative with the grants from the
.IR user ,
.IR group ,
or
.I other
category.
.IP
Each permission mask is eight bits in size,
with only six bits currently used.
The available permissions are:
.RS
.TP
.I view
This permission allows reading attributes of a key.
.IP
This permission is required for the
.B KEYCTL_DESCRIBE
operation.
.IP
The permission bits for each category are
.BR KEY_POS_VIEW ,
.BR KEY_USR_VIEW ,
.BR KEY_GRP_VIEW ,
and
.BR KEY_OTH_VIEW .
.TP
.I read
This permission allows reading a key's payload.
.IP
This permission is required for the
.B KEYCTL_READ
operation.
.IP
The permission bits for each category are
.BR KEY_POS_READ ,
.BR KEY_USR_READ ,
.BR KEY_GRP_READ ,
and
.BR KEY_OTH_READ .
.TP
.I write
This permission allows update or instantiation of a key's payload.
For a keyring, it allows keys to be linked and unlinked from the keyring,
.IP
This permission is required for the
.BR KEYCTL_UPDATE ,
.BR KEYCTL_REVOKE ,
.BR KEYCTL_CLEAR ,
.BR KEYCTL_LINK ,
and
.B KEYCTL_UNLINK
operations.
.IP
The permission bits for each category are
.BR KEY_POS_WRITE ,
.BR KEY_USR_WRITE ,
.BR KEY_GRP_WRITE ,
and
.BR KEY_OTH_WRITE .
.TP
.I search
This permission allows keyrings to be searched and keys to be found.
Searches can recurse only into nested keyrings that have
.I search
permission set.
.IP
This permission is required for the
.BR KEYCTL_GET_KEYRING_ID ,
.BR KEYCTL_JOIN_SESSION_KEYRING ,
.BR KEYCTL_SEARCH ,
and
.B KEYCTL_INVALIDATE
operations.
.IP
The permission bits for each category are
.BR KEY_POS_SEARCH ,
.BR KEY_USR_SEARCH ,
.BR KEY_GRP_SEARCH ,
and
.BR KEY_OTH_SEARCH .
.TP
.I link
This permission allows a key or keyring to be linked to.
.IP
This permission is required for the
.B KEYCTL_LINK
and
.B KEYCTL_SESSION_TO_PARENT
operations.
.IP
The permission bits for each category are
.BR KEY_POS_LINK ,
.BR KEY_USR_LINK ,
.BR KEY_GRP_LINK ,
and
.BR KEY_OTH_LINK .
.TP
.IR setattr " (since Linux 2.6.15)."
This permission allows a key's UID, GID, and permissions mask to be changed.
.IP
This permission is required for the
.BR KEYCTL_REVOKE ,
.BR KEYCTL_CHOWN ,
and
.B KEYCTL_SETPERM
operations.
.IP
The permission bits for each category are
.BR KEY_POS_SETATTR ,
.BR KEY_USR_SETATTR ,
.BR KEY_GRP_SETATTR ,
and
.BR KEY_OTH_SETATTR .
.RE
.IP
As a convenience, the following macros are defined as masks for
all of the permission bits in each of the user categories:
.BR KEY_POS_ALL ,
.BR KEY_USR_ALL ,
.BR KEY_GRP_ALL ,
and
.BR KEY_OTH_ALL .
.IP
The
.I arg4
and
.I arg5
arguments are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_setperm (3).
.TP
.BR KEYCTL_DESCRIBE " (since Linux 2.6.10)"
Obtain a string describing the attributes of a specified key.
.IP
The ID of the key to be described is specified in
.I arg2
(cast to
.IR key_serial_t ).
The descriptive string is returned in the buffer pointed to by
.I arg3
(cast to
.IR char\~* );
.I arg4
(cast to
.IR size_t )
specifies the size of that buffer in bytes.
.IP
The key must grant the caller
.I view
permission.
.IP
The returned string is null-terminated and
contains the following information about the key:
.IP
.in +4n
.IR type ; uid ; gid ; perm ; description
.in
.IP
In the above,
.I type
and
.I description
are strings,
.I uid
and
.I gid
are decimal strings, and
.I perm
is a hexadecimal permissions mask.
The descriptive string is written with the following format:
.IP
.in +4n
.EX
%s;%d;%d;%08x;%s
.EE
.in
.IP
.B Note: the intention is that the descriptive string should
.B be extensible in future kernel versions.
In particular, the
.I description
field will not contain semicolons;
.\" FIXME But, the kernel does not enforce the requirement
.\" that the key description contains no semicolons!
.\" So, user space has no guarantee here??
.\" Either something more needs to be said here,
.\" or a kernel fix is required.
it should be parsed by working backwards from the end of the string
to find the last semicolon.
This allows future semicolon-delimited fields to be inserted
in the descriptive string in the future.
.IP
Writing to the buffer is attempted only when
.I arg3
is non-NULL and the specified buffer size
is large enough to accept the descriptive string
(including the terminating null byte).
.\" Function commentary says it copies up to buflen bytes, but see the
.\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
.\" security/keyctl.c
In order to determine whether the buffer size was too small,
check to see if the return value of the operation is greater than
.IR arg4 .
.IP
The
.I arg5
argument is ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_describe (3).
.TP
.B KEYCTL_CLEAR
Clear the contents of (i.e., unlink all keys from) a keyring.
.IP
The ID of the key
(which must be of keyring type)
.\" or the error ENOTDIR results
is provided in
.I arg2
(cast to
.IR key_serial_t ).
.\" According to Documentation/security/keys.txt:
.\"     This function can also be used to clear special kernel keyrings if they
.\"     are appropriately marked if the user has CAP_SYS_ADMIN capability.  The
.\"     DNS resolver cache keyring is an example of this.
.IP
The caller must have
.I write
permission on the keyring.
.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_clear (3).
.TP
.BR KEYCTL_LINK " (since Linux 2.6.10)"
Create a link from a keyring to a key.
.IP
The key to be linked is specified in
.I arg2
(cast to
.IR key_serial_t );
the keyring is specified in
.I arg3
(cast to
.IR key_serial_t ).
.IP
If a key with the same type and description is already linked in the keyring,
then that key is displaced from the keyring.
.IP
Before creating the link,
the kernel checks the nesting of the keyrings and returns appropriate errors
if the link would produce a cycle
or if the nesting of keyrings would be too deep
(The limit on the nesting of keyrings is determined by the kernel constant
.BR KEYRING_SEARCH_MAX_DEPTH ,
defined with the value 6, and is necessary to prevent overflows
on the kernel stack when recursively searching keyrings).
.IP
The caller must have
.I link
permission on the key being added and
.I write
permission on the keyring.
.IP
The arguments
.I arg4
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_link (3).
.TP
.BR KEYCTL_UNLINK " (since Linux 2.6.10)"
Unlink a key from a keyring.
.IP
The ID of the key to be unlinked is specified in
.I arg2
(cast to
.IR key_serial_t );
the ID of the keyring from which it is to be unlinked is specified in
.I arg3
(cast to
.IR key_serial_t ).
.IP
If the key is not currently linked into the keyring, an error results.
.IP
The caller must have
.I write
permission on the keyring from which the key is being removed.
.IP
If the last link to a key is removed,
then that key will be scheduled for destruction.
.IP
The arguments
.I arg4
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_unlink (3).
.TP
.BR KEYCTL_SEARCH " (since Linux 2.6.10)"
Search for a key in a keyring tree,
returning its ID and optionally linking it to a specified keyring.
.IP
The tree to be searched is specified by passing
the ID of the head keyring in
.I arg2
(cast to
.IR key_serial_t ).
The search is performed breadth-first and recursively.
.IP
The
.I arg3
and
.I arg4
arguments specify the key to be searched for:
.I arg3
(cast as
.IR char\~* )
contains the key type
(a null-terminated character string up to 32 bytes in size,
including the terminating null byte), and
.I arg4
(cast as
.IR char\~* )
contains the description of the key
(a null-terminated character string up to 4096 bytes in size,
including the terminating null byte).
.IP
The source keyring must grant
.I search
permission to the caller.
When performing the recursive search, only keyrings that grant the caller
.I search
permission will be searched.
Only keys with for which the caller has
.I search
permission can be found.
.IP
If the key is found, its ID is returned as the function result.
.IP
If the key is found and
.I arg5
(cast to
.IR key_serial_t )
is nonzero, then, subject to the same constraints and rules as
.BR KEYCTL_LINK ,
the key is linked into the keyring whose ID is specified in
.IR arg5 .
If the destination keyring specified in
.I arg5
already contains a link to a key that has the same type and description,
then that link will be displaced by a link to
the key found by this operation.
.IP
Instead of valid existing keyring IDs, the source
.RI ( arg2 )
and destination
.RI ( arg5 )
keyrings can be one of the special keyring IDs listed under
.BR KEYCTL_GET_KEYRING_ID .
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_search (3).
.TP
.BR KEYCTL_READ " (since Linux 2.6.10)"
Read the payload data of a key.
.IP
The ID of the key whose payload is to be read is specified in
.I arg2
(cast to
.IR key_serial_t ).
This can be the ID of an existing key,
or any of the special key IDs listed for
.BR KEYCTL_GET_KEYRING_ID .
.\" including KEY_SPEC_REQKEY_AUTH_KEY
.IP
The payload is placed in the buffer pointed by
.I arg3
(cast to
.IR "char\ *" );
the size of that buffer must be specified in
.I arg4
(cast to
.IR size_t ).
.IP
The returned data will be processed for presentation
according to the key type.
For example, a keyring will return an array of
.I key_serial_t
entries representing the IDs of all the keys that are linked to it.
The
.I user
key type will return its data as is.
If a key type does not implement this function,
the operation fails with the error
.BR EOPNOTSUPP .
.IP
If
.I arg3
is not NULL,
as much of the payload data as will fit is copied into the buffer.
On a successful return,
the return value is always the total size of the payload data.
To determine whether the buffer was of sufficient size,
check to see that the return value is less than or equal to
the value supplied in
.IR arg4 .
.IP
The key must either grant the caller
.I read
permission, or grant the caller
.I search
permission when searched for from the process keyrings
(i.e., the key is possessed).
.IP
The
.I arg5
argument is ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_read (3).
.TP
.BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)"
(Positively) instantiate an uninstantiated key with a specified payload.
.IP
The ID of the key to be instantiated is provided in
.I arg2
(cast to
.IR key_serial_t ).
.IP
The key payload is specified in the buffer pointed to by
.I arg3
(cast to
.IR "void\ *");
the size of that buffer is specified in
.I arg4
(cast to
.IR size_t ).
.IP
The payload may be a null pointer and the buffer size may be 0
if this is supported by the key type (e.g., it is a keyring).
.IP
The operation may be fail if the payload data is in the wrong format
or is otherwise invalid.
.IP
If
.I arg5
(cast to
.IR key_serial_t )
is nonzero, then, subject to the same constraints and rules as
.BR KEYCTL_LINK ,
the instantiated key is linked into the keyring whose ID specified in
.IR arg5 .
.IP
The caller must have the appropriate authorization key,
and once the uninstantiated key has been instantiated,
the authorization key is revoked.
In other words, this operation is available only from a
.BR request\-key (8)-style
program.
See
.BR request_key (2)
for an explanation of uninstantiated keys and key instantiation.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_instantiate (3).
.TP
.BR KEYCTL_NEGATE " (since Linux 2.6.10)"
Negatively instantiate an uninstantiated key.
.IP
This operation is equivalent to the call:
.IP
.in +4n
.EX
keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
.EE
.in
.IP
The
.I arg5
argument is ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_negate (3).
.TP
.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
Set the default keyring to which implicitly requested keys
will be linked for this thread, and return the previous setting.
Implicit key requests are those made by internal kernel components,
.\" I.e., calls to the kernel's internal request_key() interface,
.\" which is distinct from the request_key(2) system call (which
.\" ultimately employs the kernel-internal interface).
such as can occur when, for example, opening files
on an AFS or NFS filesystem.
Setting the default keyring also has an effect when requesting
a key from user space; see
.BR request_key (2)
for details.
.IP
The
.I arg2
argument (cast to
.IR int )
should contain one of the following values,
to specify the new default keyring:
.RS
.TP
.B KEY_REQKEY_DEFL_NO_CHANGE
Don't change the default keyring.
This can be used to discover the current default keyring
(without changing it).
.TP
.B KEY_REQKEY_DEFL_DEFAULT
This selects the default behaviour,
which is to use the thread-specific keyring if there is one,
otherwise the process-specific keyring if there is one,
otherwise the session keyring if there is one,
otherwise the UID-specific session keyring,
otherwise the user-specific keyring.
.TP
.B KEY_REQKEY_DEFL_THREAD_KEYRING
Use the thread-specific keyring
.RB ( thread\-keyring (7))
as the new default keyring.
.TP
.B KEY_REQKEY_DEFL_PROCESS_KEYRING
Use the process-specific keyring
.RB ( process\-keyring (7))
as the new default keyring.
.TP
.B KEY_REQKEY_DEFL_SESSION_KEYRING
Use the session-specific keyring
.RB ( session\-keyring (7))
as the new default keyring.
.TP
.B KEY_REQKEY_DEFL_USER_KEYRING
Use the UID-specific keyring
.RB ( user\-keyring (7))
as the new default keyring.
.TP
.B KEY_REQKEY_DEFL_USER_SESSION_KEYRING
Use the UID-specific session keyring
.RB ( user\-session\-keyring (7))
as the new default keyring.
.TP
.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
Use the requestor keyring.
.\" FIXME The preceding explanation needs to be expanded.
.\" Is the following correct:
.\"
.\"	The requestor keyring is the dest_keyring that
.\"	was supplied to a call to request_key(2)?
.\"
.\" David Howells said: to be checked
.RE
.IP
All other values are invalid.
.\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING)
.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.I arg5
are ignored.
.IP
The setting controlled by this operation is inherited by the child of
.BR fork (2)
and preserved across
.BR  execve (2).
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_set_reqkey_keyring (3).
.TP
.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
Set a timeout on a key.
.IP
The ID of the key is specified in
.I arg2
(cast to
.IR key_serial_t ).
The timeout value, in seconds from the current time,
is specified in
.I arg3
(cast to
.IR "unsigned int" ).
The timeout is measured against the realtime clock.
.IP
Specifying the timeout value as 0 clears any existing timeout on the key.
.IP
The
.I /proc/keys
file displays the remaining time until each key will expire.
(This is the only method of discovering the timeout on a key.)
.IP
The caller must either have the
.I setattr
permission on the key
or hold an instantiation authorization token for the key (see
.BR request_key (2)).
.IP
The key and any links to the key will be
automatically garbage collected after the timeout expires.
Subsequent attempts to access the key will then fail with the error
.BR EKEYEXPIRED .
.IP
This operation cannot be used to set timeouts on revoked, expired,
or negatively instantiated keys.
.IP
The arguments
.I arg4
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_set_timeout (3).
.TP
.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
Assume (or divest) the authority for the calling thread
to instantiate a key.
.IP
The
.I arg2
argument (cast to
.IR key_serial_t )
specifies either a nonzero key ID to assume authority,
or the value 0 to divest authority.
.IP
If
.I arg2
is nonzero, then it specifies the ID of an uninstantiated key for which
authority is to be assumed.
That key can then be instantiated using one of
.BR KEYCTL_INSTANTIATE ,
.BR KEYCTL_INSTANTIATE_IOV ,
.BR KEYCTL_REJECT ,
or
.BR KEYCTL_NEGATE .
Once the key has been instantiated,
the thread is automatically divested of authority to instantiate the key.
.IP
Authority over a key can be assumed only if the calling thread has present
in its keyrings the authorization key that is
associated with the specified key.
(In other words, the
.B KEYCTL_ASSUME_AUTHORITY
operation is available only from a
.BR request\-key (8)-style
program; see
.BR request_key (2)
for an explanation of how this operation is used.)
The caller must have
.I search
permission on the authorization key.
.IP
If the specified key has a matching authorization key,
then the ID of that key is returned.
The authorization key can be read
.RB ( KEYCTL_READ )
to obtain the callout information passed to
.BR request_key (2).
.IP
If the ID given in
.I arg2
is 0, then the currently assumed authority is cleared (divested),
and the value 0 is returned.
.IP
The
.B KEYCTL_ASSUME_AUTHORITY
mechanism allows a program such as
.BR request\-key (8)
to assume the necessary authority to instantiate a new uninstantiated key
that was created as a consequence of a call to
.BR request_key (2).
For further information, see
.BR request_key (2)
and the kernel source file
.IR Documentation/security/keys\-request\-key.txt .
.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_assume_authority (3).
.TP
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
Get the LSM (Linux Security Module) security label of the specified key.
.IP
The ID of the key whose security label is to be fetched is specified in
.I arg2
(cast to
.IR key_serial_t ).
The security label (terminated by a null byte)
will be placed in the buffer pointed to by
.I arg3
argument (cast to
.IR "char\ *" );
the size of the buffer must be provided in
.I arg4
(cast to
.IR size_t ).
.IP
If
.I arg3
is specified as NULL or the buffer size specified in
.I arg4
is too small, the full size of the security label string
(including the terminating null byte)
is returned as the function result,
and nothing is copied to the buffer.
.IP
The caller must have
.I view
permission on the specified key.
.IP
The returned security label string will be rendered in a form appropriate
to the LSM in force.
For example, with SELinux, it may look like:
.IP
.in +4n
.EX
unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
.EE
.in
.IP
If no LSM is currently in force,
then an empty string is placed in the buffer.
.IP
The
.I arg5
argument is ignored.
.IP
This operation is exposed by
.I libkeyutils
via the functions
.BR keyctl_get_security (3)
and
.BR keyctl_get_security_alloc (3).
.TP
.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
Replace the session keyring to which the
.I parent
of the calling process
subscribes with the session keyring of the calling process.
.\" What is the use case for KEYCTL_SESSION_TO_PARENT?
.\" David Howells: the Process Authentication Groups people requested this,
.\" but then didn't use it; maybe there are no users.
.IP
The keyring will be replaced in the parent process at the point
where the parent next transitions from kernel space to user space.
.IP
The keyring must exist and must grant the caller
.I link
permission.
The parent process must be single-threaded and have
the same effective ownership as this process
and must not be set-user-ID or set-group-ID.
The UID of the parent process's existing session keyring (f it has one),
as well as the UID of the caller's session keyring
much match the caller's effective UID.
.IP
The fact that it is the parent process that is affected by this operation
allows a program such as the shell to start a child process that
uses this operation to change the shell's session keyring.
(This is what the
.BR keyctl (1)
.B new_session
command does.)
.IP
The arguments
.IR arg2 ,
.IR arg3 ,
.IR arg4 ,
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_session_to_parent (3).
.TP
.BR KEYCTL_REJECT " (since Linux 2.6.39)"
.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
Mark a key as negatively instantiated and set an expiration timer
on the key.
This operation provides a superset of the functionality of the earlier
.B KEYCTL_NEGATE
operation.
.IP
The ID of the key that is to be negatively instantiated is specified in
.I arg2
(cast to
.IR key_serial_t ).
The
.I arg3
(cast to
.IR "unsigned int" )
argument specifies the lifetime of the key, in seconds.
The
.I arg4
argument (cast to
.IR "unsigned int" )
specifies the error to be returned when a search hits this key;
typically, this is one of
.BR EKEYREJECTED ,
.BR EKEYREVOKED ,
or
.BR EKEYEXPIRED .
.IP
If
.I arg5
(cast to
.IR key_serial_t )
is nonzero, then, subject to the same constraints and rules as
.BR KEYCTL_LINK ,
the negatively instantiated key is linked into the keyring
whose ID is specified in
.IR arg5 .
.IP
The caller must have the appropriate authorization key.
In other words, this operation is available only from a
.BR request\-key (8)-style
program.
See
.BR request_key (2).
.IP
The caller must have the appropriate authorization key,
and once the uninstantiated key has been instantiated,
the authorization key is revoked.
In other words, this operation is available only from a
.BR request\-key (8)-style
program.
See
.BR request_key (2)
for an explanation of uninstantiated keys and key instantiation.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_reject (3).
.TP
.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
.\" commit ee009e4a0d4555ed522a631bae9896399674f063
Instantiate an uninstantiated key with a payload specified
via a vector of buffers.
.IP
This operation is the same as
.BR KEYCTL_INSTANTIATE ,
but the payload data is specified as an array of
.I iovec
structures (see
.BR iovec (3type)).
.IP
The pointer to the payload vector is specified in
.I arg3
(cast as
.IR "const struct iovec\~*" ).
The number of items in the vector is specified in
.I arg4
(cast as
.IR "unsigned int" ).
.IP
The
.I arg2
(key ID)
and
.I arg5
(keyring ID)
are interpreted as for
.BR KEYCTL_INSTANTIATE .
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_instantiate_iov (3).
.TP
.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
.\" commit fd75815f727f157a05f4c96b5294a4617c0557da
Mark a key as invalid.
.IP
The ID of the key to be invalidated is specified in
.I arg2
(cast to
.IR key_serial_t ).
.IP
To invalidate a key,
the caller must have
.I search
permission on the key.
.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys
.IP
This operation marks the key as invalid
and schedules immediate garbage collection.
The garbage collector removes the invalidated key from all keyrings and
deletes the key when its reference count reaches zero.
After this operation,
the key will be ignored by all searches,
even if it is not yet deleted.
.IP
Keys that are marked invalid become invisible to normal key operations
immediately, though they are still visible in
.I /proc/keys
(marked with an 'i' flag)
until they are actually removed.
.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_invalidate (3).
.TP
.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
Get the persistent keyring
.RB ( persistent\-keyring (7))
for a specified user and link it to a specified keyring.
.IP
The user ID is specified in
.I arg2
(cast to
.IR uid_t ).
If the value \-1 is specified, the caller's real user ID is used.
The ID of the destination keyring is specified in
.I arg3
(cast to
.IR key_serial_t ).
.IP
The caller must have the
.B CAP_SETUID
capability in its user namespace in order to fetch the persistent keyring
for a user ID that does not match either the real or effective user ID
of the caller.
.IP
If the call is successful,
a link to the persistent keyring is added to the keyring
whose ID was specified in
.IR arg3 .
.IP
The caller must have
.I write
permission on the keyring.
.IP
The persistent keyring will be created by the kernel
if it does not yet exist.
.IP
Each time the
.B KEYCTL_GET_PERSISTENT
operation is performed, the persistent keyring will
have its expiration timeout reset to the value in:
.IP
.in +4n
.EX
/proc/sys/kernel/keys/persistent_keyring_expiry
.EE
.in
.IP
Should the timeout be reached,
the persistent keyring will be removed and
everything it pins can then be garbage collected.
.IP
Persistent keyrings were added in Linux 3.13.
.IP
The arguments
.I arg4
and
.I arg5
are ignored.
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_get_persistent (3).
.TP
.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
.\" commit ddbb41148724367394d0880c516bfaeed127b52e
Compute a Diffie-Hellman shared secret or public key,
optionally applying key derivation function (KDF) to the result.
.IP
The
.I arg2
argument is a pointer to a set of parameters containing
serial numbers for three
.I \[dq]user\[dq]
keys used in the Diffie-Hellman calculation,
packaged in a structure of the following form:
.IP
.in +4n
.EX
struct keyctl_dh_params {
    int32_t private; /* The local private key */
    int32_t prime; /* The prime, known to both parties */
    int32_t base;  /* The base integer: either a shared
                      generator or the remote public key */
};
.EE
.in
.IP
Each of the three keys specified in this structure must grant the caller
.I read
permission.
The payloads of these keys are used to calculate the Diffie-Hellman
result as:
.IP
.in +4n
.EX
base \[ha] private mod prime
.EE
.in
.IP
If the base is the shared generator, the result is the local public key.
If the base is the remote public key, the result is the shared secret.
.IP
The
.I arg3
argument (cast to
.IR char\~* )
points to a buffer where the result of the calculation is placed.
The size of that buffer is specified in
.I arg4
(cast to
.IR size_t ).
.IP
The buffer must be large enough to accommodate the output data,
otherwise an error is returned.
If
.I arg4
is specified zero,
in which case the buffer is not used and
the operation returns the minimum required buffer size
(i.e., the length of the prime).
.IP
Diffie-Hellman computations can be performed in user space,
but require a multiple-precision integer (MPI) library.
Moving the implementation into the kernel gives access to
the kernel MPI implementation,
and allows access to secure or acceleration hardware.
.IP
Adding support for DH computation to the
.BR keyctl ()
system call was considered a good fit due to the DH algorithm's use
for deriving shared keys;
it also allows the type of the key to determine
which DH implementation (software or hardware) is appropriate.
.\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8
.IP
If the
.I arg5
argument is
.BR NULL ,
then the DH result itself is returned.
Otherwise (since Linux 4.12), it is a pointer to a structure which specifies
parameters of the KDF operation to be applied:
.IP
.in +4n
.EX
struct keyctl_kdf_params {
    char *hashname;     /* Hash algorithm name */
    char *otherinfo;    /* SP800\-56A OtherInfo */
    __u32 otherinfolen; /* Length of otherinfo data */
    __u32 __spare[8];   /* Reserved */
};
.EE
.in
.IP
The
.I hashname
field is a null-terminated string which specifies a hash name
(available in the kernel's crypto API; the list of the hashes available
is rather tricky to observe; please refer to the
.UR https://www.kernel.org\:/doc\:/html\:/latest\:/crypto\:/architecture.html
"Kernel Crypto API Architecture"
.UE
documentation for the information regarding how hash names are constructed and
your kernel's source and configuration regarding what ciphers
and templates with type
.B CRYPTO_ALG_TYPE_SHASH
are available)
to be applied to DH result in KDF operation.
.IP
The
.I otherinfo
field is an
.I OtherInfo
data as described in SP800-56A section 5.8.1.2 and is algorithm-specific.
This data is concatenated with the result of DH operation and is provided as
an input to the KDF operation.
Its size is provided in the
.I otherinfolen
field and is limited by
.B KEYCTL_KDF_MAX_OI_LEN
constant that defined in
.I security/keys/internal.h
to a value of 64.
.IP
The
.B __spare
field is currently unused.
.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
It was ignored until Linux 4.13 (but still should be
user-addressable since it is copied to the kernel),
and should contain zeros since Linux 4.13.
.IP
The KDF implementation complies with SP800-56A as well
as with SP800-108 (the counter KDF).
.IP
.\" keyutils commit 742c9d7b94051d3b21f9f61a73ed6b5f3544cb82
.\" keyutils commit d68a981e5db41d059ac782071c35d1e8f3aaf61c
This operation is exposed by
.I libkeyutils
(from
.I libkeyutils
1.5.10 onwards) via the functions
.BR keyctl_dh_compute (3)
and
.BR keyctl_dh_compute_alloc (3).
.TP
.BR KEYCTL_RESTRICT_KEYRING " (since Linux 4.12)"
.\" commit 6563c91fd645556c7801748f15bc727c77fcd311
.\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9
Apply a key-linking restriction to the keyring with the ID provided in
.I arg2
(cast to
.IR key_serial_t ).
The caller must have
.I setattr
permission on the key.
If
.I arg3
is NULL, any attempt to add a key to the keyring is blocked;
otherwise it contains a pointer to a string with a key type name and
.I arg4
contains a pointer to string that describes the type-specific restriction.
As of Linux 4.12, only the type "asymmetric" has restrictions defined:
.RS
.TP
.B builtin_trusted
Allows only keys that are signed by a key linked to the built-in keyring
(".builtin_trusted_keys").
.TP
.B builtin_and_secondary_trusted
Allows only keys that are signed by a key linked to the secondary keyring
(".secondary_trusted_keys") or, by extension, a key in a built-in keyring,
as the latter is linked to the former.
.TP
.BI key_or_keyring: key
.TQ
.BI key_or_keyring: key :chain
If
.I key
specifies the ID of a key of type "asymmetric",
then only keys that are signed by this key are allowed.
.IP
If
.I key
specifies the ID of a keyring,
then only keys that are signed by a key linked
to this keyring are allowed.
.IP
If ":chain" is specified, keys that are signed by a keys linked to the
destination keyring (that is, the keyring with the ID specified in the
.I arg2
argument) are also allowed.
.RE
.IP
Note that a restriction can be configured only once for the specified keyring;
once a restriction is set, it can't be overridden.
.IP
The argument
.I arg5
is ignored.
.\" FIXME Document KEYCTL_RESTRICT_KEYRING, added in Linux 4.12
.\"     commit 6563c91fd645556c7801748f15bc727c77fcd311
.\"     Author: Mat Martineau <mathew.j.martineau@linux.intel.com>
.\" See Documentation/security/keys.txt
.SH RETURN VALUE
For a successful call, the return value depends on the operation:
.TP
.B KEYCTL_GET_KEYRING_ID
The ID of the requested keyring.
.TP
.B KEYCTL_JOIN_SESSION_KEYRING
The ID of the joined session keyring.
.TP
.B KEYCTL_DESCRIBE
The size of the description (including the terminating null byte),
irrespective of the provided buffer size.
.TP
.B KEYCTL_SEARCH
The ID of the key that was found.
.TP
.B KEYCTL_READ
The amount of data that is available in the key,
irrespective of the provided buffer size.
.TP
.B KEYCTL_SET_REQKEY_KEYRING
The ID of the previous default keyring
to which implicitly requested keys were linked
(one of
.BR KEY_REQKEY_DEFL_USER_* ).
.TP
.B KEYCTL_ASSUME_AUTHORITY
Either 0, if the ID given was 0,
or the ID of the authorization key matching the specified key,
if a nonzero key ID was provided.
.TP
.B KEYCTL_GET_SECURITY
The size of the LSM security label string
(including the terminating null byte),
irrespective of the provided buffer size.
.TP
.B KEYCTL_GET_PERSISTENT
The ID of the persistent keyring.
.TP
.B KEYCTL_DH_COMPUTE
The number of bytes copied to the buffer, or, if
.I arg4
is 0, the required buffer size.
.TP
All other operations
Zero.
.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EACCES
The requested operation wasn't permitted.
.TP
.B EAGAIN
.I operation
was
.B KEYCTL_DH_COMPUTE
and there was an error during crypto module initialization.
.TP
.B EDEADLK
.I operation
was
.B KEYCTL_LINK
and the requested link would result in a cycle.
.TP
.B EDEADLK
.I operation
was
.B KEYCTL_RESTRICT_KEYRING
and the requested keyring restriction would result in a cycle.
.TP
.B EDQUOT
The key quota for the caller's user would be exceeded by creating a key or
linking it to the keyring.
.TP
.B EEXIST
.I operation
was
.B KEYCTL_RESTRICT_KEYRING
and keyring provided in
.I arg2
argument already has a restriction set.
.TP
.B EFAULT
.I operation
was
.B KEYCTL_DH_COMPUTE
and one of the following has failed:
.RS
.IP \[bu] 3
copying of the
.IR "struct keyctl_dh_params" ,
provided in the
.I arg2
argument, from user space;
.IP \[bu]
copying of the
.IR "struct keyctl_kdf_params" ,
provided in the non-NULL
.I arg5
argument, from user space
(in case kernel supports performing KDF operation on DH operation result);
.IP \[bu]
copying of data pointed by the
.I hashname
field of the
.I "struct keyctl_kdf_params"
from user space;
.IP \[bu]
copying of data pointed by the
.I otherinfo
field of the
.I struct keyctl_kdf_params
from user space if the
.I otherinfolen
field was nonzero;
.IP \[bu]
copying of the result to user space.
.RE
.TP
.B EINVAL
.I operation
was
.B KEYCTL_SETPERM
and an invalid permission bit was specified in
.IR arg3 .
.TP
.B EINVAL
.I operation
was
.B KEYCTL_SEARCH
and the size of the description in
.I arg4
(including the terminating null byte) exceeded 4096 bytes.
.TP
.B EINVAL
size of the string (including the terminating null byte) specified in
.I arg3
(the key type)
or
.I arg4
(the key description)
exceeded the limit (32 bytes and 4096 bytes respectively).
.TP
.BR EINVAL " (before Linux 4.12)"
.I operation
was
.BR KEYCTL_DH_COMPUTE ,
argument
.I arg5
was non-NULL.
.TP
.B EINVAL
.I operation
was
.B KEYCTL_DH_COMPUTE
And the digest size of the hashing algorithm supplied is zero.
.TP
.B EINVAL
.I operation
was
.B KEYCTL_DH_COMPUTE
and the buffer size provided is not enough to hold the result.
Provide 0 as a buffer size in order to obtain the minimum buffer size.
.TP
.B EINVAL
.I operation
was
.B KEYCTL_DH_COMPUTE
and the hash name provided in the
.I hashname
field of the
.I struct keyctl_kdf_params
pointed by
.I arg5
argument is too big (the limit is implementation-specific and varies between
kernel versions, but it is deemed big enough for all valid algorithm names).
.TP
.B EINVAL
.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
.I operation
was
.B KEYCTL_DH_COMPUTE
and the
.I __spare
field of the
.I struct keyctl_kdf_params
provided in the
.I arg5
argument contains nonzero values.
.TP
.B EKEYEXPIRED
An expired key was found or specified.
.TP
.B EKEYREJECTED
A rejected key was found or specified.
.TP
.B EKEYREVOKED
A revoked key was found or specified.
.TP
.B ELOOP
.I operation
was
.B KEYCTL_LINK
and the requested link would cause the maximum nesting depth
for keyrings to be exceeded.
.TP
.B EMSGSIZE
.I operation
was
.B KEYCTL_DH_COMPUTE
and the buffer length exceeds
.B KEYCTL_KDF_MAX_OUTPUT_LEN
(which is 1024 currently)
or the
.I otherinfolen
field of the
.I struct keyctl_kdf_parms
passed in
.I arg5
exceeds
.B KEYCTL_KDF_MAX_OI_LEN
(which is 64 currently).
.TP
.BR ENFILE " (before Linux 3.13)"
.I operation
was
.B KEYCTL_LINK
and the keyring is full.
(Before Linux 3.13,
.\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69
the available space for storing keyring links was limited to
a single page of memory; since Linux 3.13, there is no fixed limit.)
.TP
.B ENOENT
.I operation
was
.B KEYCTL_UNLINK
and the key to be unlinked isn't linked to the keyring.
.TP
.B ENOENT
.I operation
was
.B KEYCTL_DH_COMPUTE
and the hashing algorithm specified in the
.I hashname
field of the
.I struct keyctl_kdf_params
pointed by
.I arg5
argument hasn't been found.
.TP
.B ENOENT
.I operation
was
.B KEYCTL_RESTRICT_KEYRING
and the type provided in
.I arg3
argument doesn't support setting key linking restrictions.
.TP
.B ENOKEY
No matching key was found or an invalid key was specified.
.TP
.B ENOKEY
The value
.B KEYCTL_GET_KEYRING_ID
was specified in
.IR operation ,
the key specified in
.I arg2
did not exist, and
.I arg3
was zero (meaning don't create the key if it didn't exist).
.TP
.B ENOMEM
One of kernel memory allocation routines failed during the execution of the
syscall.
.TP
.B ENOTDIR
A key of keyring type was expected but the ID of a key with
a different type was provided.
.TP
.B EOPNOTSUPP
.I operation
was
.B KEYCTL_READ
and the key type does not support reading
(e.g., the type is
.IR \[dq]login\[dq] ).
.TP
.B EOPNOTSUPP
.I operation
was
.B KEYCTL_UPDATE
and the key type does not support updating.
.TP
.B EOPNOTSUPP
.I operation
was
.BR KEYCTL_RESTRICT_KEYRING ,
the type provided in
.I arg3
argument was "asymmetric",
and the key specified in the restriction specification provided in
.I arg4
has type other than "asymmetric" or "keyring".
.TP
.B EPERM
.I operation
was
.BR KEYCTL_GET_PERSISTENT ,
.I arg2
specified a UID other than the calling thread's real or effective UID,
and the caller did not have the
.B CAP_SETUID
capability.
.TP
.B EPERM
.I operation
was
.B KEYCTL_SESSION_TO_PARENT
and either:
all of the UIDs (GIDs) of the parent process do not match
the effective UID (GID) of the calling process;
the UID of the parent's existing session keyring or
the UID of the caller's session keyring did not match
the effective UID of the caller;
the parent process is not single-thread;
or the parent process is
.BR init (1)
or a kernel thread.
.TP
.B ETIMEDOUT
.I operation
was
.B KEYCTL_DH_COMPUTE
and the initialization of crypto modules has timed out.
.SH VERSIONS
A wrapper is provided in the
.I libkeyutils
library.
(The accompanying package provides the
.I <keyutils.h>
header file.)
However, rather than using this system call directly,
you probably want to use the various library functions
mentioned in the descriptions of individual operations above.
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.6.10.
.SH EXAMPLES
The program below provide subset of the functionality of the
.BR request\-key (8)
program provided by the
.I keyutils
package.
For informational purposes,
the program records various information in a log file.
.P
As described in
.BR request_key (2),
the
.BR request\-key (8)
program is invoked with command-line arguments that
describe a key that is to be instantiated.
The example program fetches and logs these arguments.
The program assumes authority to instantiate the requested key,
and then instantiates that key.
.P
The following shell session demonstrates the use of this program.
In the session,
we compile the program and then use it to temporarily replace the standard
.BR request\-key (8)
program.
(Note that temporarily disabling the standard
.BR request\-key (8)
program may not be safe on some systems.)
While our example program is installed,
we use the example program shown in
.BR request_key (2)
to request a key.
.P
.in +4n
.EX
$ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP
$ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP
$ \fBsudo cp key_instantiate /sbin/request\-key\fP
$ \fB./t_request_key user mykey somepayloaddata\fP
Key ID is 20d035bf
$ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP
.EE
.in
.P
Looking at the log file created by this program,
we can see the command-line arguments supplied to our example program:
.P
.in +4n
.EX
$ \fBcat /tmp/key_instantiate.log\fP
Time: Mon Nov  7 13:06:47 2016
\&
Command line arguments:
  argv[0]:            /sbin/request\-key
  operation:          create
  key_to_instantiate: 20d035bf
  UID:                1000
  GID:                1000
  thread_keyring:     0
  process_keyring:    0
  session_keyring:    256e6a6
\&
Key description:      user;1000;1000;3f010000;mykey
Auth key payload:     somepayloaddata
Destination keyring:  256e6a6
Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
.EE
.in
.P
The last few lines of the above output show that the example program
was able to fetch:
.IP \[bu] 3
the description of the key to be instantiated,
which included the name of the key
.RI ( mykey );
.IP \[bu]
the payload of the authorization key, which consisted of the data
.RI ( somepayloaddata )
passed to
.BR request_key (2);
.IP \[bu]
the destination keyring that was specified in the call to
.BR request_key (2);
and
.IP \[bu]
the description of the authorization key,
where we can see that the name of the authorization key matches
the ID of the key that is to be instantiated
.RI ( 20d035bf ).
.P
The example program in
.BR request_key (2)
specified the destination keyring as
.BR KEY_SPEC_SESSION_KEYRING .
By examining the contents of
.IR /proc/keys ,
we can see that this was translated to the ID of the destination keyring
.RI ( 0256e6a6 )
shown in the log output above;
we can also see the newly created key with the name
.I mykey
and ID
.IR 20d035bf .
.P
.in +4n
.EX
$ \fBcat /proc/keys | egrep \[aq]mykey|256e6a6\[aq]\fP
0256e6a6 I\-\-Q\-\-\-  194 perm 3f030000  1000  1000 keyring  _ses: 3
20d035bf I\-\-Q\-\-\-    1 perm 3f010000  1000  1000 user     mykey: 16
.EE
.in
.SS Program source
\&
.\" SRC BEGIN (key_instantiate.c)
.EX
/* key_instantiate.c */
\&
#include <errno.h>
#include <keyutils.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <time.h>
\&
#ifndef KEY_SPEC_REQUESTOR_KEYRING
#define KEY_SPEC_REQUESTOR_KEYRING      (\-8)
#endif
\&
int
main(int argc, char *argv[])
{
    int           akp_size;       /* Size of auth_key_payload */
    int           auth_key;
    char          dbuf[256];
    char          auth_key_payload[256];
    char          *operation;
    FILE          *fp;
    gid_t         gid;
    uid_t         uid;
    time_t        t;
    key_serial_t  key_to_instantiate, dest_keyring;
    key_serial_t  thread_keyring, process_keyring, session_keyring;
\&
    if (argc != 8) {
        fprintf(stderr, "Usage: %s op key uid gid thread_keyring "
                        "process_keyring session_keyring\en", argv[0]);
        exit(EXIT_FAILURE);
    }
\&
    fp = fopen("/tmp/key_instantiate.log", "w");
    if (fp == NULL)
        exit(EXIT_FAILURE);
\&
    setbuf(fp, NULL);
\&
    t = time(NULL);
    fprintf(fp, "Time: %s\en", ctime(&t));
\&
    /*
     * The kernel passes a fixed set of arguments to the program
     * that it execs; fetch them.
     */
    operation = argv[1];
    key_to_instantiate = atoi(argv[2]);
    uid = atoi(argv[3]);
    gid = atoi(argv[4]);
    thread_keyring = atoi(argv[5]);
    process_keyring = atoi(argv[6]);
    session_keyring = atoi(argv[7]);
\&
    fprintf(fp, "Command line arguments:\en");
    fprintf(fp, "  argv[0]:            %s\en", argv[0]);
    fprintf(fp, "  operation:          %s\en", operation);
    fprintf(fp, "  key_to_instantiate: %jx\en",
            (uintmax_t) key_to_instantiate);
    fprintf(fp, "  UID:                %jd\en", (intmax_t) uid);
    fprintf(fp, "  GID:                %jd\en", (intmax_t) gid);
    fprintf(fp, "  thread_keyring:     %jx\en",
            (uintmax_t) thread_keyring);
    fprintf(fp, "  process_keyring:    %jx\en",
            (uintmax_t) process_keyring);
    fprintf(fp, "  session_keyring:    %jx\en",
            (uintmax_t) session_keyring);
    fprintf(fp, "\en");
\&
    /*
     * Assume the authority to instantiate the key named in argv[2].
     */
    if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) {
        fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\en",
                strerror(errno));
        exit(EXIT_FAILURE);
    }
\&
    /*
     * Fetch the description of the key that is to be instantiated.
     */
    if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
               dbuf, sizeof(dbuf)) == \-1) {
        fprintf(fp, "KEYCTL_DESCRIBE failed: %s\en", strerror(errno));
        exit(EXIT_FAILURE);
    }
\&
    fprintf(fp, "Key description:      %s\en", dbuf);
\&
    /*
     * Fetch the payload of the authorization key, which is
     * actually the callout data given to request_key().
     */
    akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY,
                      auth_key_payload, sizeof(auth_key_payload));
    if (akp_size == \-1) {
        fprintf(fp, "KEYCTL_READ failed: %s\en", strerror(errno));
        exit(EXIT_FAILURE);
    }
\&
    auth_key_payload[akp_size] = \[aq]\e0\[aq];
    fprintf(fp, "Auth key payload:     %s\en", auth_key_payload);
\&
    /*
     * For interest, get the ID of the authorization key and
     * display it.
     */
    auth_key = keyctl(KEYCTL_GET_KEYRING_ID,
                      KEY_SPEC_REQKEY_AUTH_KEY);
    if (auth_key == \-1) {
        fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\en",
                strerror(errno));
        exit(EXIT_FAILURE);
    }
\&
    fprintf(fp, "Auth key ID:          %jx\en", (uintmax_t) auth_key);
\&
    /*
     * Fetch key ID for the request_key(2) destination keyring.
     */
    dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID,
                          KEY_SPEC_REQUESTOR_KEYRING);
    if (dest_keyring == \-1) {
        fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\en",
                strerror(errno));
        exit(EXIT_FAILURE);
    }
\&
    fprintf(fp, "Destination keyring:  %jx\en", (uintmax_t) dest_keyring);
\&
    /*
     * Fetch the description of the authorization key. This
     * allows us to see the key type, UID, GID, permissions,
     * and description (name) of the key. Among other things,
     * we will see that the name of the key is a hexadecimal
     * string representing the ID of the key to be instantiated.
     */
    if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
               dbuf, sizeof(dbuf)) == \-1)
    {
        fprintf(fp, "KEYCTL_DESCRIBE failed: %s\en", strerror(errno));
        exit(EXIT_FAILURE);
    }
\&
    fprintf(fp, "Auth key description: %s\en", dbuf);
\&
    /*
     * Instantiate the key using the callout data that was supplied
     * in the payload of the authorization key.
     */
    if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
               auth_key_payload, akp_size + 1, dest_keyring) == \-1)
    {
        fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\en",
                strerror(errno));
        exit(EXIT_FAILURE);
    }
\&
    exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH SEE ALSO
.ad l
.nh
.BR keyctl (1),
.BR add_key (2),
.BR request_key (2),
.\"     .BR find_key_by_type_and_name (3)
.\"     There is a man page, but this function seems not to exist
.BR keyctl (3),
.BR keyctl_assume_authority (3),
.BR keyctl_chown (3),
.BR keyctl_clear (3),
.BR keyctl_describe (3),
.BR keyctl_describe_alloc (3),
.BR keyctl_dh_compute (3),
.BR keyctl_dh_compute_alloc (3),
.BR keyctl_get_keyring_ID (3),
.BR keyctl_get_persistent (3),
.BR keyctl_get_security (3),
.BR keyctl_get_security_alloc (3),
.BR keyctl_instantiate (3),
.BR keyctl_instantiate_iov (3),
.BR keyctl_invalidate (3),
.BR keyctl_join_session_keyring (3),
.BR keyctl_link (3),
.BR keyctl_negate (3),
.BR keyctl_read (3),
.BR keyctl_read_alloc (3),
.BR keyctl_reject (3),
.BR keyctl_revoke (3),
.BR keyctl_search (3),
.BR keyctl_session_to_parent (3),
.BR keyctl_set_reqkey_keyring (3),
.BR keyctl_set_timeout (3),
.BR keyctl_setperm (3),
.BR keyctl_unlink (3),
.BR keyctl_update (3),
.BR recursive_key_scan (3),
.BR recursive_session_key_scan (3),
.BR capabilities (7),
.BR credentials (7),
.BR keyrings (7),
.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_namespaces (7),
.BR user\-session\-keyring (7),
.BR request\-key (8)
.P
The kernel source files under
.I Documentation/security/keys/
(or, before Linux 4.13, in the file
.IR Documentation/security/keys.txt ).