summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/X509V3_EXT_print.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/X509V3_EXT_print.3195
1 files changed, 0 insertions, 195 deletions
diff --git a/src/lib/libcrypto/man/X509V3_EXT_print.3 b/src/lib/libcrypto/man/X509V3_EXT_print.3
deleted file mode 100644
index edb97d3a36..0000000000
--- a/src/lib/libcrypto/man/X509V3_EXT_print.3
+++ /dev/null
@@ -1,195 +0,0 @@
1.\" $OpenBSD: X509V3_EXT_print.3,v 1.3 2024/12/28 10:19:45 schwarze Exp $
2.\"
3.\" Copyright (c) 2021, 2024 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: December 28 2024 $
18.Dt X509V3_EXT_PRINT 3
19.Os
20.Sh NAME
21.Nm X509V3_EXT_print ,
22.Nm X509V3_EXT_print_fp
23.Nd pretty-print an X.509 extension
24.Sh SYNOPSIS
25.In openssl/x509v3.h
26.Ft int
27.Fo X509V3_EXT_print
28.Fa "BIO *bio"
29.Fa "X509_EXTENSION *ext"
30.Fa "unsigned long flags"
31.Fa "int indent"
32.Fc
33.Ft int
34.Fo X509V3_EXT_print_fp
35.Fa "FILE *file"
36.Fa "X509_EXTENSION *ext"
37.Fa "int flags"
38.Fa "int indent"
39.Fc
40.Sh DESCRIPTION
41.Fn X509V3_EXT_print
42and
43.Fn X509V3_EXT_print_fp
44decode
45.Fa ext
46and print the data contained in it to the
47.Fa bio
48or
49.Fa file ,
50respectively, in a human-readable format with a left margin of
51.Fa indent
52space characters.
53The details of both the decoding and the printing depend on the type of
54.Fa ext .
55.Pp
56For most extension types, the decoding is done in the same way
57as it would be done by the appropriate public API function, for example:
58.Pp
59.Bl -tag -width NID_authority_key_identifier -compact
60.It Sy extension type
61.Sy decoding function
62.It Dv NID_authority_key_identifier
63.Xr d2i_AUTHORITY_KEYID 3
64.It Dv NID_certificate_policies
65.Xr d2i_CERTIFICATEPOLICIES 3
66.It Dv NID_crl_number
67.Xr d2i_ASN1_INTEGER 3
68.It Dv NID_crl_reason
69.Xr d2i_ASN1_ENUMERATED 3
70.It Dv NID_hold_instruction_code
71.Xr d2i_ASN1_OBJECT 3
72.It Dv NID_id_pkix_OCSP_CrlID
73.Xr d2i_OCSP_CRLID 3
74.It Dv NID_id_pkix_OCSP_noCheck
75.Xr d2i_ASN1_NULL 3
76.It Dv NID_id_pkix_OCSP_Nonce
77non-public function built into the library
78.It Dv NID_invalidity_date
79.Xr d2i_ASN1_GENERALIZEDTIME 3
80.It Dv NID_key_usage
81.Xr d2i_ASN1_BIT_STRING 3
82.It Dv NID_subject_alt_name
83.Xr d2i_GENERAL_NAMES 3
84.It Dv NID_subject_key_identifier
85.Xr d2i_ASN1_OCTET_STRING 3
86.El
87.Pp
88For some types, the printing is performed
89by a dedicated non-public function built into the library.
90For some other types, the printing function is a public API function,
91for example:
92.Pp
93.Bl -tag -width NID_id_pkix_OCSP_archiveCutoff -compact
94.It Sy extension type
95.Sy printing function
96.It Dv NID_crl_number
97.Xr i2s_ASN1_INTEGER 3
98.It Dv NID_crl_reason
99.Xr i2s_ASN1_ENUMERATED_TABLE 3
100.It Dv NID_delta_crl
101.Xr i2s_ASN1_INTEGER 3
102.It Dv NID_hold_instruction_code
103.Xr i2a_ASN1_OBJECT 3
104.It Dv NID_id_pkix_OCSP_archiveCutoff
105.Xr ASN1_GENERALIZEDTIME_print 3
106.It Dv NID_id_pkix_OCSP_Nonce
107.Xr i2a_ASN1_STRING 3
108.It Dv NID_inhibit_any_policy
109.Xr i2s_ASN1_INTEGER 3
110.It Dv NID_invalidity_date
111.Xr ASN1_GENERALIZEDTIME_print 3
112.It Dv NID_key_usage
113.Xr i2v_ASN1_BIT_STRING 3
114.It Dv NID_subject_key_identifier
115.Xr i2s_ASN1_OCTET_STRING 3
116.El
117.Pp
118Some of the public printing functions are not documented yet.
119.Pp
120If
121.Fa ext
122is of an unknown extension type or if decoding fails
123while using the decoding function for the relevant type,
124the action taken depends on the
125.Fa flags
126argument:
127.Bl -bullet
128.It
129If the bit
130.Dv X509V3_EXT_PARSE_UNKNOWN
131is set,
132.Xr ASN1_parse_dump 3
133is called on the BER-encoded data of the extension, passing \-1 for the
134.Fa dump
135argument.
136Thus, some information about the encoding of the extension gets printed
137and some about its decoded content, falling back to
138.Xr BIO_dump_indent 3
139for the decoded content unless a dedicated printing method is known
140for the respective data type(s).
141Note that even if an extension type is unknown, the data type used
142by the unknown extension, or, if that data type is constructed, of
143the values contained in it, may still be known, which may allow
144printing the content of even an unknown extension in a structured
145or partially structured form.
146.It
147If the bit
148.Dv X509V3_EXT_DUMP_UNKNOWN
149is set,
150.Xr BIO_dump_indent 3
151is called on the BER-encoded data of the extension without decoding
152it first, which is usually less readable than the above but poses
153a smaller risk of omitting or misrepresenting parts of the information.
154.It
155If the bit
156.Dv X509V3_EXT_ERROR_UNKNOWN
157is set, only the fixed string
158.Qq "<Not Supported>"
159is printed for an unknown type or only the fixed string
160.Qq "<Parse Error>"
161if the parsing functions fails,
162but printing is considered as successful anyway.
163.It
164If more than one of these three bits is set, or if a bit in
165.Dv X509V3_EXT_UNKNOWN_MASK
166is set that is not listed above, nothing is printed, but printing
167is considered as successful anyway.
168.It
169If none of the bits in
170.Dv X509V3_EXT_UNKNOWN_MASK
171are set, nothing is printed and printing is considered as failed.
172.El
173.Sh RETURN VALUES
174.Fn X509V3_EXT_print
175and
176.Fn X509V3_EXT_print_fp
177return 0 if failure was both detected and considered relevant.
178Otherwise, 1 is returned, and in general the user cannot tell whether
179failure simply went undetected, whether the function detected failure
180but regarded it as irrelevant, or whether printing did indeed
181succeed.
182.Sh SEE ALSO
183.Xr BIO_new 3 ,
184.Xr X509_EXTENSION_new 3 ,
185.Xr X509_get0_extensions 3 ,
186.Xr X509_get_ext 3 ,
187.Xr X509V3_extensions_print 3
188.Sh HISTORY
189These functions first appeared in OpenSSL 0.9.2 and have been available since
190.Ox 2.6 .
191.Sh BUGS
192These functions lack error handling throughout.
193When a write operation fails, they will usually ignore the fact that
194information was omitted from the output and report success to the
195caller anyway.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-07 08:58:01 +0000