1.\" $OpenBSD: X509_EXTENSION_set_object.3,v 1.19 2024/12/28 11:04:09 schwarze Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2016, 2021, 2024 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: December 28 2024 $ 69.Dt X509_EXTENSION_SET_OBJECT 3 70.Os 71.Sh NAME 72.Nm X509_EXTENSION_new , 73.Nm X509_EXTENSION_dup , 74.Nm X509_EXTENSION_free , 75.Nm X509_EXTENSION_create_by_NID , 76.Nm X509_EXTENSION_create_by_OBJ , 77.Nm X509_EXTENSION_set_object , 78.Nm X509_EXTENSION_set_critical , 79.Nm X509_EXTENSION_set_data , 80.Nm X509_EXTENSION_get_object , 81.Nm X509_EXTENSION_get_critical , 82.Nm X509_EXTENSION_get_data , 83.Nm X509_supported_extension 84.\" In the next line, the capital "E" is not a typo. 85.\" The ASN.1 structure is called "Extension", not "extension". 86.Nd create, change, and inspect X.509 Extension objects 87.Sh SYNOPSIS 88.In openssl/x509.h 89.Ft X509_EXTENSION * 90.Fn X509_EXTENSION_new void 91.Ft X509_EXTENSION * 92.Fn X509_EXTENSION_dup "X509_EXTENSION *ex" 93.Ft void 94.Fn X509_EXTENSION_free "X509_EXTENSION *ex" 95.Ft X509_EXTENSION * 96.Fo X509_EXTENSION_create_by_NID 97.Fa "X509_EXTENSION **ex" 98.Fa "int nid" 99.Fa "int crit" 100.Fa "ASN1_OCTET_STRING *data" 101.Fc 102.Ft X509_EXTENSION * 103.Fo X509_EXTENSION_create_by_OBJ 104.Fa "X509_EXTENSION **ex" 105.Fa "const ASN1_OBJECT *obj" 106.Fa "int crit" 107.Fa "ASN1_OCTET_STRING *data" 108.Fc 109.Ft int 110.Fo X509_EXTENSION_set_object 111.Fa "X509_EXTENSION *ex" 112.Fa "const ASN1_OBJECT *obj" 113.Fc 114.Ft int 115.Fo X509_EXTENSION_set_critical 116.Fa "X509_EXTENSION *ex" 117.Fa "int crit" 118.Fc 119.Ft int 120.Fo X509_EXTENSION_set_data 121.Fa "X509_EXTENSION *ex" 122.Fa "ASN1_OCTET_STRING *data" 123.Fc 124.Ft ASN1_OBJECT * 125.Fo X509_EXTENSION_get_object 126.Fa "X509_EXTENSION *ex" 127.Fc 128.Ft int 129.Fo X509_EXTENSION_get_critical 130.Fa "const X509_EXTENSION *ex" 131.Fc 132.Ft ASN1_OCTET_STRING * 133.Fo X509_EXTENSION_get_data 134.Fa "X509_EXTENSION *ex" 135.Fc 136.Ft int 137.Fo X509_supported_extension 138.Fa "X509_EXTENSION *ex" 139.Fc 140.Sh DESCRIPTION 141.Fn X509_EXTENSION_new 142allocates and initializes an empty 143.Vt X509_EXTENSION 144object, representing an ASN.1 145.Vt Extension 146structure defined in RFC 5280 section 4.1. 147It is a wrapper object around specific extension objects of different 148types and stores an extension type identifier and a criticality 149flag in addition to the DER-encoded form of the wrapped object. 150.Vt X509_EXTENSION 151objects can be used for X.509 v3 certificates inside 152.Vt X509_CINF 153objects and for X.509 v2 certificate revocation lists inside 154.Vt X509_CRL_INFO 155and 156.Vt X509_REVOKED 157objects. 158.Pp 159.Fn X509_EXTENSION_dup 160creates a deep copy of 161.Fa ex 162using 163.Xr ASN1_item_dup 3 . 164.Pp 165.Fn X509_EXTENSION_free 166frees 167.Fa ex 168and all objects it is using. 169.Pp 170.Fn X509_EXTENSION_create_by_NID 171creates an extension of type 172.Fa nid 173and criticality 174.Fa crit 175using data 176.Fa data . 177The created extension is returned and written to 178.Pf * Fa ex 179reusing or allocating a new extension if necessary, so 180.Pf * Fa ex 181should either be 182.Dv NULL 183or a valid 184.Vt X509_EXTENSION 185structure. 186It must not be an uninitialised pointer. 187.Pp 188.Fn X509_EXTENSION_create_by_OBJ 189is identical to 190.Fn X509_EXTENSION_create_by_NID 191except that it creates an extension using 192.Fa obj 193instead of a NID. 194.Pp 195.Fn X509_EXTENSION_set_object 196sets the extension type of 197.Fa ex 198to 199.Fa obj . 200The 201.Fa obj 202pointer is duplicated internally so 203.Fa obj 204should be freed up after use. 205.Pp 206.Fn X509_EXTENSION_set_critical 207sets the criticality of 208.Fa ex 209to 210.Fa crit . 211If 212.Fa crit 213is zero, the extension in non-critical, otherwise it is critical. 214.Pp 215.Fn X509_EXTENSION_set_data 216sets the data in extension 217.Fa ex 218to 219.Fa data . 220The 221.Fa data 222pointer is duplicated internally. 223.Pp 224.Fn X509_EXTENSION_get_object 225returns the extension type of 226.Fa ex 227as an 228.Vt ASN1_OBJECT 229pointer. 230The returned pointer is an internal value which must not be freed up. 231.Pp 232.Fn X509_EXTENSION_get_critical 233tests whether 234.Fa ex 235is critical. 236.Pp 237.Fn X509_EXTENSION_get_data 238returns the data of extension 239.Fa ex . 240The returned pointer is an internal value which must not be freed up. 241.Pp 242.Fn X509_supported_extension 243checks whether 244.Fa ex 245is of a type supported by the verifier. 246The list of supported extension types is hardcoded into the library. 247If an extension is critical but unsupported, 248the certificate will normally be rejected. 249.Pp 250These functions manipulate the contents of an extension directly. 251Most applications will want to parse or encode and add an extension: 252they should use the extension encode and decode functions instead 253such as 254.Xr X509_add1_ext_i2d 3 255and 256.Xr X509_get_ext_d2i 3 . 257.Pp 258The 259.Fa data 260associated with an extension is the extension encoding in an 261.Vt ASN1_OCTET_STRING 262structure. 263.Sh RETURN VALUES 264.Fn X509_EXTENSION_new , 265.Fn X509_EXTENSION_dup , 266.Fn X509_EXTENSION_create_by_NID , 267and 268.Fn X509_EXTENSION_create_by_OBJ 269return an 270.Vt X509_EXTENSION 271pointer or 272.Dv NULL 273if an error occurs. 274.Pp 275.Fn X509_EXTENSION_set_object , 276.Fn X509_EXTENSION_set_critical , 277and 278.Fn X509_EXTENSION_set_data 279return 1 for success or 0 for failure. 280.Pp 281.Fn X509_EXTENSION_get_object 282returns an 283.Vt ASN1_OBJECT 284pointer. 285.Pp 286.Fn X509_EXTENSION_get_critical 287returns 0 for non-critical or 1 for critical. 288.Pp 289.Fn X509_EXTENSION_get_data 290returns an 291.Vt ASN1_OCTET_STRING 292pointer. 293.Pp 294.Fn X509_supported_extension 295returns 1 if the type of 296.Fa ex 297is supported by the verifier or 0 otherwise. 298.Sh SEE ALSO 299.Xr ACCESS_DESCRIPTION_new 3 , 300.Xr AUTHORITY_KEYID_new 3 , 301.Xr BASIC_CONSTRAINTS_new 3 , 302.Xr d2i_X509_EXTENSION 3 , 303.Xr DIST_POINT_new 3 , 304.Xr ESS_SIGNING_CERT_new 3 , 305.Xr EXTENDED_KEY_USAGE_new 3 , 306.Xr GENERAL_NAME_new 3 , 307.Xr NAME_CONSTRAINTS_new 3 , 308.Xr OCSP_CRLID_new 3 , 309.Xr OCSP_SERVICELOC_new 3 , 310.Xr PKEY_USAGE_PERIOD_new 3 , 311.Xr POLICYINFO_new 3 , 312.Xr TS_REQ_new 3 , 313.Xr X509_check_ca 3 , 314.Xr X509_check_host 3 , 315.Xr X509_check_issued 3 , 316.Xr X509_get_extension_flags 3 , 317.Xr X509_REQ_add_extensions 3 , 318.Xr X509V3_EXT_get_nid 3 , 319.Xr X509V3_EXT_print 3 , 320.Xr X509V3_extensions_print 3 , 321.Xr X509V3_get_d2i 3 , 322.Xr X509v3_get_ext_by_NID 3 323.Sh STANDARDS 324RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 325Certificate Revocation List (CRL) Profile 326.Sh HISTORY 327.Fn X509_EXTENSION_new 328and 329.Fn X509_EXTENSION_free 330first appeared in SSLeay 0.6.2, 331.Fn X509_EXTENSION_dup 332in SSLeay 0.6.5, and 333.Fn X509_EXTENSION_create_by_NID , 334.Fn X509_EXTENSION_create_by_OBJ , 335.Fn X509_EXTENSION_set_object , 336.Fn X509_EXTENSION_set_critical , 337.Fn X509_EXTENSION_set_data , 338.Fn X509_EXTENSION_get_object , 339.Fn X509_EXTENSION_get_critical , 340and 341.Fn X509_EXTENSION_get_data 342in SSLeay 0.8.0. 343These functions have been available since 344.Ox 2.4 . 345.Pp 346.Fn X509_supported_extension 347first appeared in OpenSSL 0.9.7 and has been available since 348.Ox 3.2 . 349