Debian Codegraph @

upstream/debian-unstable/man3/X509_check_purpose.3ssl

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 "X509_CHECK_PURPOSE 3SSL"
58 .TH X509_CHECK_PURPOSE 3SSL 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 X509_check_purpose,
65 X509_PURPOSE_get_count,
66 X509_PURPOSE_get_unused_id,
67 X509_PURPOSE_get_by_sname,
68 X509_PURPOSE_get_by_id,
69 X509_PURPOSE_add,
70 X509_PURPOSE_cleanup,
71 X509_PURPOSE_get0,
72 X509_PURPOSE_get_id,
73 X509_PURPOSE_get0_name,
74 X509_PURPOSE_get0_sname,
75 X509_PURPOSE_get_trust,
76 X509_PURPOSE_set \- functions related to checking the purpose of a certificate
77 .SH SYNOPSIS
78 .IX Header "SYNOPSIS"
79 .Vb 1
80 \& #include <openssl/x509v3.h>
81 \&
82 \& int X509_check_purpose(X509 *x, int id, int ca);
83 \&
84 \& int X509_PURPOSE_get_count(void);
85 \& int X509_PURPOSE_get_unused_id(OSSL_LIB_CTX *libctx);
86 \& int X509_PURPOSE_get_by_sname(const char *sname);
87 \& int X509_PURPOSE_get_by_id(int id);
88 \& int X509_PURPOSE_add(int id, int trust, int flags,
89 \& int (*ck) (const X509_PURPOSE *, const X509 *, int),
90 \& const char *name, const char *sname, void *arg);
91 \& void X509_PURPOSE_cleanup(void);
92 \&
93 \& X509_PURPOSE *X509_PURPOSE_get0(int idx);
94 \& int X509_PURPOSE_get_id(const X509_PURPOSE *);
95 \& char *X509_PURPOSE_get0_name(const X509_PURPOSE *xp);
96 \& char *X509_PURPOSE_get0_sname(const X509_PURPOSE *xp);
97 \& int X509_PURPOSE_get_trust(const X509_PURPOSE *xp);
98 \& int X509_PURPOSE_set(int *p, int purpose);
99 .Ve
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 \&\fBX509_check_purpose()\fR checks if certificate \fIx\fR was created with the purpose
103 represented by \fIid\fR. If \fIca\fR is nonzero, then certificate \fIx\fR is
104 checked to determine if it's a possible CA with various levels of certainty
105 possibly returned. The certificate \fIx\fR must be a complete certificate
106 otherwise the function returns an error.
107 .PP
108 Below are the potential ID's that can be checked:
109 .PP
110 .Vb 10
111 \& # define X509_PURPOSE_SSL_CLIENT 1
112 \& # define X509_PURPOSE_SSL_SERVER 2
113 \& # define X509_PURPOSE_NS_SSL_SERVER 3
114 \& # define X509_PURPOSE_SMIME_SIGN 4
115 \& # define X509_PURPOSE_SMIME_ENCRYPT 5
116 \& # define X509_PURPOSE_CRL_SIGN 6
117 \& # define X509_PURPOSE_ANY 7
118 \& # define X509_PURPOSE_OCSP_HELPER 8
119 \& # define X509_PURPOSE_TIMESTAMP_SIGN 9
120 \& # define X509_PURPOSE_CODE_SIGN 10
121 .Ve
122 .PP
123 The checks performed take into account the X.509 extensions
124 keyUsage, extendedKeyUsage, and basicConstraints.
125 .PP
126 \&\fBX509_PURPOSE_get_count()\fR returns the number of currently defined purposes.
127 .PP
128 \&\fBX509_PURPOSE_get_unused_id()\fR returns the smallest purpose id not yet used,
129 which is guaranteed to be unique and larger than \fBX509_PURPOSE_MAX\fR.
130 The \fIlibctx\fR parameter should be used to provide the library context.
131 It is currently ignored as the purpose mapping table is global.
132 .PP
133 \&\fBX509_PURPOSE_get_by_sname()\fR returns the index of
134 the purpose with the given short name or \-1 if not found.
135 .PP
136 \&\fBX509_PURPOSE_get_by_id()\fR returns the index of
137 the purpose with the given id or \-1 if not found.
138 .PP
139 \&\fBX509_PURPOSE_add()\fR adds or modifies a purpose entry identified by \fIsname\fR.
140 Unless the id stays the same for an existing entry, \fIid\fR must be fresh,
141 which can be achieved by using the result of \fBX509_PURPOSE_get_unused_id()\fR.
142 The function also sets in the entry the trust id \fItrust\fR, the given \fIflags\fR,
143 the purpose (long) name \fIname\fR, the short name \fIsname\fR, the purpose checking
144 function \fIck\fR of type \fBint (*) (const X509_PURPOSE *, const X509 *, int)\fR,
145 and its user data \fIarg\fR which may be retrieved via the \fBX509_PURPOSE\fR pointer.
146 .PP
147 \&\fBX509_PURPOSE_cleanup()\fR removes all purposes that are not pre-defined.
148 .PP
149 \&\fBX509_PURPOSE_get0()\fR returns an \fBX509_PURPOSE\fR pointer or NULL on error.
150 .PP
151 \&\fBX509_PURPOSE_get_id()\fR returns the id of the given \fBX509_PURPOSE\fR structure.
152 .PP
153 \&\fBX509_PURPOSE_get0_name()\fR returns the (long) name of the given \fBX509_PURPOSE\fR.
154 .PP
155 \&\fBX509_PURPOSE_get0_sname()\fR returns the short name of the given \fBX509_PURPOSE\fR.
156 .PP
157 \&\fBX509_PURPOSE_get_trust()\fR returns the trust id of the given \fBX509_PURPOSE\fR.
158 .PP
159 \&\fBX509_PURPOSE_set()\fR assigns the given \fIpurpose\fR id to the location pointed at by
160 \&\fIp\fR.
161 This resets to the any purpose if \fIpurpose\fR is \fBX509_PURPOSE_DEFAULT_ANY\fR.
162 .SH "RETURN VALUES"
163 .IX Header "RETURN VALUES"
164 \&\fBX509_check_purpose()\fR returns the following values.
165 For non-CA checks
166 .IP "\-1 an error condition has occurred" 4
167 .IX Item "-1 an error condition has occurred"
168 .PD 0
169 .IP " 1 if the certificate was created to perform the purpose represented by \fIid\fR" 4
170 .IX Item " 1 if the certificate was created to perform the purpose represented by id"
171 .IP " 0 if the certificate was not created to perform the purpose represented by \fIid\fR" 4
172 .IX Item " 0 if the certificate was not created to perform the purpose represented by id"
173 .PD
174 .PP
175 For CA checks the below integers could be returned with the following meanings:
176 .IP "\-1 an error condition has occurred" 4
177 .IX Item "-1 an error condition has occurred"
178 .PD 0
179 .IP " 0 not a CA or does not have the purpose represented by \fIid\fR" 4
180 .IX Item " 0 not a CA or does not have the purpose represented by id"
181 .IP " 1 is a CA." 4
182 .IX Item " 1 is a CA."
183 .IP " 2 Only possible in old versions of openSSL when basicConstraints are absent. New versions will not return this value. May be a CA" 4
184 .IX Item " 2 Only possible in old versions of openSSL when basicConstraints are absent. New versions will not return this value. May be a CA"
185 .IP " 3 basicConstraints absent but self signed V1." 4
186 .IX Item " 3 basicConstraints absent but self signed V1."
187 .IP " 4 basicConstraints absent but keyUsage present and keyCertSign asserted." 4
188 .IX Item " 4 basicConstraints absent but keyUsage present and keyCertSign asserted."
189 .IP " 5 legacy Netscape specific CA Flags present" 4
190 .IX Item " 5 legacy Netscape specific CA Flags present"
191 .PD
192 .PP
193 \&\fBX509_PURPOSE_get_count()\fR returns the number of currently defined purposes.
194 .PP
195 \&\fBX509_PURPOSE_get_unused_id()\fR returns the smallest purpose id not yet used.
196 .PP
197 \&\fBX509_PURPOSE_get_by_sname()\fR returns the index of
198 the purpose with the given short name or \-1 if not found.
199 .PP
200 \&\fBX509_PURPOSE_get_by_id()\fR returns the index of
201 the purpose with the given id or \-1 if not found.
202 .PP
203 int \fBX509_PURPOSE_add()\fR returns 1 on success, 0 on error.
204 .PP
205 \&\fBX509_PURPOSE_cleanup()\fR does not return anything.
206 .PP
207 \&\fBX509_PURPOSE_get0()\fR returns an \fBX509_PURPOSE\fR pointer or NULL on error.
208 .PP
209 \&\fBX509_PURPOSE_get_id()\fR returns the id of the given \fBX509_PURPOSE\fR structure.
210 .PP
211 \&\fBX509_PURPOSE_get0_name()\fR returns the (long) name of the given \fBX509_PURPOSE\fR.
212 .PP
213 \&\fBX509_PURPOSE_get0_sname()\fR returns the short name of the given \fBX509_PURPOSE\fR.
214 .PP
215 \&\fBX509_PURPOSE_get_trust()\fR returns the trust id of the given \fBX509_PURPOSE\fR.
216 .PP
217 \&\fBX509_PURPOSE_set()\fR returns 1 on success, 0 on error.
218 .SH BUGS
219 .IX Header "BUGS"
220 The X509_PURPOSE implementation so far is not thread-safe.
221 There may be race conditions retrieving purpose information while
222 \&\fBX509_PURPOSE_add()\fR or X509_PURPOSE_cleanup(void) is being called.
223 .SH HISTORY
224 .IX Header "HISTORY"
225 \&\fBX509_PURPOSE_get_unused_id()\fR was added in OpensSL 3.5.
226 .SH COPYRIGHT
227 .IX Header "COPYRIGHT"
228 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
229 Licensed under the Apache License 2.0 (the "License"). You may not use this
230 file except in compliance with the License. You can obtain a copy in the file
231 LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.