]>
Commit | Line | Data |
---|---|---|
2e2f82fc MK |
1 | .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. |
2 | .\" Written by David Howells (dhowells@redhat.com) | |
3 | .\" | |
23dbdcbe | 4 | .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) |
2e2f82fc MK |
5 | .\" This program is free software; you can redistribute it and/or |
6 | .\" modify it under the terms of the GNU General Public License | |
7 | .\" as published by the Free Software Foundation; either version | |
8 | .\" 2 of the License, or (at your option) any later version. | |
722b6788 | 9 | .\" %%%LICENSE_END |
2e2f82fc | 10 | .\" |
3df541c0 | 11 | .TH ADD_KEY 2 2016-07-17 Linux "Linux Key Management Calls" |
2e2f82fc | 12 | .SH NAME |
f68512e9 | 13 | add_key \- add a key to the kernel's key management facility |
2e2f82fc MK |
14 | .SH SYNOPSIS |
15 | .nf | |
16 | .B #include <keyutils.h> | |
17 | .sp | |
18 | .BI "key_serial_t add_key(const char *" type ", const char *" description , | |
be464b55 MK |
19 | .BI " const void *" payload ", size_t " plen , |
20 | .BI " key_serial_t " keyring ");" | |
6030f2d8 | 21 | .fi |
2e2f82fc MK |
22 | .SH DESCRIPTION |
23 | .BR add_key () | |
24 | asks the kernel to create or update a key of the given | |
25 | .I type | |
26 | and | |
27 | .IR description , | |
28 | instantiate it with the | |
29 | .I payload | |
30 | of length | |
31 | .IR plen , | |
32 | and to attach it to the nominated | |
33 | .I keyring | |
34 | and to return its serial number. | |
35 | .P | |
36 | The key type may reject the data if it's in the wrong format or in some other | |
37 | way invalid. | |
38 | .P | |
39 | If the destination | |
40 | .I keyring | |
41 | already contains a key that matches the specified | |
4cae11db | 42 | .IR type " and " description, |
2e2f82fc MK |
43 | then, if the key type supports it, that key will be updated rather than a new |
44 | key being created; if not, a new key will be created and it will displace the | |
45 | link to the extant key from the keyring. | |
46 | .P | |
47 | The destination | |
48 | .I keyring | |
49 | serial number may be that of a valid keyring to which the caller has write | |
50 | permission, or it may be a special keyring ID: | |
51 | .TP | |
52 | .B KEY_SPEC_THREAD_KEYRING | |
53 | This specifies the caller's thread-specific keyring. | |
54 | .TP | |
55 | .B KEY_SPEC_PROCESS_KEYRING | |
56 | This specifies the caller's process-specific keyring. | |
57 | .TP | |
58 | .B KEY_SPEC_SESSION_KEYRING | |
59 | This specifies the caller's session-specific keyring. | |
60 | .TP | |
61 | .B KEY_SPEC_USER_KEYRING | |
62 | This specifies the caller's UID-specific keyring. | |
63 | .TP | |
64 | .B KEY_SPEC_USER_SESSION_KEYRING | |
65 | This specifies the caller's UID-session keyring. | |
2e2f82fc MK |
66 | .SH KEY TYPES |
67 | There are a number of key types available in the core key management code, and | |
68 | these can be specified to this function: | |
69 | .TP | |
70 | .B \*(lquser\*(rq | |
71 | Keys of the user-defined key type may contain a blob of arbitrary data, and the | |
72 | .I description | |
73 | may be any valid string, though it is preferred that the description be | |
74 | prefixed with a string representing the service to which the key is of interest | |
75 | and a colon (for instance | |
76 | .RB \*(lq afs:mykey \*(rq). | |
2e2f82fc MK |
77 | .TP |
78 | .B \*(lqkeyring\*(rq | |
79 | Keyrings are special key types that may contain links to sequences of other | |
4175f999 | 80 | keys of any type. |
7ee43165 | 81 | If this interface is used to create a keyring, then a NULL |
2e2f82fc MK |
82 | .I payload |
83 | should be specified, and | |
84 | .I plen | |
85 | should be zero. | |
2e2f82fc MK |
86 | .SH RETURN VALUE |
87 | On success | |
88 | .BR add_key () | |
89 | returns the serial number of the key it created or updated. | |
7ee43165 | 90 | On error, the value \-1 |
2e2f82fc | 91 | will be returned and errno will have been set to an appropriate error. |
2e2f82fc MK |
92 | .SH ERRORS |
93 | .TP | |
b801426a MK |
94 | .B EACCES |
95 | The keyring wasn't available for modification by the user. | |
96 | .TP | |
97 | .B EINVAL | |
98 | The payload data was invalid. | |
2e2f82fc MK |
99 | .TP |
100 | .B EKEYEXPIRED | |
101 | The keyring has expired. | |
102 | .TP | |
103 | .B EKEYREVOKED | |
104 | The keyring has been revoked. | |
105 | .TP | |
b801426a MK |
106 | .B ENOKEY |
107 | The keyring doesn't exist. | |
2e2f82fc MK |
108 | .TP |
109 | .B ENOMEM | |
110 | Insufficient memory to create a key. | |
111 | .TP | |
112 | .B EDQUOT | |
113 | The key quota for this user would be exceeded by creating this key or linking | |
114 | it to the keyring. | |
2e2f82fc MK |
115 | .SH LINKING |
116 | Although this is a Linux system call, it is not present in | |
117 | .I libc | |
118 | but can be found rather in | |
119 | .IR libkeyutils . | |
120 | When linking, | |
121 | .B -lkeyutils | |
122 | should be specified to the linker. | |
2e2f82fc MK |
123 | .SH SEE ALSO |
124 | .BR keyctl (1), | |
125 | .BR keyctl (2), | |
32fc2407 | 126 | .BR request_key (2), |
86cfb3ca | 127 | .BR keyctl (3), |
32fc2407 | 128 | .BR keyrings (7) |