1.\" $OpenBSD: X509_EXTENSION_set_object.3,v 1.15 2021/10/29 10:22:00 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 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: October 29 2021 $ 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.\" In the next line, the capital "E" is not a typo. 84.\" The ASN.1 structure is called "Extension", not "extension". 85.Nd create, change, and inspect X.509 Extension objects 86.Sh SYNOPSIS 87.In openssl/x509.h 88.Ft X509_EXTENSION * 89.Fn X509_EXTENSION_new void 90.Ft X509_EXTENSION * 91.Fn X509_EXTENSION_dup "X509_EXTENSION *ex" 92.Ft void 93.Fn X509_EXTENSION_free "X509_EXTENSION *ex" 94.Ft X509_EXTENSION * 95.Fo X509_EXTENSION_create_by_NID 96.Fa "X509_EXTENSION **ex" 97.Fa "int nid" 98.Fa "int crit" 99.Fa "ASN1_OCTET_STRING *data" 100.Fc 101.Ft X509_EXTENSION * 102.Fo X509_EXTENSION_create_by_OBJ 103.Fa "X509_EXTENSION **ex" 104.Fa "const ASN1_OBJECT *obj" 105.Fa "int crit" 106.Fa "ASN1_OCTET_STRING *data" 107.Fc 108.Ft int 109.Fo X509_EXTENSION_set_object 110.Fa "X509_EXTENSION *ex" 111.Fa "const ASN1_OBJECT *obj" 112.Fc 113.Ft int 114.Fo X509_EXTENSION_set_critical 115.Fa "X509_EXTENSION *ex" 116.Fa "int crit" 117.Fc 118.Ft int 119.Fo X509_EXTENSION_set_data 120.Fa "X509_EXTENSION *ex" 121.Fa "ASN1_OCTET_STRING *data" 122.Fc 123.Ft ASN1_OBJECT * 124.Fo X509_EXTENSION_get_object 125.Fa "X509_EXTENSION *ex" 126.Fc 127.Ft int 128.Fo X509_EXTENSION_get_critical 129.Fa "const X509_EXTENSION *ex" 130.Fc 131.Ft ASN1_OCTET_STRING * 132.Fo X509_EXTENSION_get_data 133.Fa "X509_EXTENSION *ex" 134.Fc 135.Sh DESCRIPTION 136.Fn X509_EXTENSION_new 137allocates and initializes an empty 138.Vt X509_EXTENSION 139object, representing an ASN.1 140.Vt Extension 141structure defined in RFC 5280 section 4.1. 142It is a wrapper object around specific extension objects of different 143types and stores an extension type identifier and a criticality 144flag in addition to the DER-encoded form of the wrapped object. 145.Vt X509_EXTENSION 146objects can be used for X.509 v3 certificates inside 147.Vt X509_CINF 148objects and for X.509 v2 certificate revocation lists inside 149.Vt X509_CRL_INFO 150and 151.Vt X509_REVOKED 152objects. 153.Pp 154.Fn X509_EXTENSION_dup 155creates a deep copy of 156.Fa ex 157using 158.Xr ASN1_item_dup 3 . 159.Pp 160.Fn X509_EXTENSION_free 161frees 162.Fa ex 163and all objects it is using. 164.Pp 165.Fn X509_EXTENSION_create_by_NID 166creates an extension of type 167.Fa nid 168and criticality 169.Fa crit 170using data 171.Fa data . 172The created extension is returned and written to 173.Pf * Fa ex 174reusing or allocating a new extension if necessary, so 175.Pf * Fa ex 176should either be 177.Dv NULL 178or a valid 179.Vt X509_EXTENSION 180structure. 181It must not be an uninitialised pointer. 182.Pp 183.Fn X509_EXTENSION_create_by_OBJ 184is identical to 185.Fn X509_EXTENSION_create_by_NID 186except that it creates an extension using 187.Fa obj 188instead of a NID. 189.Pp 190.Fn X509_EXTENSION_set_object 191sets the extension type of 192.Fa ex 193to 194.Fa obj . 195The 196.Fa obj 197pointer is duplicated internally so 198.Fa obj 199should be freed up after use. 200.Pp 201.Fn X509_EXTENSION_set_critical 202sets the criticality of 203.Fa ex 204to 205.Fa crit . 206If 207.Fa crit 208is zero, the extension in non-critical, otherwise it is critical. 209.Pp 210.Fn X509_EXTENSION_set_data 211sets the data in extension 212.Fa ex 213to 214.Fa data . 215The 216.Fa data 217pointer is duplicated internally. 218.Pp 219.Fn X509_EXTENSION_get_object 220returns the extension type of 221.Fa ex 222as an 223.Vt ASN1_OBJECT 224pointer. 225The returned pointer is an internal value which must not be freed up. 226.Pp 227.Fn X509_EXTENSION_get_critical 228returns the criticality of extension 229.Fa ex 230it returns 1 for critical and 0 for non-critical. 231.Pp 232.Fn X509_EXTENSION_get_data 233returns the data of extension 234.Fa ex . 235The returned pointer is an internal value which must not be freed up. 236.Pp 237These functions manipulate the contents of an extension directly. 238Most applications will want to parse or encode and add an extension: 239they should use the extension encode and decode functions instead 240such as 241.Xr X509_add1_ext_i2d 3 242and 243.Xr X509_get_ext_d2i 3 . 244.Pp 245The 246.Fa data 247associated with an extension is the extension encoding in an 248.Vt ASN1_OCTET_STRING 249structure. 250.Sh RETURN VALUES 251.Fn X509_EXTENSION_new , 252.Fn X509_EXTENSION_dup , 253.Fn X509_EXTENSION_create_by_NID , 254and 255.Fn X509_EXTENSION_create_by_OBJ 256return an 257.Vt X509_EXTENSION 258pointer or 259.Dv NULL 260if an error occurs. 261.Pp 262.Fn X509_EXTENSION_set_object , 263.Fn X509_EXTENSION_set_critical , 264and 265.Fn X509_EXTENSION_set_data 266return 1 for success or 0 for failure. 267.Pp 268.Fn X509_EXTENSION_get_object 269returns an 270.Vt ASN1_OBJECT 271pointer. 272.Pp 273.Fn X509_EXTENSION_get_critical 274returns 0 for non-critical or 1 for critical. 275.Pp 276.Fn X509_EXTENSION_get_data 277returns an 278.Vt ASN1_OCTET_STRING 279pointer. 280.Sh SEE ALSO 281.Xr ACCESS_DESCRIPTION_new 3 , 282.Xr AUTHORITY_KEYID_new 3 , 283.Xr BASIC_CONSTRAINTS_new 3 , 284.Xr d2i_X509_EXTENSION 3 , 285.Xr DIST_POINT_new 3 , 286.Xr ESS_SIGNING_CERT_new 3 , 287.Xr EXTENDED_KEY_USAGE_new 3 , 288.Xr GENERAL_NAME_new 3 , 289.Xr NAME_CONSTRAINTS_new 3 , 290.Xr OCSP_CRLID_new 3 , 291.Xr OCSP_SERVICELOC_new 3 , 292.Xr PKEY_USAGE_PERIOD_new 3 , 293.Xr POLICYINFO_new 3 , 294.Xr PROXY_POLICY_new 3 , 295.Xr SXNET_new 3 , 296.Xr TS_REQ_new 3 , 297.Xr X509_check_ca 3 , 298.Xr X509_check_host 3 , 299.Xr X509_check_issued 3 , 300.Xr X509_get_extension_flags 3 , 301.Xr X509_REQ_add_extensions 3 , 302.Xr X509V3_EXT_print 3 , 303.Xr X509V3_extensions_print 3 , 304.Xr X509V3_get_d2i 3 , 305.Xr X509v3_get_ext_by_NID 3 306.Sh STANDARDS 307RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 308Certificate Revocation List (CRL) Profile 309.Sh HISTORY 310.Fn X509_EXTENSION_new 311and 312.Fn X509_EXTENSION_free 313first appeared in SSLeay 0.6.2, 314.Fn X509_EXTENSION_dup 315in SSLeay 0.6.5, and 316.Fn X509_EXTENSION_create_by_NID , 317.Fn X509_EXTENSION_create_by_OBJ , 318.Fn X509_EXTENSION_set_object , 319.Fn X509_EXTENSION_set_critical , 320.Fn X509_EXTENSION_set_data , 321.Fn X509_EXTENSION_get_object , 322.Fn X509_EXTENSION_get_critical , 323and 324.Fn X509_EXTENSION_get_data 325in SSLeay 0.8.0. 326These functions have been available since 327.Ox 2.4 . 328