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