1.\" $OpenBSD: X509_NAME_ENTRY_get_object.3,v 1.16 2021/12/10 16:58:20 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: December 10 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 the given string 236.Fa type 237and the value determined by 238.Fa bytes 239and 240.Fa len . 241If the 242.Fa type 243argument is positive and includes the 244.Fa MBSTRING_FLAG 245bit, 246.Xr ASN1_STRING_set_by_NID 3 247is used for setting the value, passing the 248.Fa type 249as the 250.Fa inform 251argument and using the 252.Fa nid 253corresponding to 254.Fa ne . 255Otherwise, if the 256.Fa type 257argument is 258.Dv V_ASN1_APP_CHOOSE , 259the type of 260.Fa ne 261is set to the return value of 262.Xr ASN1_PRINTABLE_type 3 . 263.Pp 264.Fn X509_NAME_ENTRY_create_by_txt , 265.Fn X509_NAME_ENTRY_create_by_NID , 266and 267.Fn X509_NAME_ENTRY_create_by_OBJ 268create and return an 269.Vt X509_NAME_ENTRY 270structure. 271.Pp 272Except for 273.Fn X509_NAME_ENTRY_get_object 274and 275.Fn X509_NAME_ENTRY_get_data , 276these functions are rarely used because 277.Vt X509_NAME_ENTRY 278structures are almost always part of 279.Vt X509_NAME 280structures and the functions described in 281.Xr X509_NAME_add_entry_by_txt 3 282are typically used to create and add new entries in a single operation. 283.Pp 284The arguments of these functions support similar options to the 285similarly named ones described in 286.Xr X509_NAME_add_entry_by_txt 3 . 287So for example 288.Fa type 289can be set to 290.Dv MBSTRING_ASC , 291but in the case of 292.Fn X509_NAME_ENTRY_set_data 293the field type must be set first so the relevant field information 294can be looked up internally. 295.Sh RETURN VALUES 296The 297.Fn X509_NAME_ENTRY_new 298function returns a valid 299.Vt X509_NAME_ENTRY 300structure if successful; otherwise 301.Dv NULL 302is returned and an error code can be retrieved with 303.Xr ERR_get_error 3 . 304.Pp 305.Fn X509_NAME_ENTRY_get_object 306returns a valid 307.Vt ASN1_OBJECT 308structure if it is set or 309.Dv NULL 310if an error occurred. 311.Pp 312.Fn X509_NAME_ENTRY_get_data 313returns a valid 314.Vt ASN1_STRING 315structure if it is set or 316.Dv NULL 317if an error occurred. 318.Pp 319.Fn X509_NAME_ENTRY_set 320returns the zero-based index of the RDN 321.Fa ne 322is used in, or 0 if 323.Fa ne 324is not yet used by any 325.Vt X509_NAME 326object. 327.Pp 328The 329.Fn X509_NAME_ENTRY_set_object 330function returns 1 if successful; 331otherwise 0 is returned and an error code can be retrieved with 332.Xr ERR_get_error 3 . 333.Pp 334.Fn X509_NAME_ENTRY_set_data 335returns 1 on success or 0 on error. 336In some cases of failure, the reason can be determined with 337.Xr ERR_get_error 3 . 338.Pp 339.Fn X509_NAME_ENTRY_create_by_txt , 340.Fn X509_NAME_ENTRY_create_by_NID , 341and 342.Fn X509_NAME_ENTRY_create_by_OBJ 343return a valid 344.Vt X509_NAME_ENTRY 345structure on success or 346.Dv NULL 347if an error occurred. 348In some cases of failure, the reason can be determined with 349.Xr ERR_get_error 3 . 350.Sh SEE ALSO 351.Xr OBJ_nid2obj 3 , 352.Xr X509_NAME_add_entry 3 , 353.Xr X509_NAME_get_entry 3 , 354.Xr X509_NAME_new 3 355.Sh STANDARDS 356RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 357Certificate Revocation List (CRL) Profile 358.Pp 359ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: Information 360Technology Open Systems Interconnection The Directory: Models, 361section 9.3: Relative distinguished name 362.Sh HISTORY 363.Fn X509_NAME_ENTRY_new 364and 365.Fn X509_NAME_ENTRY_free 366first appeared in SSLeay 0.5.1. 367.Fn X509_NAME_ENTRY_get_object , 368.Fn X509_NAME_ENTRY_get_data , 369.Fn X509_NAME_ENTRY_set_object , 370.Fn X509_NAME_ENTRY_set_data , 371.Fn X509_NAME_ENTRY_create_by_NID , 372and 373.Fn X509_NAME_ENTRY_create_by_OBJ 374first appeared in SSLeay 0.8.0. 375These functions have been available since 376.Ox 2.4 . 377.Pp 378.Fn X509_NAME_ENTRY_create_by_txt 379first appeared in OpenSSL 0.9.5 and has been available since 380.Ox 2.7 . 381.Pp 382.Fn X509_NAME_ENTRY_set 383first appeared in OpenSSL 1.1.0 and has been available since 384.Ox 6.3 . 385.Sh CAVEATS 386Despite its name, 387.Fn X509_NAME_ENTRY_set 388does not set anything. 389Something like 390.Dq X509_NAME_ENTRY_get_set 391would have been a better name. 392