summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/X509V3_get_d2i.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/X509V3_get_d2i.3')
-rw-r--r--src/lib/libcrypto/man/X509V3_get_d2i.3507
1 files changed, 0 insertions, 507 deletions
diff --git a/src/lib/libcrypto/man/X509V3_get_d2i.3 b/src/lib/libcrypto/man/X509V3_get_d2i.3
deleted file mode 100644
index bf442dc846..0000000000
--- a/src/lib/libcrypto/man/X509V3_get_d2i.3
+++ /dev/null
@@ -1,507 +0,0 @@
1.\" $OpenBSD: X509V3_get_d2i.3,v 1.25 2024/12/31 20:17:00 tb Exp $
2.\" full merge up to: OpenSSL ff7fbfd5 Nov 2 11:52:01 2015 +0000
3.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2023, 2024 Theo Buehler <tb@openbsd.org>
9.\" Copyright (c) 2024 Ingo Schwarze <schwarze@openbsd.org>
10.\"
11.\" Permission to use, copy, modify, and distribute this software for any
12.\" purpose with or without fee is hereby granted, provided that the above
13.\" copyright notice and this permission notice appear in all copies.
14.\"
15.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
16.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
17.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
18.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
21.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22.\"
23.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
24.\" Copyright (c) 2014, 2015, 2016 The OpenSSL Project. All rights reserved.
25.\"
26.\" Redistribution and use in source and binary forms, with or without
27.\" modification, are permitted provided that the following conditions
28.\" are met:
29.\"
30.\" 1. Redistributions of source code must retain the above copyright
31.\" notice, this list of conditions and the following disclaimer.
32.\"
33.\" 2. Redistributions in binary form must reproduce the above copyright
34.\" notice, this list of conditions and the following disclaimer in
35.\" the documentation and/or other materials provided with the
36.\" distribution.
37.\"
38.\" 3. All advertising materials mentioning features or use of this
39.\" software must display the following acknowledgment:
40.\" "This product includes software developed by the OpenSSL Project
41.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
42.\"
43.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
44.\" endorse or promote products derived from this software without
45.\" prior written permission. For written permission, please contact
46.\" openssl-core@openssl.org.
47.\"
48.\" 5. Products derived from this software may not be called "OpenSSL"
49.\" nor may "OpenSSL" appear in their names without prior written
50.\" permission of the OpenSSL Project.
51.\"
52.\" 6. Redistributions of any form whatsoever must retain the following
53.\" acknowledgment:
54.\" "This product includes software developed by the OpenSSL Project
55.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
56.\"
57.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
58.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
60.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
61.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
62.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
63.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
64.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
65.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
66.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
68.\" OF THE POSSIBILITY OF SUCH DAMAGE.
69.\"
70.Dd $Mdocdate: December 31 2024 $
71.Dt X509V3_GET_D2I 3
72.Os
73.Sh NAME
74.Nm X509V3_get_d2i ,
75.Nm X509V3_add1_i2d ,
76.Nm X509V3_EXT_d2i ,
77.Nm X509V3_EXT_i2d ,
78.Nm X509_get_ext_d2i ,
79.Nm X509_add1_ext_i2d ,
80.Nm X509_CRL_get_ext_d2i ,
81.Nm X509_CRL_add1_ext_i2d ,
82.Nm X509_REVOKED_get_ext_d2i ,
83.Nm X509_REVOKED_add1_ext_i2d ,
84.Nm X509_get0_extensions ,
85.Nm X509_CRL_get0_extensions ,
86.Nm X509_REVOKED_get0_extensions ,
87.Nm X509_get0_uids
88.Nd X509 extension decode and encode functions
89.Sh SYNOPSIS
90.In openssl/x509v3.h
91.Ft void *
92.Fo X509V3_get_d2i
93.Fa "const STACK_OF(X509_EXTENSION) *x"
94.Fa "int nid"
95.Fa "int *crit"
96.Fa "int *idx"
97.Fc
98.Ft int
99.Fo X509V3_add1_i2d
100.Fa "STACK_OF(X509_EXTENSION) **x"
101.Fa "int nid"
102.Fa "void *value"
103.Fa "int crit"
104.Fa "unsigned long flags"
105.Fc
106.Ft void *
107.Fo X509V3_EXT_d2i
108.Fa "X509_EXTENSION *ext"
109.Fc
110.Ft X509_EXTENSION *
111.Fo X509V3_EXT_i2d
112.Fa "int ext_nid"
113.Fa "int crit"
114.Fa "void *ext"
115.Fc
116.Ft void *
117.Fo X509_get_ext_d2i
118.Fa "const X509 *x"
119.Fa "int nid"
120.Fa "int *crit"
121.Fa "int *idx"
122.Fc
123.Ft int
124.Fo X509_add1_ext_i2d
125.Fa "X509 *x"
126.Fa "int nid"
127.Fa "void *value"
128.Fa "int crit"
129.Fa "unsigned long flags"
130.Fc
131.Ft void *
132.Fo X509_CRL_get_ext_d2i
133.Fa "const X509_CRL *crl"
134.Fa "int nid"
135.Fa "int *crit"
136.Fa "int *idx"
137.Fc
138.Ft int
139.Fo X509_CRL_add1_ext_i2d
140.Fa "X509_CRL *crl"
141.Fa "int nid"
142.Fa "void *value"
143.Fa "int crit"
144.Fa "unsigned long flags"
145.Fc
146.Ft void *
147.Fo X509_REVOKED_get_ext_d2i
148.Fa "const X509_REVOKED *r"
149.Fa "int nid"
150.Fa "int *crit"
151.Fa "int *idx"
152.Fc
153.Ft int
154.Fo X509_REVOKED_add1_ext_i2d
155.Fa "X509_REVOKED *r"
156.Fa "int nid"
157.Fa "void *value"
158.Fa "int crit"
159.Fa "unsigned long flags"
160.Fc
161.Ft const STACK_OF(X509_EXTENSION) *
162.Fo X509_get0_extensions
163.Fa "const X509 *x"
164.Fc
165.Ft const STACK_OF(X509_EXTENSION) *
166.Fo X509_CRL_get0_extensions
167.Fa "const X509_CRL *crl"
168.Fc
169.Ft const STACK_OF(X509_EXTENSION) *
170.Fo X509_REVOKED_get0_extensions
171.Fa "const X509_REVOKED *r"
172.Fc
173.Ft void
174.Fo X509_get0_uids
175.Fa "const X509 *x"
176.Fa "const ASN1_BIT_STRING **issuerUID"
177.Fa "const ASN1_BIT_STRING **subjectUID"
178.Fc
179.Sh DESCRIPTION
180.Fn X509V3_get_d2i
181looks for an extension with OID
182.Fa nid
183in the extensions
184.Fa x
185and, if found, decodes it.
186If
187.Fa idx
188is
189.Dv NULL ,
190then only one occurrence of an extension is permissible.
191Otherwise the first extension after index
192.Pf * Fa idx
193is returned and
194.Pf * Fa idx
195is updated to the location of the extension.
196If
197.Fa crit
198is not
199.Dv NULL ,
200then
201.Pf * Fa crit
202is set to a status value: -2 if the extension occurs multiple times
203(this is only returned if
204.Fa idx
205is
206.Dv NULL ) ,
207-1 if the extension could not be found, 0 if the extension is found
208and is not critical, and 1 if it is critical.
209A pointer to an extension specific structure or
210.Dv NULL
211is returned.
212.Pp
213.Fn X509V3_add1_i2d
214adds extension
215.Fa value
216to STACK
217.Pf * Fa x
218(allocating a new STACK if necessary) using OID
219.Fa nid
220and criticality
221.Fa crit
222according to
223.Fa flags .
224.Pp
225.Fn X509V3_EXT_d2i
226attempts to decode the ASN.1 data contained in extension
227.Fa ext
228and returns a pointer to an extension specific structure or
229.Dv NULL
230if the extension could not be decoded (invalid syntax or not supported).
231.Pp
232.Fn X509V3_EXT_i2d
233encodes the extension specific structure
234.Fa ext
235with OID
236.Fa ext_nid
237and criticality
238.Fa crit .
239.Pp
240.Fn X509_get_ext_d2i
241and
242.Fn X509_add1_ext_i2d
243operate on the extensions of certificate
244.Fa x ,
245and are otherwise identical to
246.Fn X509V3_get_d2i
247and
248.Fn X509V3_add1_i2d .
249.Pp
250.Fn X509_CRL_get_ext_d2i
251and
252.Fn X509_CRL_add1_ext_i2d
253operate on the extensions of CRL
254.Fa crl ,
255and are otherwise identical to
256.Fn X509V3_get_d2i
257and
258.Fn X509V3_add1_i2d .
259.Pp
260.Fn X509_REVOKED_get_ext_d2i
261and
262.Fn X509_REVOKED_add1_ext_i2d
263operate on the extensions of the
264.Vt X509_REVOKED
265structure
266.Fa r
267(i.e. for CRL entry extensions), and are otherwise identical to
268.Fn X509V3_get_d2i
269and
270.Fn X509V3_add1_i2d .
271.Pp
272.Fn X509_get0_extensions ,
273.Fn X509_CRL_get0_extensions ,
274and
275.Fn X509_REVOKED_get0_extensions
276return a stack of all the extensions of a certificate, a CRL,
277or a CRL entry, respectively.
278.Pp
279In almost all cases an extension can occur at most once and multiple
280occurrences is an error.
281Therefore the
282.Fa idx
283parameter is usually
284.Dv NULL .
285.Pp
286The
287.Fa flags
288argument consists of two parts OR'ed together:
289the operation mode and the optional silent flag.
290The operation mode is the bitwise OR of the
291.Fa flags
292and the bitmask
293.Dv X509V3_ADD_OP_MASK .
294The following operation modes are recognized:
295.Pp
296.Dv X509V3_ADD_DEFAULT
297appends a new extension only if the extension does not already exist.
298An error is returned if the extension does already exist.
299.Pp
300.Dv X509V3_ADD_APPEND
301appends a new extension, ignoring whether the extension already exists.
302This is a misfeature and should not be used because certificates must
303not include the same extension more than once.
304.Pp
305.Dv X509V3_ADD_REPLACE
306replaces an extension if it exists otherwise appends a new extension.
307.Pp
308.Dv X509V3_ADD_REPLACE_EXISTING
309replaces an existing extension if it exists otherwise returns an error.
310.Pp
311.Dv X509V3_ADD_KEEP_EXISTING
312appends a new extension only if the extension does not already exist.
313An error
314.Sy is not
315returned if the extension does already exist.
316.Pp
317.Dv X509V3_ADD_DELETE
318deletes extension
319.Fa nid
320if it exists and errors otherwise.
321No new extension is added.
322.Pp
323Any other operation mode results in an error.
324.Pp
325If
326.Dv X509V3_ADD_SILENT
327is OR'd into the
328.Fa flags ,
329any error returned will not be added to the error queue.
330.Pp
331The function
332.Fn X509V3_get_d2i
333will return
334.Dv NULL
335if the extension is not found, occurs multiple times or cannot be
336decoded.
337It is possible to determine the precise reason by checking the value of
338.Pf * Fa crit .
339.Pp
340.Fn X509_get0_uids
341returns the issuer and subject unique identifiers of the certificate
342.Fa x
343in
344.Pf * Fa issuerUID
345and
346.Pf * Fa subjectUID .
347If a unique identifier field is not present in
348.Fa x ,
349.Dv NULL
350is returned.
351Either one of
352.Fa issuerUID
353and
354.Fa subjectUID
355can be
356.Dv NULL .
357.Sh SUPPORTED EXTENSIONS
358The following sections contain a list of all supported extensions
359including their name and NID.
360.Ss PKIX Certificate Extensions
361The following certificate extensions are defined in PKIX standards such
362as RFC 5280.
363.Bl -column 30n 30n
364.It Basic Constraints Ta Dv NID_basic_constraints
365.It Key Usage Ta Dv NID_key_usage
366.It Extended Key Usage Ta Dv NID_ext_key_usage
367.It Subject Key Identifier Ta Dv NID_subject_key_identifier
368.It Authority Key Identifier Ta Dv NID_authority_key_identifier
369.It Private Key Usage Period Ta Dv NID_private_key_usage_period
370.It Subject Alternative Name Ta Dv NID_subject_alt_name
371.It Issuer Alternative Name Ta Dv NID_issuer_alt_name
372.It Authority Information Access Ta Dv NID_info_access
373.It Subject Information Access Ta Dv NID_sinfo_access
374.It Name Constraints Ta Dv NID_name_constraints
375.It Certificate Policies Ta Dv NID_certificate_policies
376.It Policy Mappings Ta Dv NID_policy_mappings
377.It Policy Constraints Ta Dv NID_policy_constraints
378.It Inhibit Any Policy Ta Dv NID_inhibit_any_policy
379.It IP Address Delegation Ta Dv NID_sbgp_ipAddrBlock
380.It Autonomous System Identifier Delegation\
381 Ta Dv NID_sbgp_autonomousSysNum
382.El
383.Ss Netscape Certificate Extensions
384The following are (largely obsolete) Netscape certificate extensions.
385.Bl -column 30n 30n
386.It Netscape Cert Type Ta Dv NID_netscape_cert_type
387.It Netscape Base Url Ta Dv NID_netscape_base_url
388.It Netscape Revocation Url Ta Dv NID_netscape_revocation_url
389.It Netscape CA Revocation Url Ta Dv NID_netscape_ca_revocation_url
390.It Netscape Renewal Url Ta Dv NID_netscape_renewal_url
391.It Netscape CA Policy Url Ta Dv NID_netscape_ca_policy_url
392.It Netscape SSL Server Name Ta Dv NID_netscape_ssl_server_name
393.It Netscape Comment Ta Dv NID_netscape_comment
394.El
395.Ss PKIX CRL Extensions
396The following are CRL extensions from PKIX standards such as RFC 5280.
397.Bl -column 30n 30n
398.It CRL Number Ta Dv NID_crl_number
399.It CRL Distribution Points Ta Dv NID_crl_distribution_points
400.It Delta CRL Indicator Ta Dv NID_delta_crl
401.It Freshest CRL Ta Dv NID_freshest_crl
402.It Invalidity Date Ta Dv NID_invalidity_date
403.It Issuing Distribution Point Ta Dv NID_issuing_distribution_point
404.El
405.Pp
406The following are CRL entry extensions from PKIX standards such as
407RFC 5280.
408.Bl -column 30n 30n
409.It CRL Reason Code Ta Dv NID_crl_reason
410.It Certificate Issuer Ta Dv NID_certificate_issuer
411.El
412.Ss OCSP Extensions
413.Bl -column 30n 30n
414.It OCSP Nonce Ta Dv NID_id_pkix_OCSP_Nonce
415.It OCSP CRL ID Ta Dv NID_id_pkix_OCSP_CrlID
416.It Acceptable OCSP Responses Ta Dv NID_id_pkix_OCSP_acceptableResponses
417.It OCSP No Check Ta Dv NID_id_pkix_OCSP_noCheck
418.It OCSP Archive Cutoff Ta Dv NID_id_pkix_OCSP_archiveCutoff
419.It OCSP Service Locator Ta Dv NID_id_pkix_OCSP_serviceLocator
420.It Hold Instruction Code Ta Dv NID_hold_instruction_code
421.El
422.Sh RETURN VALUES
423.Fn X509V3_get_d2i ,
424.Fn X509V3_EXT_d2i ,
425.Fn X509_get_ext_d2i ,
426.Fn X509_CRL_get_ext_d2i ,
427and
428.Fn X509_REVOKED_get_ext_d2i
429return a pointer to an extension specific structure or
430.Dv NULL
431if an error occurs.
432.Pp
433.Fn X509V3_add1_i2d ,
434.Fn X509_add1_ext_i2d ,
435.Fn X509_CRL_add1_ext_i2d ,
436and
437.Fn X509_REVOKED_add1_ext_i2d
438return 1 if the operation is successful, 0 if it fails due to a
439non-fatal error (extension not found, already exists, cannot be encoded),
440or -1 due to a fatal error such as a memory allocation failure.
441In some cases of failure, the reason can be determined with
442.Xr ERR_get_error 3 .
443.Pp
444The
445.Fn X509V3_EXT_i2d
446function returns a pointer to an
447.Vt X509_EXTENSION
448structure if successful; otherwise
449.Dv NULL
450is returned and an error code can be retrieved with
451.Xr ERR_get_error 3 .
452.Pp
453.Fn X509_get0_extensions ,
454.Fn X509_CRL_get0_extensions ,
455and
456.Fn X509_REVOKED_get0_extensions
457return a stack of extensions, or
458.Dv NULL
459if no extensions are present.
460.Sh SEE ALSO
461.Xr d2i_X509 3 ,
462.Xr d2i_X509_EXTENSION 3 ,
463.Xr X509_check_purpose 3 ,
464.Xr X509_CRL_get0_by_serial 3 ,
465.Xr X509_CRL_new 3 ,
466.Xr X509_EXTENSION_new 3 ,
467.Xr X509_get_pubkey 3 ,
468.Xr X509_get_subject_name 3 ,
469.Xr X509_get_version 3 ,
470.Xr X509_new 3 ,
471.Xr X509_REVOKED_new 3 ,
472.Xr X509V3_EXT_print 3 ,
473.Xr X509V3_extensions_print 3
474.Sh HISTORY
475.Fn X509V3_EXT_d2i
476first appeared in OpenSSL 0.9.2b.
477.Fn X509V3_EXT_i2d
478first appeared in OpenSSL 0.9.3.
479Both functions have been available since
480.Ox 2.6 .
481.Pp
482.Fn X509V3_get_d2i ,
483.Fn X509_get_ext_d2i ,
484.Fn X509_CRL_get_ext_d2i ,
485and
486.Fn X509_REVOKED_get_ext_d2i
487first appeared in OpenSSL 0.9.5 and have been available since
488.Ox 2.7 .
489.Pp
490.Fn X509V3_add1_i2d ,
491.Fn X509_add1_ext_i2d ,
492.Fn X509_CRL_add1_ext_i2d ,
493and
494.Fn X509_REVOKED_add1_ext_i2d
495first appeared in OpenSSL 0.9.7 and have been available since
496.Ox 3.2 .
497.Pp
498.Fn X509_get0_extensions ,
499.Fn X509_CRL_get0_extensions ,
500and
501.Fn X509_REVOKED_get0_extensions
502first appeared in OpenSSL 1.1.0 and have been available since
503.Ox 6.3 .
504.Pp
505.Fn X509_get0_uids
506first appeared in OpenSSL 1.1.0 and has been available since
507.Ox 7.3 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-07 09:28:05 +0000