xref: /openbsd-src/lib/libcrypto/man/X509_check_purpose.3 (revision 4e1ee0786f11cc571bd0be17d38e46f635c719fc) 
1.\" $OpenBSD: X509_check_purpose.3,v 1.6 2021/07/27 13:27:46 schwarze 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: July 27 2021 $
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 ca
34flag is 0,
35.Fn X509_check_purpose
36checks whether the public key contained in the
37.Fa certificate
38is intended to be used for the given
39.Fa purpose ,
40which can be one of the following integer constants.
41The check succeeds if none of the conditions given in the list below
42are violated.
43.Bl -tag -width 1n
44.It Dv X509_PURPOSE_SSL_CLIENT
45.Bl -dash -width 1n -compact
46.It
47If the
48.Fa certificate
49contains an Extended Key Usage extension, it contains the RFC 5280
50.Dq TLS WWW client authentication
51purpose
52.Pq Dv NID_client_auth .
53.It
54If the
55.Fa certificate
56contains a Key Usage extension, the
57.Dv digitalSignature
58bit is set.
59.It
60If the
61.Fa certificate
62contains a Netscape Cert Type extension, the
63.Dq SSL client certificate
64bit is set
65.Pq Dv NS_SSL_CLIENT .
66.El
67.It Dv X509_PURPOSE_SSL_SERVER
68.Bl -dash -width 1n -compact
69.It
70If the
71.Fa certificate
72contains an Extended Key Usage extension, it contains the RFC 5280
73.Dq TLS WWW server authentication
74purpose
75.Pq Dv NID_server_auth
76or the private
77.Dq Netscape Server Gated Crypto
78.Pq Dv NID_ns_sgc
79or
80.Dq Microsoft Server Gated Crypto
81.Pq Dv NID_ms_sgc
82purpose.
83.It
84If the
85.Fa certificate
86contains a Key Usage extension, at least one of the
87.Dv digitalSignature
88and
89.Dv keyEncipherment
90bits is set.
91.It
92If the
93.Fa certificate
94contains a Netscape Cert Type extension, the
95.Dq SSL server certificate
96bit is set
97.Pq Dv NS_SSL_SERVER
98.El
99.It Dv X509_PURPOSE_NS_SSL_SERVER
100.\" check_purpose_ns_ssl_server, "Netscape SSL server"
101This does the same checks as
102.Dv X509_PURPOSE_SSL_SERVER
103and additionally requires that a Key Usage extension, if present,
104has the
105.Dv keyEncipherment
106bit set.
107.It Dv X509_PURPOSE_SMIME_SIGN
108.\" check_purpose_smime_sign, "S/MIME signing"
109.Bl -dash -width 1n -compact
110.It
111If the
112.Fa certificate
113contains an Extended Key Usage extension, it contains the RFC 5280
114.Dq Email protection
115purpose
116.Pq Dv NID_email_protect .
117.It
118If the
119.Fa certificate
120contains a Key Usage extension, at least one of the
121.Dv digitalSignature
122and
123.Dv nonRepudiation
124bits is set.
125.It
126If the
127.Fa certificate
128contains a Netscape Cert Type extension, it has the
129.Dq S/MIME certificate
130bit set.
131If the
132.Dq SSL client certificate
133bit is set but the
134.Dq S/MIME certificate
135bit is not, no decision is made.
136.El
137.It Dv X509_PURPOSE_SMIME_ENCRYPT
138.\" check_purpose_smime_encrypt, "S/MIME encryption"
139.Bl -dash -width 1n -compact
140.It
141If the
142.Fa certificate
143contains an Extended Key Usage extension, it contains the RFC 5280
144.Dq Email protection
145purpose
146.Pq Dv NID_email_protect .
147.It
148If the
149.Fa certificate
150contains a Key Usage extension, the
151.Dv keyEncipherment
152bit is set.
153.It
154If the
155.Fa certificate
156contains a Netscape Cert Type extension, it has the
157.Dq S/MIME certificate
158bit set.
159If the
160.Dq SSL client certificate
161bit is set but the
162.Dq S/MIME certificate
163bit is not, no decision is made.
164.El
165.It Dv X509_PURPOSE_CRL_SIGN
166.\" check_purpose_crl_sign, "CRL signing"
167.Bl -dash -width 1n -compact
168.It
169If the
170.Fa certificate
171contains a Key Usage extension, the
172.Dv cRLSign
173bit is set.
174.El
175.It Dv X509_PURPOSE_ANY
176The check always succeeds.
177.It Dv X509_PURPOSE_OCSP_HELPER
178.\" ocsp_helper, "OCSP helper"
179The check always succeeds.
180The application program is expected
181to do the actual checking by other means.
182.It Dv X509_PURPOSE_TIMESTAMP_SIGN
183.\" check_purpose_timestamp_sign, "Time Stamp signing"
184.Bl -dash -width 1n -compact
185.It
186The
187.Fa certificate
188contains an Extended Key Usage extension containing the RFC 5280
189.Dq Time Stamping
190purpose and no other purpose.
191This extension is marked as critical.
192.It
193If the
194.Fa certificate
195contains a Key Usage extension, at least one of the
196.Dv digitalSignature
197and
198.Dv nonRepudiation
199bits is set, and no other bits are set.
200.El
201.El
202.Pp
203If the
204.Fa ca
205flag is non-zero,
206.Fn X509_check_purpose
207instead checks whether the
208.Fa certificate
209can be used as a certificate authority certificate
210in the context of the given
211.Fa purpose .
212To succeed, the check always requires that none of the following
213conditions are violated:
214.Pp
215.Bl -dash -width 1n -compact
216.It
217If the
218.Fa certificate
219contains a Key Usage extension, the
220.Dv keyCertSign
221bit is set.
222.It
223If the
224.Fa certificate
225contains a Basic Constraints extension, the
226.Fa cA
227field is set.
228.It
229If the
230.Fa certificate
231is a version 1 certificate, the subject name matches the issuer name
232and the certificate is self signed.
233.El
234.Pp
235The check succeeds if none of the additional conditions given in
236the list below are violated.
237.Bl -tag -width 1n
238.It Dv X509_PURPOSE_SSL_CLIENT
239.Bl -dash -width 1n -compact
240.It
241If the
242.Fa certificate
243contains an Extended Key Usage extension, it contains the RFC 5280
244.Dq TLS WWW client authentication
245purpose
246.Pq Dv NID_client_auth .
247.It
248If the
249.Fa certificate
250is not a version 1 certificate and does not contain a Basic Constraints
251extension, it contains a Key Usage extension with the
252.Dv keyCertSign
253bit set or a Netscape Cert Type extension with the
254.Dq SSL CA certificate
255bit set.
256.El
257.It Dv X509_PURPOSE_SSL_SERVER No or Dv X509_PURPOSE_NS_SSL_SERVER
258.Bl -dash -width 1n -compact
259.It
260If the
261.Fa certificate
262contains an Extended Key Usage extension, it contains the RFC 5280
263.Dq TLS WWW server authentication
264purpose
265.Pq Dv NID_server_auth
266or the private
267.Dq Netscape Server Gated Crypto
268.Pq Dv NID_ns_sgc
269or
270.Dq Microsoft Server Gated Crypto
271.Pq Dv NID_ms_sgc
272purpose.
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_SMIME_SIGN No or Dv X509_PURPOSE_SMIME_ENCRYPT
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 Email protection
290purpose
291.Pq Dv NID_email_protect .
292.It
293If the
294.Fa certificate
295is not a version 1 certificate and does not contain a Basic Constraints
296extension, it contains a Key Usage extension with the
297.Dv keyCertSign
298bit set or a Netscape Cert Type extension with the
299.Dq S/MIME CA certificate
300bit set.
301.El
302.It Xo
303.Dv X509_PURPOSE_CRL_SIGN ,
304.Dv X509_PURPOSE_OCSP_HELPER ,
305or
306.Dv X509_PURPOSE_TIMESTAMP_SIGN
307.Xc
308.Bl -dash -width 1n -compact
309.It
310If the
311.Fa certificate
312is not a version 1 certificate and does not contain a Basic Constraints
313extension, it contains a Key Usage extension with the
314.Dv keyCertSign
315bit set or a Netscape Cert Type extension with at least one of the
316.Dq SSL CA certificate ,
317.Dq S/MIME CA certificate ,
318or
319.Dq Object-signing CA certificate
320bits set.
321.El
322.It Dv X509_PURPOSE_ANY
323The check always succeeds, even if the three common conditions
324cited above this list are violated.
325.El
326.Pp
327If the
328.Fa purpose
329is -1,
330.Fn X509_check_purpose
331always succeeds, no matter whether or not the
332.Fa ca
333flag is set.
334.Pp
335If the function
336.Xr X509_PURPOSE_add 3
337was called before
338.Fn X509_check_purpose ,
339it may have installed different, user-supplied checking functions
340for some of the standard purposes listed above, or it may have
341installed additional, user-supplied checking functions for user-defined
342.Fa purpose
343identifiers not listed above.
344.Sh RETURN VALUES
345.Fn X509_check_purpose
346returns the following values:
347.Bl -column -1 Failure -compact
348.It -1 Ta Error Ta The
349.Fa purpose
350is invalid.
351.It 0 Ta Failure Ta The
352.Fa certificate
353cannot be used for the
354.Fa purpose .
355.El
356.Pp
357If
358.Fa ca
359is 0, the following values can also be returned:
360.Bl -column -1 Failure -compact
361.It 1 Ta Success Ta The
362.Fa certificate
363can be used for the
364.Fa purpose .
365.It 2 Ta Unknown Ta \&No decision can be made.
366.El
367.Pp
368If
369.Fa ca
370is non-zero, the following values can also be returned:
371.Bl -column -1 Failure -compact
372.It 1 Ta Success Ta The
373.Fa certificate
374can be used as a CA for the
375.Fa purpose .
376.It 3 Ta Success Ta The Fa certificate No is a version 1 CA .
377.It 4 Ta Success Ta The Key Usage allows Dv keyCertSign .
378.It 5 Ta Success Ta A Netscape Cert Type allows usage as a CA.
379.El
380.Sh SEE ALSO
381.Xr BASIC_CONSTRAINTS_new 3 ,
382.Xr EXTENDED_KEY_USAGE_new 3 ,
383.Xr X509_check_trust 3 ,
384.Xr X509_new 3 ,
385.Xr X509_policy_check 3 ,
386.Xr X509_PURPOSE_set 3 ,
387.Xr X509V3_get_d2i 3 ,
388.Xr x509v3.cnf 5
389.Sh STANDARDS
390RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
391Certificate Revocation List (CRL) Profile
392.Bl -dash -offset indent -compact
393.It
394section 4.2.1.3: Key Usage
395.It
396section 4.2.1.9: Basic Constraints
397.It
398section 4.2.1.12: Extended Key Usage
399.El
400.Sh HISTORY
401.Fn X509_check_purpose
402first appeared in OpenSSL 0.9.5 and has been available since
403.Ox 2.7 .
404