Debian Codegraph @

upstream/debian-unstable/man7/proxy-certificates.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PROXY-CERTIFICATES 7SSL"
58 .TH PROXY-CERTIFICATES 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 proxy\-certificates \- Proxy certificates in OpenSSL
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 Proxy certificates are defined in RFC 3820. They are used to
68 extend rights to some other entity (a computer process, typically, or
69 sometimes to the user itself). This allows the entity to perform
70 operations on behalf of the owner of the EE (End Entity) certificate.
71 .PP
72 The requirements for a valid proxy certificate are:
73 .IP \(bu 4
74 They are issued by an End Entity, either a normal EE certificate, or
75 another proxy certificate.
76 .IP \(bu 4
77 They must not have the \fBsubjectAltName\fR or \fBissuerAltName\fR
78 extensions.
79 .IP \(bu 4
80 They must have the \fBproxyCertInfo\fR extension.
81 .IP \(bu 4
82 They must have the subject of their issuer, with one \fBcommonName\fR
83 added.
84 .SS "Enabling proxy certificate verification"
85 .IX Subsection "Enabling proxy certificate verification"
86 OpenSSL expects applications that want to use proxy certificates to be
87 specially aware of them, and make that explicit. This is done by
88 setting an X509 verification flag:
89 .PP
90 .Vb 1
91 \& X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
92 .Ve
93 .PP
94 or
95 .PP
96 .Vb 1
97 \& X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_ALLOW_PROXY_CERTS);
98 .Ve
99 .PP
100 See "NOTES" for a discussion on this requirement.
101 .SS "Creating proxy certificates"
102 .IX Subsection "Creating proxy certificates"
103 Creating proxy certificates can be done using the \fBopenssl\-x509\fR\|(1)
104 command, with some extra extensions:
105 .PP
106 .Vb 7
107 \& [ proxy ]
108 \& # A proxy certificate MUST NEVER be a CA certificate.
109 \& basicConstraints = CA:FALSE
110 \& # Usual authority key ID
111 \& authorityKeyIdentifier = keyid,issuer:always
112 \& # The extension which marks this certificate as a proxy
113 \& proxyCertInfo = critical,language:id\-ppl\-anyLanguage,pathlen:1,policy:text:AB
114 .Ve
115 .PP
116 It's also possible to specify the proxy extension in a separate section:
117 .PP
118 .Vb 1
119 \& proxyCertInfo = critical,@proxy_ext
120 \&
121 \& [ proxy_ext ]
122 \& language = id\-ppl\-anyLanguage
123 \& pathlen = 0
124 \& policy = text:BC
125 .Ve
126 .PP
127 The policy value has a specific syntax, \fIsyntag\fR:\fIstring\fR, where the
128 \&\fIsyntag\fR determines what will be done with the string. The following
129 \&\fIsyntag\fRs are recognised:
130 .IP \fBtext\fR 4
131 .IX Item "text"
132 indicates that the string is a byte sequence, without any encoding:
133 .Sp
134 .Vb 1
135 \& policy=text:räksmörgås
136 .Ve
137 .IP \fBhex\fR 4
138 .IX Item "hex"
139 indicates the string is encoded hexadecimal encoded binary data, with
140 colons between each byte (every second hex digit):
141 .Sp
142 .Vb 1
143 \& policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73
144 .Ve
145 .IP \fBfile\fR 4
146 .IX Item "file"
147 indicates that the text of the policy should be taken from a file.
148 The string is then a filename. This is useful for policies that are
149 more than a few lines, such as XML or other markup.
150 .PP
151 Note that the proxy policy value is what determines the rights granted
152 to the process during the proxy certificate, and it is up to the
153 application to interpret and combine these policies.>
154 .PP
155 With a proxy extension, creating a proxy certificate is a matter of
156 two commands:
157 .PP
158 .Vb 3
159 \& openssl req \-new \-config proxy.cnf \e
160 \& \-out proxy.req \-keyout proxy.key \e
161 \& \-subj "/DC=org/DC=openssl/DC=users/CN=proxy"
162 \&
163 \& openssl x509 \-req \-CAcreateserial \-in proxy.req \-out proxy.crt \e
164 \& \-CA user.crt \-CAkey user.key \-days 7 \e
165 \& \-extfile proxy.cnf \-extensions proxy
166 .Ve
167 .PP
168 You can also create a proxy certificate using another proxy
169 certificate as issuer. Note that this example uses a different
170 configuration section for the proxy extensions:
171 .PP
172 .Vb 3
173 \& openssl req \-new \-config proxy.cnf \e
174 \& \-out proxy2.req \-keyout proxy2.key \e
175 \& \-subj "/DC=org/DC=openssl/DC=users/CN=proxy/CN=proxy 2"
176 \&
177 \& openssl x509 \-req \-CAcreateserial \-in proxy2.req \-out proxy2.crt \e
178 \& \-CA proxy.crt \-CAkey proxy.key \-days 7 \e
179 \& \-extfile proxy.cnf \-extensions proxy_2
180 .Ve
181 .SS "Using proxy certs in applications"
182 .IX Subsection "Using proxy certs in applications"
183 To interpret proxy policies, the application would normally start with
184 some default rights (perhaps none at all), then compute the resulting
185 rights by checking the rights against the chain of proxy certificates,
186 user certificate and CA certificates.
187 .PP
188 The complicated part is figuring out how to pass data between your
189 application and the certificate validation procedure.
190 .PP
191 The following ingredients are needed for such processing:
192 .IP \(bu 4
193 a callback function that will be called for every certificate being
194 validated. The callback is called several times for each certificate,
195 so you must be careful to do the proxy policy interpretation at the
196 right time. You also need to fill in the defaults when the EE
197 certificate is checked.
198 .IP \(bu 4
199 a data structure that is shared between your application code and the
200 callback.
201 .IP \(bu 4
202 a wrapper function that sets it all up.
203 .IP \(bu 4
204 an ex_data index function that creates an index into the generic
205 ex_data store that is attached to an X509 validation context.
206 .PP
207 The following skeleton code can be used as a starting point:
208 .PP
209 .Vb 4
210 \& #include <string.h>
211 \& #include <netdb.h>
212 \& #include <openssl/x509.h>
213 \& #include <openssl/x509v3.h>
214 \&
215 \& #define total_rights 25
216 \&
217 \& /*
218 \& * In this example, I will use a view of granted rights as a bit
219 \& * array, one bit for each possible right.
220 \& */
221 \& typedef struct your_rights {
222 \& unsigned char rights[(total_rights + 7) / 8];
223 \& } YOUR_RIGHTS;
224 \&
225 \& /*
226 \& * The following procedure will create an index for the ex_data
227 \& * store in the X509 validation context the first time it\*(Aqs
228 \& * called. Subsequent calls will return the same index.
229 \& */
230 \& static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx)
231 \& {
232 \& static volatile int idx = \-1;
233 \&
234 \& if (idx < 0) {
235 \& X509_STORE_lock(X509_STORE_CTX_get0_store(ctx));
236 \& if (idx < 0) {
237 \& idx = X509_STORE_CTX_get_ex_new_index(0,
238 \& "for verify callback",
239 \& NULL,NULL,NULL);
240 \& }
241 \& X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx));
242 \& }
243 \& return idx;
244 \& }
245 \&
246 \& /* Callback to be given to the X509 validation procedure. */
247 \& static int verify_callback(int ok, X509_STORE_CTX *ctx)
248 \& {
249 \& if (ok == 1) {
250 \& /*
251 \& * It\*(Aqs REALLY important you keep the proxy policy check
252 \& * within this section. It\*(Aqs important to know that when
253 \& * ok is 1, the certificates are checked from top to
254 \& * bottom. You get the CA root first, followed by the
255 \& * possible chain of intermediate CAs, followed by the EE
256 \& * certificate, followed by the possible proxy
257 \& * certificates.
258 \& */
259 \& X509 *xs = X509_STORE_CTX_get_current_cert(ctx);
260 \&
261 \& if (X509_get_extension_flags(xs) & EXFLAG_PROXY) {
262 \& YOUR_RIGHTS *rights =
263 \& (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
264 \& get_proxy_auth_ex_data_idx(ctx));
265 \& PROXY_CERT_INFO_EXTENSION *pci =
266 \& X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);
267 \&
268 \& switch (OBJ_obj2nid(pci\->proxyPolicy\->policyLanguage)) {
269 \& case NID_Independent:
270 \& /*
271 \& * Do whatever you need to grant explicit rights
272 \& * to this particular proxy certificate, usually
273 \& * by pulling them from some database. If there
274 \& * are none to be found, clear all rights (making
275 \& * this and any subsequent proxy certificate void
276 \& * of any rights).
277 \& */
278 \& memset(rights\->rights, 0, sizeof(rights\->rights));
279 \& break;
280 \& case NID_id_ppl_inheritAll:
281 \& /*
282 \& * This is basically a NOP, we simply let the
283 \& * current rights stand as they are.
284 \& */
285 \& break;
286 \& default:
287 \& /*
288 \& * This is usually the most complex section of
289 \& * code. You really do whatever you want as long
290 \& * as you follow RFC 3820. In the example we use
291 \& * here, the simplest thing to do is to build
292 \& * another, temporary bit array and fill it with
293 \& * the rights granted by the current proxy
294 \& * certificate, then use it as a mask on the
295 \& * accumulated rights bit array, and voilà, you
296 \& * now have a new accumulated rights bit array.
297 \& */
298 \& {
299 \& int i;
300 \& YOUR_RIGHTS tmp_rights;
301 \& memset(tmp_rights.rights, 0,
302 \& sizeof(tmp_rights.rights));
303 \&
304 \& /*
305 \& * process_rights() is supposed to be a
306 \& * procedure that takes a string and its
307 \& * length, interprets it and sets the bits
308 \& * in the YOUR_RIGHTS pointed at by the
309 \& * third argument.
310 \& */
311 \& process_rights((char *) pci\->proxyPolicy\->policy\->data,
312 \& pci\->proxyPolicy\->policy\->length,
313 \& &tmp_rights);
314 \&
315 \& for(i = 0; i < total_rights / 8; i++)
316 \& rights\->rights[i] &= tmp_rights.rights[i];
317 \& }
318 \& break;
319 \& }
320 \& PROXY_CERT_INFO_EXTENSION_free(pci);
321 \& } else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) {
322 \& /* We have an EE certificate, let\*(Aqs use it to set default! */
323 \& YOUR_RIGHTS *rights =
324 \& (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
325 \& get_proxy_auth_ex_data_idx(ctx));
326 \&
327 \& /*
328 \& * The following procedure finds out what rights the
329 \& * owner of the current certificate has, and sets them
330 \& * in the YOUR_RIGHTS structure pointed at by the
331 \& * second argument.
332 \& */
333 \& set_default_rights(xs, rights);
334 \& }
335 \& }
336 \& return ok;
337 \& }
338 \&
339 \& static int my_X509_verify_cert(X509_STORE_CTX *ctx,
340 \& YOUR_RIGHTS *needed_rights)
341 \& {
342 \& int ok;
343 \& int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) =
344 \& X509_STORE_CTX_get_verify_cb(ctx);
345 \& YOUR_RIGHTS rights;
346 \&
347 \& X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
348 \& X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx),
349 \& &rights);
350 \& X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
351 \& ok = X509_verify_cert(ctx);
352 \&
353 \& if (ok == 1) {
354 \& ok = check_needed_rights(rights, needed_rights);
355 \& }
356 \&
357 \& X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);
358 \&
359 \& return ok;
360 \& }
361 .Ve
362 .PP
363 If you use SSL or TLS, you can easily set up a callback to have the
364 certificates checked properly, using the code above:
365 .PP
366 .Vb 2
367 \& SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert,
368 \& &needed_rights);
369 .Ve
370 .SH NOTES
371 .IX Header "NOTES"
372 To this date, it seems that proxy certificates have only been used in
373 environments that are aware of them, and no one seems to have
374 investigated how they can be used or misused outside of such an
375 environment.
376 .PP
377 For that reason, OpenSSL requires that applications aware of proxy
378 certificates must also make that explicit.
379 .PP
380 \&\fBsubjectAltName\fR and \fBissuerAltName\fR are forbidden in proxy
381 certificates, and this is enforced in OpenSSL. The subject must be
382 the same as the issuer, with one commonName added on.
383 .SH "SEE ALSO"
384 .IX Header "SEE ALSO"
385 \&\fBX509_STORE_CTX_set_flags\fR\|(3),
386 \&\fBX509_STORE_CTX_set_verify_cb\fR\|(3),
387 \&\fBX509_VERIFY_PARAM_set_flags\fR\|(3),
388 \&\fBSSL_CTX_set_cert_verify_callback\fR\|(3),
389 \&\fBopenssl\-req\fR\|(1), \fBopenssl\-x509\fR\|(1),
390 RFC 3820 <https://tools.ietf.org/html/rfc3820>
391 .SH COPYRIGHT
392 .IX Header "COPYRIGHT"
393 Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved.
394 .PP
395 Licensed under the Apache License 2.0 (the "License"). You may not use
396 this file except in compliance with the License. You can obtain a copy
397 in the file LICENSE in the source distribution or at
398 <https://www.openssl.org/source/license.html>.