summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/X509_check_purpose.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/X509_check_purpose.3')
-rw-r--r--src/lib/libcrypto/man/X509_check_purpose.3431
1 files changed, 0 insertions, 431 deletions
diff --git a/src/lib/libcrypto/man/X509_check_purpose.3 b/src/lib/libcrypto/man/X509_check_purpose.3
deleted file mode 100644
index 8fea6679fc..0000000000
--- a/src/lib/libcrypto/man/X509_check_purpose.3
+++ /dev/null
@@ -1,431 +0,0 @@
1.\" $OpenBSD: X509_check_purpose.3,v 1.12 2024/09/02 08:04:32 tb Exp $
2.\"
3.\" Copyright (c) 2019, 2021 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: September 2 2024 $
18.Dt X509_CHECK_PURPOSE 3
19.Os
20.Sh NAME
21.Nm X509_check_purpose
22.Nd check intended usage of a public key
23.Sh SYNOPSIS
24.In openssl/x509v3.h
25.Ft int
26.Fo X509_check_purpose
27.Fa "X509 *certificate"
28.Fa "int purpose"
29.Fa "int ca"
30.Fc
31.Sh DESCRIPTION
32If the
33.Fa purpose
34argument is \-1,
35.Fn X509_check_purpose
36ignores the
37.Fa ca
38argument and checks that all the extensions of the
39.Fa certificate
40can be parsed and pass minimal sanity checks, ensuring that
41no extension occurs more than once.
42It also makes sure that all extensions are cached in the
43.Vt X509
44object.
45.Pp
46If the
47.Fa purpose
48argument is not \-1 and the
49.Fa ca
50flag is 0,
51.Fn X509_check_purpose
52also checks whether the public key contained in the
53.Fa certificate
54is intended to be used for the given
55.Fa purpose ,
56which can be one of the following integer constants.
57The check succeeds if none of the conditions given in the list below
58are violated.
59It always fails if parsing fails for any extension contained in the
60.Fa certificate .
61.Bl -tag -width 1n
62.It Dv X509_PURPOSE_SSL_CLIENT
63.Bl -dash -width 1n -compact
64.It
65If the
66.Fa certificate
67contains an Extended Key Usage extension, it contains the RFC 5280
68.Dq TLS WWW client authentication
69purpose
70.Pq Dv NID_client_auth .
71.It
72If the
73.Fa certificate
74contains a Key Usage extension, the
75.Dv digitalSignature
76bit is set.
77.It
78If the
79.Fa certificate
80contains a Netscape Cert Type extension, the
81.Dq SSL client certificate
82bit is set
83.Pq Dv NS_SSL_CLIENT .
84.El
85.It Dv X509_PURPOSE_SSL_SERVER
86.Bl -dash -width 1n -compact
87.It
88If the
89.Fa certificate
90contains an Extended Key Usage extension, it contains the RFC 5280
91.Dq TLS WWW server authentication
92purpose
93.Pq Dv NID_server_auth
94or the private
95.Dq Netscape Server Gated Crypto
96.Pq Dv NID_ns_sgc
97or
98.Dq Microsoft Server Gated Crypto
99.Pq Dv NID_ms_sgc
100purpose.
101.It
102If the
103.Fa certificate
104contains a Key Usage extension, at least one of the
105.Dv digitalSignature
106and
107.Dv keyEncipherment
108bits is set.
109.It
110If the
111.Fa certificate
112contains a Netscape Cert Type extension, the
113.Dq SSL server certificate
114bit is set
115.Pq Dv NS_SSL_SERVER
116.El
117.It Dv X509_PURPOSE_NS_SSL_SERVER
118.\" check_purpose_ns_ssl_server, "Netscape SSL server"
119This does the same checks as
120.Dv X509_PURPOSE_SSL_SERVER
121and additionally requires that a Key Usage extension, if present,
122has the
123.Dv keyEncipherment
124bit set.
125.It Dv X509_PURPOSE_SMIME_SIGN
126.\" check_purpose_smime_sign, "S/MIME signing"
127.Bl -dash -width 1n -compact
128.It
129If the
130.Fa certificate
131contains an Extended Key Usage extension, it contains the RFC 5280
132.Dq Email protection
133purpose
134.Pq Dv NID_email_protect .
135.It
136If the
137.Fa certificate
138contains a Key Usage extension, at least one of the
139.Dv digitalSignature
140and
141.Dv nonRepudiation
142bits is set.
143.It
144If the
145.Fa certificate
146contains a Netscape Cert Type extension, it has the
147.Dq S/MIME certificate
148bit set.
149If the
150.Dq SSL client certificate
151bit is set but the
152.Dq S/MIME certificate
153bit is not, no decision is made.
154.El
155.It Dv X509_PURPOSE_SMIME_ENCRYPT
156.\" check_purpose_smime_encrypt, "S/MIME encryption"
157.Bl -dash -width 1n -compact
158.It
159If the
160.Fa certificate
161contains an Extended Key Usage extension, it contains the RFC 5280
162.Dq Email protection
163purpose
164.Pq Dv NID_email_protect .
165.It
166If the
167.Fa certificate
168contains a Key Usage extension, the
169.Dv keyEncipherment
170bit is set.
171.It
172If the
173.Fa certificate
174contains a Netscape Cert Type extension, it has the
175.Dq S/MIME certificate
176bit set.
177If the
178.Dq SSL client certificate
179bit is set but the
180.Dq S/MIME certificate
181bit is not, no decision is made.
182.El
183.It Dv X509_PURPOSE_CRL_SIGN
184.\" check_purpose_crl_sign, "CRL signing"
185.Bl -dash -width 1n -compact
186.It
187If the
188.Fa certificate
189contains a Key Usage extension, the
190.Dv cRLSign
191bit is set.
192.El
193.It Dv X509_PURPOSE_ANY
194Nothing is required except that, if any extensions are present,
195parsing them needs to succeed.
196.It Dv X509_PURPOSE_OCSP_HELPER
197.\" ocsp_helper, "OCSP helper"
198Nothing is required except that, if any extensions are present,
199parsing them needs to succeed.
200The application program is expected
201to do the actual checking by other means.
202.It Dv X509_PURPOSE_TIMESTAMP_SIGN
203.\" check_purpose_timestamp_sign, "Time Stamp signing"
204.Bl -dash -width 1n -compact
205.It
206The
207.Fa certificate
208contains an Extended Key Usage extension containing the RFC 5280
209.Dq Time Stamping
210purpose and no other purpose.
211This extension is marked as critical.
212.It
213If the
214.Fa certificate
215contains a Key Usage extension, at least one of the
216.Dv digitalSignature
217and
218.Dv nonRepudiation
219bits is set, and no other bits are set.
220.El
221.El
222.Pp
223If the
224.Fa purpose
225argument is not \-1 and the
226.Fa ca
227flag is non-zero,
228.Fn X509_check_purpose
229instead checks, in addition to the minimal sanity checks, whether the
230.Fa certificate
231can be used as a certificate authority certificate
232in the context of the given
233.Fa purpose .
234To succeed, the check always requires that none of the following
235conditions are violated:
236.Pp
237.Bl -dash -width 1n -compact
238.It
239If the
240.Fa certificate
241contains any extensions, parsing them succeeds.
242.It
243If the
244.Fa certificate
245contains a Key Usage extension, the
246.Dv keyCertSign
247bit is set.
248.It
249If the
250.Fa certificate
251contains a Basic Constraints extension, the
252.Fa cA
253field is set.
254.It
255If the
256.Fa certificate
257is a version 1 certificate, the subject name matches the issuer name
258and the certificate is self signed.
259.El
260.Pp
261The check succeeds if none of the additional conditions given in
262the list below are violated.
263.Bl -tag -width 1n
264.It Dv X509_PURPOSE_SSL_CLIENT
265.Bl -dash -width 1n -compact
266.It
267If the
268.Fa certificate
269contains an Extended Key Usage extension, it contains the RFC 5280
270.Dq TLS WWW client authentication
271purpose
272.Pq Dv NID_client_auth .
273.It
274If the
275.Fa certificate
276is not a version 1 certificate and does not contain a Basic Constraints
277extension, it contains a Key Usage extension with the
278.Dv keyCertSign
279bit set or a Netscape Cert Type extension with the
280.Dq SSL CA certificate
281bit set.
282.El
283.It Dv X509_PURPOSE_SSL_SERVER No or Dv X509_PURPOSE_NS_SSL_SERVER
284.Bl -dash -width 1n -compact
285.It
286If the
287.Fa certificate
288contains an Extended Key Usage extension, it contains the RFC 5280
289.Dq TLS WWW server authentication
290purpose
291.Pq Dv NID_server_auth
292or the private
293.Dq Netscape Server Gated Crypto
294.Pq Dv NID_ns_sgc
295or
296.Dq Microsoft Server Gated Crypto
297.Pq Dv NID_ms_sgc
298purpose.
299.It
300If the
301.Fa certificate
302is not a version 1 certificate and does not contain a Basic Constraints
303extension, it contains a Key Usage extension with the
304.Dv keyCertSign
305bit set or a Netscape Cert Type extension with the
306.Dq SSL CA certificate
307bit set.
308.El
309.It Dv X509_PURPOSE_SMIME_SIGN No or Dv X509_PURPOSE_SMIME_ENCRYPT
310.Bl -dash -width 1n -compact
311.It
312If the
313.Fa certificate
314contains an Extended Key Usage extension, it contains the RFC 5280
315.Dq Email protection
316purpose
317.Pq Dv NID_email_protect .
318.It
319If the
320.Fa certificate
321is not a version 1 certificate and does not contain a Basic Constraints
322extension, it contains a Key Usage extension with the
323.Dv keyCertSign
324bit set or a Netscape Cert Type extension with the
325.Dq S/MIME CA certificate
326bit set.
327.El
328.It Xo
329.Dv X509_PURPOSE_CRL_SIGN ,
330.Dv X509_PURPOSE_OCSP_HELPER ,
331or
332.Dv X509_PURPOSE_TIMESTAMP_SIGN
333.Xc
334.Bl -dash -width 1n -compact
335.It
336If the
337.Fa certificate
338is not a version 1 certificate and does not contain a Basic Constraints
339extension, it contains a Key Usage extension with the
340.Dv keyCertSign
341bit set or a Netscape Cert Type extension with at least one of the
342.Dq SSL CA certificate ,
343.Dq S/MIME CA certificate ,
344or
345.Dq Object-signing CA certificate
346bits set.
347.El
348.It Dv X509_PURPOSE_ANY
349Nothing is required except that, if any extensions are present,
350parsing them needs to succeed.
351The check even succeeds if the three other common conditions
352cited above this list are violated.
353.El
354.Pp
355If the function
356.Xr X509_PURPOSE_add 3
357was called before
358.Fn X509_check_purpose ,
359it may have installed different, user-supplied checking functions
360for some of the standard purposes listed above, or it may have
361installed additional, user-supplied checking functions for user-defined
362.Fa purpose
363identifiers not listed above.
364.Sh RETURN VALUES
365If the parsing of certificate extensions fails, sanity checks fail or the
366.Fa purpose
367is invalid,
368.Fn X509_check_purpose
369returns \-1 to indicate the error.
370.Pp
371If the
372.Fa purpose
373argument is \-1 and parsing and minimal sanity checks succeed,
374.Fn X509_check_purpose
375returns 1 to indicate success.
376.Pp
377Otherwise, it returns the following values:
378.Pp
379If
380.Fa ca
381is 0:
382.Bl -column -1 Failure -compact
383.It 0 Ta Failure Ta The
384.Fa certificate
385cannot be used for the
386.Fa purpose .
387.It 1 Ta Success Ta The
388.Fa certificate
389can be used for the
390.Fa purpose .
391.It 2 Ta Unknown Ta \&No decision can be made.
392.El
393.Pp
394If
395.Fa ca
396is non-zero:
397.Bl -column -1 Failure -compact
398.It 0 Ta Failure Ta The
399.Fa certificate
400cannot be used as a CA for the
401.Fa purpose .
402.It 1 Ta Success Ta The
403.Fa certificate
404can be used as a CA for the
405.Fa purpose .
406.It 3 Ta Success Ta The Fa certificate No is a version 1 CA .
407.It 4 Ta Success Ta The Key Usage allows Dv keyCertSign .
408.It 5 Ta Success Ta A Netscape Cert Type allows usage as a CA.
409.El
410.Sh SEE ALSO
411.Xr BASIC_CONSTRAINTS_new 3 ,
412.Xr EXTENDED_KEY_USAGE_new 3 ,
413.Xr X509_new 3 ,
414.Xr X509_PURPOSE_set 3 ,
415.Xr X509V3_get_d2i 3 ,
416.Xr x509v3.cnf 5
417.Sh STANDARDS
418RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
419Certificate Revocation List (CRL) Profile
420.Bl -dash -offset indent -compact
421.It
422section 4.2.1.3: Key Usage
423.It
424section 4.2.1.9: Basic Constraints
425.It
426section 4.2.1.12: Extended Key Usage
427.El
428.Sh HISTORY
429.Fn X509_check_purpose
430first appeared in OpenSSL 0.9.5 and has been available since
431.Ox 2.7 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-23 13:37:03 +0000