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