]>
Commit | Line | Data |
---|---|---|
047dd81e DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c | 5 | X509_get0_extensions, X509_CRL_get0_extensions, X509_REVOKED_get0_extensions, |
047dd81e DSH |
6 | X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d, |
7 | X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i, | |
8 | X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i, | |
9 | X509_REVOKED_add1_ext_i2d - X509 extension decode and encode functions | |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/x509v3.h> | |
14 | ||
84de54b9 | 15 | void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit, |
047dd81e DSH |
16 | int *idx); |
17 | int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value, | |
18 | int crit, unsigned long flags); | |
19 | ||
20 | void *X509V3_EXT_d2i(X509_EXTENSION *ext); | |
21 | X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext); | |
22 | ||
84de54b9 | 23 | void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx); |
047dd81e DSH |
24 | int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit, |
25 | unsigned long flags); | |
26 | ||
84de54b9 | 27 | void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx); |
047dd81e DSH |
28 | int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit, |
29 | unsigned long flags); | |
30 | ||
84de54b9 | 31 | void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx); |
047dd81e DSH |
32 | int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit, |
33 | unsigned long flags); | |
34 | ||
8900f3e3 | 35 | const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x); |
5e6089f0 | 36 | const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl); |
604f6eff | 37 | const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r); |
ff7fbfd5 | 38 | |
047dd81e DSH |
39 | =head1 DESCRIPTION |
40 | ||
41 | X509V3_get_ext_d2i() looks for an extension with OID B<nid> in the extensions | |
42 | B<x> and, if found, decodes it. If B<idx> is B<NULL> then only one | |
43 | occurrence of an extension is permissible otherwise the first extension after | |
44 | index B<*idx> is returned and B<*idx> updated to the location of the extension. | |
45 | If B<crit> is not B<NULL> then B<*crit> is set to a status value: -2 if the | |
46 | extension occurs multiple times (this is only returned if B<idx> is B<NULL>), | |
47 | -1 if the extension could not be found, 0 if the extension is found and is | |
48 | not critical and 1 if critical. A pointer to an extension specific structure | |
49 | or B<NULL> is returned. | |
50 | ||
51 | X509V3_add1_i2d() adds extension B<value> to STACK B<*x> (allocating a new | |
52 | STACK if necessary) using OID B<nid> and criticality B<crit> according | |
53 | to B<flags>. | |
54 | ||
55 | X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension | |
56 | B<ext> and returns a pointer to an extension specific structure or B<NULL> | |
57 | if the extension could not be decoded (invalid syntax or not supported). | |
58 | ||
59 | X509V3_EXT_i2d() encodes the extension specific structure B<ext> | |
60 | with OID B<ext_nid> and criticality B<crit>. | |
61 | ||
62 | X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of | |
63 | certificate B<x>, they are otherwise identical to X509V3_get_d2i() and | |
64 | X509V3_add_i2d(). | |
65 | ||
66 | X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions | |
67 | of CRL B<crl>, they are otherwise identical to X509V3_get_d2i() and | |
68 | X509V3_add_i2d(). | |
69 | ||
70 | X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the | |
71 | extensions of B<X509_REVOKED> structure B<r> (i.e for CRL entry extensions), | |
72 | they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d(). | |
73 | ||
ff7fbfd5 DSH |
74 | X509_get0_extensions(), X509_CRL_get0_extensions() and |
75 | X509_REVOKED_get0_extensions() return a stack of all the extensions | |
76 | of a certificate a CRL or a CRL entry respectively. | |
77 | ||
047dd81e DSH |
78 | =head1 NOTES |
79 | ||
80 | In almost all cases an extension can occur at most once and multiple | |
0d4fb843 | 81 | occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>. |
047dd81e DSH |
82 | |
83 | The B<flags> parameter may be one of the following values. | |
84 | ||
85 | B<X509V3_ADD_DEFAULT> appends a new extension only if the extension does | |
86 | not already exist. An error is returned if the extension does already | |
87 | exist. | |
88 | ||
89 | B<X509V3_ADD_APPEND> appends a new extension, ignoring whether the extension | |
90 | already exists. | |
91 | ||
9d22666e | 92 | B<X509V3_ADD_REPLACE> replaces an extension if it exists otherwise appends |
047dd81e DSH |
93 | a new extension. |
94 | ||
95 | B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension if it exists | |
96 | otherwise returns an error. | |
97 | ||
98 | B<X509V3_ADD_KEEP_EXISTING> appends a new extension only if the extension does | |
99 | not already exist. An error B<is not> returned if the extension does already | |
100 | exist. | |
101 | ||
9d22666e | 102 | B<X509V3_ADD_DELETE> extension B<nid> is deleted: no new extension is added. |
047dd81e DSH |
103 | |
104 | If B<X509V3_ADD_SILENT> is ored with B<flags>: any error returned will not | |
105 | be added to the error queue. | |
106 | ||
107 | The function X509V3_get_d2i() will return B<NULL> if the extension is not | |
108 | found, occurs multiple times or cannot be decoded. It is possible to | |
109 | determine the precise reason by checking the value of B<*crit>. | |
110 | ||
111 | =head1 SUPPORTED EXTENSIONS | |
112 | ||
113 | The following sections contain a list of all supported extensions | |
114 | including their name and NID. | |
115 | ||
05ea606a | 116 | =head2 PKIX Certificate Extensions |
047dd81e DSH |
117 | |
118 | The following certificate extensions are defined in PKIX standards such as | |
119 | RFC5280. | |
120 | ||
121 | Basic Constraints NID_basic_constraints | |
122 | Key Usage NID_key_usage | |
123 | Extended Key Usage NID_ext_key_usage | |
124 | ||
125 | Subject Key Identifier NID_subject_key_identifier | |
126 | Authority Key Identifier NID_authority_key_identifier | |
127 | ||
128 | Private Key Usage Period NID_private_key_usage_period | |
129 | ||
130 | Subject Alternative Name NID_subject_alt_name | |
131 | Issuer Alternative Name NID_issuer_alt_name | |
132 | ||
133 | Authority Information Access NID_info_access | |
134 | Subject Information Access NID_sinfo_access | |
135 | ||
136 | Name Constraints NID_name_constraints | |
137 | ||
138 | Certificate Policies NID_certificate_policies | |
139 | Policy Mappings NID_policy_mappings | |
140 | Policy Constraints NID_policy_constraints | |
141 | Inhibit Any Policy NID_inhibit_any_policy | |
142 | ||
ba67253d RS |
143 | TLS Feature NID_tlsfeature |
144 | ||
05ea606a | 145 | =head2 Netscape Certificate Extensions |
047dd81e DSH |
146 | |
147 | The following are (largely obsolete) Netscape certificate extensions. | |
148 | ||
149 | Netscape Cert Type NID_netscape_cert_type | |
150 | Netscape Base Url NID_netscape_base_url | |
151 | Netscape Revocation Url NID_netscape_revocation_url | |
152 | Netscape CA Revocation Url NID_netscape_ca_revocation_url | |
153 | Netscape Renewal Url NID_netscape_renewal_url | |
154 | Netscape CA Policy Url NID_netscape_ca_policy_url | |
155 | Netscape SSL Server Name NID_netscape_ssl_server_name | |
156 | Netscape Comment NID_netscape_comment | |
157 | ||
05ea606a | 158 | =head2 Miscellaneous Certificate Extensions |
047dd81e DSH |
159 | |
160 | Strong Extranet ID NID_sxnet | |
161 | Proxy Certificate Information NID_proxyCertInfo | |
162 | ||
05ea606a | 163 | =head2 PKIX CRL Extensions |
047dd81e DSH |
164 | |
165 | The following are CRL extensions from PKIX standards such as RFC5280. | |
166 | ||
167 | CRL Number NID_crl_number | |
168 | CRL Distribution Points NID_crl_distribution_points | |
169 | Delta CRL Indicator NID_delta_crl | |
170 | Freshest CRL NID_freshest_crl | |
171 | Invalidity Date NID_invalidity_date | |
b9b6a7e5 | 172 | Issuing Distribution Point NID_issuing_distribution_point |
047dd81e DSH |
173 | |
174 | The following are CRL entry extensions from PKIX standards such as RFC5280. | |
175 | ||
176 | CRL Reason Code NID_crl_reason | |
177 | Certificate Issuer NID_certificate_issuer | |
178 | ||
05ea606a | 179 | =head2 OCSP Extensions |
047dd81e DSH |
180 | |
181 | OCSP Nonce NID_id_pkix_OCSP_Nonce | |
182 | OCSP CRL ID NID_id_pkix_OCSP_CrlID | |
183 | Acceptable OCSP Responses NID_id_pkix_OCSP_acceptableResponses | |
184 | OCSP No Check NID_id_pkix_OCSP_noCheck | |
185 | OCSP Archive Cutoff NID_id_pkix_OCSP_archiveCutoff | |
186 | OCSP Service Locator NID_id_pkix_OCSP_serviceLocator | |
187 | Hold Instruction Code NID_hold_instruction_code | |
188 | ||
05ea606a | 189 | =head2 Certificate Transparency Extensions |
047dd81e DSH |
190 | |
191 | The following extensions are used by certificate transparency, RFC6962 | |
192 | ||
193 | CT Precertificate SCTs NID_ct_precert_scts | |
194 | CT Certificate SCTs NID_ct_cert_scts | |
195 | ||
196 | =head1 RETURN VALUES | |
197 | ||
198 | X509V3_EXT_d2i() and *X509V3_get_d2i() return a pointer to an extension | |
199 | specific structure of B<NULL> if an error occurs. | |
200 | ||
201 | X509V3_EXT_i2d() returns a pointer to an B<X509_EXTENSION> structure | |
202 | or B<NULL> if an error occurs. | |
203 | ||
204 | X509V3_add1_i2d() returns 1 if the operation is successful and 0 if it | |
205 | fails due to a non-fatal error (extension not found, already exists, | |
206 | cannot be encoded) or -1 due to a fatal error such as a memory allocation | |
207 | failure. | |
208 | ||
ff7fbfd5 | 209 | X509_get0_extensions(), X509_CRL_get0_extensions() and |
c952780c | 210 | X509_REVOKED_get0_extensions() return a stack of extensions. They return |
ff7fbfd5 DSH |
211 | NULL if no extensions are present. |
212 | ||
047dd81e DSH |
213 | =head1 SEE ALSO |
214 | ||
215 | L<d2i_X509(3)>, | |
7795475f | 216 | L<ERR_get_error(3)>, |
047dd81e DSH |
217 | L<X509_CRL_get0_by_serial(3)>, |
218 | L<X509_get0_signature(3)>, | |
219 | L<X509_get_ext_d2i(3)>, | |
220 | L<X509_get_extension_flags(3)>, | |
221 | L<X509_get_pubkey(3)>, | |
222 | L<X509_get_subject_name(3)>, | |
223 | L<X509_get_version(3)>, | |
224 | L<X509_NAME_add_entry_by_txt(3)>, | |
225 | L<X509_NAME_ENTRY_get_object(3)>, | |
226 | L<X509_NAME_get_index_by_NID(3)>, | |
227 | L<X509_NAME_print_ex(3)>, | |
228 | L<X509_new(3)>, | |
229 | L<X509_sign(3)>, | |
230 | L<X509_verify_cert(3)> | |
231 | ||
e2f92610 RS |
232 | =head1 COPYRIGHT |
233 | ||
234 | Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. | |
235 | ||
4746f25a | 236 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
237 | this file except in compliance with the License. You can obtain a copy |
238 | in the file LICENSE in the source distribution or at | |
239 | L<https://www.openssl.org/source/license.html>. | |
240 | ||
241 | =cut |