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