Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_DH_COMPUTE.2const

raw
1 .\" Copyright 2016, Michael Kerrisk <[email protected]>
2 .\" Copyright 2016, Eugene Syromyatnikov <[email protected]>
3 .\" A very few fragments remain from an earlier version of this page
4 .\" written by David Howells ([email protected])
5 .\" Copyright 2024, Alejandro Colomar <[email protected]>
6 .\"
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\"
9 .TH KEYCTL_DH_COMPUTE 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_DH_COMPUTE
12 \-
13 compute a Diffie-Hellman shared secret or public key
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ,\~ \-lc )
17 .SH SYNOPSIS
18 .nf
19 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
20 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
21 .B #include <unistd.h>
22 .P
23 .B long syscall(SYS_keyctl, KEYCTL_DH_COMPUTE,
24 .BI " struct keyctl_dh_params *" dh_params ,
25 .BI " char " buf [. n "], size_t " n ,
26 .BI " struct keyctl_kdf_params *_Nullable " kdf_params );
27 .fi
28 .SH DESCRIPTION
29 Compute a Diffie-Hellman shared secret or public key,
30 optionally applying key derivation function (KDF) to the result.
31 .P
32 The
33 .I dh_params
34 argument is a pointer to a set of parameters containing
35 serial numbers for three
36 .I \[dq]user\[dq]
37 keys used in the Diffie-Hellman calculation,
38 packaged in a structure of the following form:
39 .P
40 .in +4n
41 .EX
42 struct keyctl_dh_params {
43 int32_t private; /* The local private key */
44 int32_t prime; /* The prime, known to both parties */
45 int32_t base; /* The base integer: either a shared
46 generator or the remote public key */
47 };
48 .EE
49 .in
50 .P
51 Each of the three keys specified in this structure must grant the caller
52 .I read
53 permission.
54 The payloads of these keys are used to calculate the Diffie-Hellman
55 result as:
56 .P
57 .in +4n
58 .EX
59 base \[ha] private mod prime
60 .EE
61 .in
62 .P
63 If the base is the shared generator, the result is the local public key.
64 If the base is the remote public key, the result is the shared secret.
65 .P
66 The
67 .I buf
68 argument
69 points to a buffer where the result of the calculation is placed.
70 The size of that buffer is specified in
71 .IR n .
72 .P
73 The buffer must be large enough to accommodate the output data,
74 otherwise an error is returned.
75 If
76 .I n
77 is specified zero,
78 in which case the buffer is not used and
79 the operation returns the minimum required buffer size
80 (i.e., the length of the prime).
81 .P
82 Diffie-Hellman computations can be performed in user space,
83 but require a multiple-precision integer (MPI) library.
84 Moving the implementation into the kernel gives access to
85 the kernel MPI implementation,
86 and allows access to secure or acceleration hardware.
87 .P
88 Adding support for DH computation to the
89 .BR keyctl ()
90 system call was considered a good fit due to the DH algorithm's use
91 for deriving shared keys;
92 it also allows the type of the key to determine
93 which DH implementation (software or hardware) is appropriate.
94 .\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8
95 .P
96 If the
97 .I kdf_params
98 argument is
99 .BR NULL ,
100 then the DH result itself is returned.
101 Otherwise (since Linux 4.12), it is a pointer to a structure which specifies
102 parameters of the KDF operation to be applied:
103 .P
104 .in +4n
105 .EX
106 struct keyctl_kdf_params {
107 char *hashname; /* Hash algorithm name */
108 char *otherinfo; /* SP800\-56A OtherInfo */
109 __u32 otherinfolen; /* Length of otherinfo data */
110 __u32 __spare[8]; /* Reserved */
111 };
112 .EE
113 .in
114 .P
115 The
116 .I hashname
117 field is a null-terminated string which specifies a hash name
118 (available in the kernel's crypto API; the list of the hashes available
119 is rather tricky to observe; please refer to the
120 .UR https://www.kernel.org\:/doc\:/html\:/latest\:/crypto\:/architecture.html
121 "Kernel Crypto API Architecture"
122 .UE
123 documentation for the information regarding how hash names are constructed and
124 your kernel's source and configuration regarding what ciphers
125 and templates with type
126 .B CRYPTO_ALG_TYPE_SHASH
127 are available)
128 to be applied to DH result in KDF operation.
129 .P
130 The
131 .I otherinfo
132 field is an
133 .I OtherInfo
134 data as described in SP800-56A section 5.8.1.2 and is algorithm-specific.
135 This data is concatenated with the result of DH operation and is provided as
136 an input to the KDF operation.
137 Its size is provided in the
138 .I otherinfolen
139 field and is limited by
140 .B KEYCTL_KDF_MAX_OI_LEN
141 constant that defined in
142 .I security/keys/internal.h
143 to a value of 64.
144 .P
145 The
146 .B __spare
147 field is currently unused.
148 .\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
149 It was ignored until Linux 4.13 (but still should be
150 user-addressable since it is copied to the kernel),
151 and should contain zeros since Linux 4.13.
152 .P
153 The KDF implementation complies with SP800-56A as well
154 as with SP800-108 (the counter KDF).
155 .P
156 .\" keyutils commit 742c9d7b94051d3b21f9f61a73ed6b5f3544cb82
157 .\" keyutils commit d68a981e5db41d059ac782071c35d1e8f3aaf61c
158 This operation is exposed by
159 .I libkeyutils
160 (from
161 .I libkeyutils
162 1.5.10 onwards) via the functions
163 .BR keyctl_dh_compute (3)
164 and
165 .BR keyctl_dh_compute_alloc (3).
166 .SH RETURN VALUE
167 On success,
168 the number of bytes copied to the buffer, or, if
169 .I n
170 is 0, the required buffer size.
171 .P
172 On error, \-1 is returned, and
173 .I errno
174 is set to indicate the error.
175 .SH ERRORS
176 .TP
177 .B EAGAIN
178 There was an error during crypto module initialization.
179 .TP
180 .B EFAULT
181 One of the following has failed:
182 .RS
183 .IP \[bu] 3
184 copying of the
185 .IR "struct keyctl_dh_params" ,
186 provided in the
187 .I dh_params
188 argument, from user space;
189 .IP \[bu]
190 copying of the
191 .IR "struct keyctl_kdf_params" ,
192 provided in the non-NULL
193 .I kdf_params
194 argument, from user space
195 (in case kernel supports performing KDF operation on DH operation result);
196 .IP \[bu]
197 copying of data pointed by the
198 .I hashname
199 field of the
200 .I "struct keyctl_kdf_params"
201 from user space;
202 .IP \[bu]
203 copying of data pointed by the
204 .I otherinfo
205 field of the
206 .I struct keyctl_kdf_params
207 from user space if the
208 .I otherinfolen
209 field was nonzero;
210 .IP \[bu]
211 copying of the result to user space.
212 .RE
213 .TP
214 .BR EINVAL " (before Linux 4.12)"
215 Argument
216 .I kdf_params
217 was non-NULL.
218 .TP
219 .B EINVAL
220 The digest size of the hashing algorithm supplied is zero.
221 .TP
222 .B EINVAL
223 The buffer size provided is not enough to hold the result.
224 Provide 0 as a buffer size in order to obtain the minimum buffer size.
225 .TP
226 .B EINVAL
227 The hash name provided in the
228 .I hashname
229 field of the
230 .I struct keyctl_kdf_params
231 pointed by
232 .I kdf_params
233 argument is too big (the limit is implementation-specific and varies between
234 kernel versions, but it is deemed big enough for all valid algorithm names).
235 .TP
236 .B EINVAL
237 .\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
238 The
239 .I __spare
240 field of the
241 .I struct keyctl_kdf_params
242 provided in the
243 .I kdf_params
244 argument contains nonzero values.
245 .TP
246 .B EMSGSIZE
247 The buffer length exceeds
248 .B KEYCTL_KDF_MAX_OUTPUT_LEN
249 (which is 1024 currently)
250 or the
251 .I otherinfolen
252 field of the
253 .I struct keyctl_kdf_parms
254 passed in
255 .I kdf_params
256 exceeds
257 .B KEYCTL_KDF_MAX_OI_LEN
258 (which is 64 currently).
259 .TP
260 .B ENOENT
261 The hashing algorithm specified in the
262 .I hashname
263 field of the
264 .I struct keyctl_kdf_params
265 pointed by
266 .I kdf_params
267 argument hasn't been found.
268 .TP
269 .B ETIMEDOUT
270 The initialization of crypto modules has timed out.
271 .SH STANDARDS
272 Linux.
273 .SH HISTORY
274 Linux 4.7.
275 .\" commit ddbb41148724367394d0880c516bfaeed127b52e
276 .SH SEE ALSO
277 .BR keyctl (2),
278 .BR keyctl_dh_compute (3),
279 .BR keyctl_dh_compute_alloc (3),
280 .BR keyctl_dh_compute_kdf (3)