1.\" $OpenBSD: X509_NAME_ENTRY_get_object.3,v 1.14 2021/07/02 16:13:56 schwarze Exp $ 2.\" full merge up to: OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400 3.\" selective merge up to: OpenSSL ca34e08d Dec 12 07:38:07 2018 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2016, 2018, 2019, 2021 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 23.\" Copyright (c) 2002, 2005, 2006, 2017 The OpenSSL Project. 24.\" 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: July 2 2021 $ 71.Dt X509_NAME_ENTRY_GET_OBJECT 3 72.Os 73.Sh NAME 74.Nm X509_NAME_ENTRY_new , 75.Nm X509_NAME_ENTRY_free , 76.Nm X509_NAME_ENTRY_get_object , 77.Nm X509_NAME_ENTRY_get_data , 78.Nm X509_NAME_ENTRY_set , 79.Nm X509_NAME_ENTRY_set_object , 80.Nm X509_NAME_ENTRY_set_data , 81.Nm X509_NAME_ENTRY_create_by_txt , 82.Nm X509_NAME_ENTRY_create_by_NID , 83.Nm X509_NAME_ENTRY_create_by_OBJ 84.\" In the following line, "X.501" is not a typo. 85.\" This object defined in X.501, not in X.509. 86.Nd X.501 relative distinguished name 87.Sh SYNOPSIS 88.In openssl/x509.h 89.Ft X509_NAME_ENTRY * 90.Fn X509_NAME_ENTRY_new void 91.Ft void 92.Fo X509_NAME_ENTRY_free 93.Fa "X509_NAME_ENTRY* ne" 94.Fc 95.Ft ASN1_OBJECT * 96.Fo X509_NAME_ENTRY_get_object 97.Fa "const X509_NAME_ENTRY *ne" 98.Fc 99.Ft ASN1_STRING * 100.Fo X509_NAME_ENTRY_get_data 101.Fa "const X509_NAME_ENTRY *ne" 102.Fc 103.Ft int 104.Fo X509_NAME_ENTRY_set 105.Fa "const X509_NAME_ENTRY *ne" 106.Fc 107.Ft int 108.Fo X509_NAME_ENTRY_set_object 109.Fa "X509_NAME_ENTRY *ne" 110.Fa "const ASN1_OBJECT *obj" 111.Fc 112.Ft int 113.Fo X509_NAME_ENTRY_set_data 114.Fa "X509_NAME_ENTRY *ne" 115.Fa "int type" 116.Fa "const unsigned char *bytes" 117.Fa "int len" 118.Fc 119.Ft X509_NAME_ENTRY * 120.Fo X509_NAME_ENTRY_create_by_txt 121.Fa "X509_NAME_ENTRY **ne" 122.Fa "const char *field" 123.Fa "int type" 124.Fa "const unsigned char *bytes" 125.Fa "int len" 126.Fc 127.Ft X509_NAME_ENTRY * 128.Fo X509_NAME_ENTRY_create_by_NID 129.Fa "X509_NAME_ENTRY **ne" 130.Fa "int nid" 131.Fa "int type" 132.Fa "const unsigned char *bytes" 133.Fa "int len" 134.Fc 135.Ft X509_NAME_ENTRY * 136.Fo X509_NAME_ENTRY_create_by_OBJ 137.Fa "X509_NAME_ENTRY **ne" 138.Fa "const ASN1_OBJECT *obj" 139.Fa "int type" 140.Fa "const unsigned char *bytes" 141.Fa "int len" 142.Fc 143.Sh DESCRIPTION 144An X.501 145.Vt RelativeDistinguishedName 146is an ordered set of field type and value pairs. 147It is the building block for constructing X.501 148.Vt Name 149objects. 150The 151.Vt X509_NAME_ENTRY 152object stores one such pair, containing one field type and one value. 153.Pp 154.Vt X509_NAME_ENTRY 155objects are intended for use by the 156.Vt X509_NAME 157objects documented in 158.Xr X509_NAME_new 3 . 159Since part of the information about how several 160.Vt X509_NAME_ENTRY 161objects combine to form an X.501 162.Vt Name 163is stored in the individual 164.Vt X509_NAME_ENTRY 165objects rather than in the 166.Vt X509_NAME 167object, any given 168.Vt X509_NAME_ENTRY 169object can only be used by one 170.Vt X509_NAME 171object at a time. 172.Pp 173.Fn X509_NAME_ENTRY_new 174allocates and initializes an empty 175.Vt X509_NAME_ENTRY 176object, representing an ASN.1 177.Vt RelativeDistinguishedName 178structure defined in RFC 5280 section 4.1.2.4, but containing not more 179than one type-value-pair. 180.Pp 181.Fn X509_NAME_ENTRY_free 182frees 183.Fa ne 184and the type and value contained in it. 185.Pp 186.Fn X509_NAME_ENTRY_get_object 187retrieves the field type of 188.Fa ne 189in an 190.Vt ASN1_OBJECT 191structure. 192.Fn X509_NAME_ENTRY_get_data 193retrieves the field value of 194.Fa ne 195in an 196.Vt ASN1_STRING 197structure. 198These two functions can be used to examine an 199.Vt X509_NAME_ENTRY 200object as returned by 201.Xr X509_NAME_get_entry 3 . 202.Pp 203.Fn X509_NAME_ENTRY_set 204retrieves the index of the X.501 205.Vt RelativeDistinguishedName Pq RDN 206that 207.Fa ne 208is part of in the X.501 209.Vt Name 210object using it. 211The first RDN has index 0. 212If an RDN consists of more than one 213.Vt X509_NAME_ENTRY 214object, they all share the same index. 215In practice, RDNs containing more than one type-value-pair are rarely 216used, so if an 217.Va X509_NAME *name 218object uses 219.Fa ne , 220then 221.Fn X509_NAME_ENTRY_set ne 222usually agrees with 223.Fn sk_X509_NAME_ENTRY_find name->entries ne , 224but when multi-pair RDNs are used, it may be smaller. 225.Pp 226.Fn X509_NAME_ENTRY_set_object 227sets the field type of 228.Fa ne 229to 230.Fa obj . 231.Pp 232.Fn X509_NAME_ENTRY_set_data 233sets the field value of 234.Fa ne 235to string type 236.Fa type 237and the value determined by 238.Fa bytes 239and 240.Fa len . 241.Pp 242.Fn X509_NAME_ENTRY_create_by_txt , 243.Fn X509_NAME_ENTRY_create_by_NID , 244and 245.Fn X509_NAME_ENTRY_create_by_OBJ 246create and return an 247.Vt X509_NAME_ENTRY 248structure. 249.Pp 250Except for 251.Fn X509_NAME_ENTRY_get_object 252and 253.Fn X509_NAME_ENTRY_get_data , 254these functions are rarely used because 255.Vt X509_NAME_ENTRY 256structures are almost always part of 257.Vt X509_NAME 258structures and the functions described in 259.Xr X509_NAME_add_entry_by_txt 3 260are typically used to create and add new entries in a single operation. 261.Pp 262The arguments of these functions support similar options to the 263similarly named ones described in 264.Xr X509_NAME_add_entry_by_txt 3 . 265So for example 266.Fa type 267can be set to 268.Dv MBSTRING_ASC , 269but in the case of 270.Fn X509_NAME_ENTRY_set_data 271the field type must be set first so the relevant field information 272can be looked up internally. 273.Sh RETURN VALUES 274The 275.Fn X509_NAME_ENTRY_new 276function returns a valid 277.Vt X509_NAME_ENTRY 278structure if successful; otherwise 279.Dv NULL 280is returned and an error code can be retrieved with 281.Xr ERR_get_error 3 . 282.Pp 283.Fn X509_NAME_ENTRY_get_object 284returns a valid 285.Vt ASN1_OBJECT 286structure if it is set or 287.Dv NULL 288if an error occurred. 289.Pp 290.Fn X509_NAME_ENTRY_get_data 291returns a valid 292.Vt ASN1_STRING 293structure if it is set or 294.Dv NULL 295if an error occurred. 296.Pp 297.Fn X509_NAME_ENTRY_set 298returns the zero-based index of the RDN 299.Fa ne 300is used in, or 0 if 301.Fa ne 302is not yet used by any 303.Vt X509_NAME 304object. 305.Pp 306The 307.Fn X509_NAME_ENTRY_set_object 308function returns 1 if successful; 309otherwise 0 is returned and an error code can be retrieved with 310.Xr ERR_get_error 3 . 311.Pp 312.Fn X509_NAME_ENTRY_set_data 313returns 1 on success or 0 on error. 314In some cases of failure, the reason can be determined with 315.Xr ERR_get_error 3 . 316.Pp 317.Fn X509_NAME_ENTRY_create_by_txt , 318.Fn X509_NAME_ENTRY_create_by_NID , 319and 320.Fn X509_NAME_ENTRY_create_by_OBJ 321return a valid 322.Vt X509_NAME_ENTRY 323structure on success or 324.Dv NULL 325if an error occurred. 326In some cases of failure, the reason can be determined with 327.Xr ERR_get_error 3 . 328.Sh SEE ALSO 329.Xr OBJ_nid2obj 3 , 330.Xr X509_NAME_add_entry 3 , 331.Xr X509_NAME_get_entry 3 , 332.Xr X509_NAME_new 3 333.Sh STANDARDS 334RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 335Certificate Revocation List (CRL) Profile 336.Pp 337ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: Information 338Technology Open Systems Interconnection The Directory: Models, 339section 9.3: Relative distinguished name 340.Sh HISTORY 341.Fn X509_NAME_ENTRY_new 342and 343.Fn X509_NAME_ENTRY_free 344first appeared in SSLeay 0.5.1. 345.Fn X509_NAME_ENTRY_get_object , 346.Fn X509_NAME_ENTRY_get_data , 347.Fn X509_NAME_ENTRY_set_object , 348.Fn X509_NAME_ENTRY_set_data , 349.Fn X509_NAME_ENTRY_create_by_NID , 350and 351.Fn X509_NAME_ENTRY_create_by_OBJ 352first appeared in SSLeay 0.8.0. 353These functions have been available since 354.Ox 2.4 . 355.Pp 356.Fn X509_NAME_ENTRY_create_by_txt 357first appeared in OpenSSL 0.9.5 and has been available since 358.Ox 2.7 . 359.Pp 360.Fn X509_NAME_ENTRY_set 361first appeared in OpenSSL 1.1.0 and has been available since 362.Ox 6.3 . 363.Sh CAVEATS 364Despite its name, 365.Fn X509_NAME_ENTRY_set 366does not set anything. 367Something like 368.Dq X509_NAME_ENTRY_get_set 369would have been a better name. 370