Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_DH_COMPUTE.2const

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