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 . 508