1.\" $OpenBSD: X509_NAME_add_entry_by_txt.3,v 1.16 2022/03/31 17:27:17 naddy Exp $ 2.\" OpenSSL aebb9aac Jul 19 09:27:53 2016 -0400 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2002, 2005, 2006, 2013, 2014 The OpenSSL Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: March 31 2022 $ 53.Dt X509_NAME_ADD_ENTRY_BY_TXT 3 54.Os 55.Sh NAME 56.Nm X509_NAME_add_entry_by_txt , 57.Nm X509_NAME_add_entry_by_OBJ , 58.Nm X509_NAME_add_entry_by_NID , 59.Nm X509_NAME_add_entry , 60.Nm X509_NAME_delete_entry 61.Nd X509_NAME modification functions 62.Sh SYNOPSIS 63.In openssl/x509.h 64.Ft int 65.Fo X509_NAME_add_entry_by_txt 66.Fa "X509_NAME *name" 67.Fa "const char *field" 68.Fa "int type" 69.Fa "const unsigned char *bytes" 70.Fa "int len" 71.Fa "int loc" 72.Fa "int set" 73.Fc 74.Ft int 75.Fo X509_NAME_add_entry_by_OBJ 76.Fa "X509_NAME *name" 77.Fa "const ASN1_OBJECT *obj" 78.Fa "int type" 79.Fa "const unsigned char *bytes" 80.Fa "int len" 81.Fa "int loc" 82.Fa "int set" 83.Fc 84.Ft int 85.Fo X509_NAME_add_entry_by_NID 86.Fa "X509_NAME *name" 87.Fa "int nid" 88.Fa "int type" 89.Fa "const unsigned char *bytes" 90.Fa "int len" 91.Fa "int loc" 92.Fa "int set" 93.Fc 94.Ft int 95.Fo X509_NAME_add_entry 96.Fa "X509_NAME *name" 97.Fa "const X509_NAME_ENTRY *ne" 98.Fa "int loc" 99.Fa "int set" 100.Fc 101.Ft X509_NAME_ENTRY * 102.Fo X509_NAME_delete_entry 103.Fa "X509_NAME *name" 104.Fa "int loc" 105.Fc 106.Sh DESCRIPTION 107.Fn X509_NAME_add_entry_by_txt , 108.Fn X509_NAME_add_entry_by_OBJ , 109and 110.Fn X509_NAME_add_entry_by_NID 111add a field whose name is defined by a string 112.Fa field , 113an object 114.Fa obj 115or a NID 116.Fa nid , 117respectively. 118The field value to be added is in 119.Fa bytes 120of length 121.Fa len . 122If 123.Fa len 124is -1 then the field length is calculated internally using 125.Fn strlen bytes . 126.Pp 127The type of field is determined by 128.Fa type 129which can either be a definition of the type of 130.Fa bytes 131(such as 132.Dv MBSTRING_ASC ) 133or a standard ASN.1 type (such as 134.Dv V_ASN1_IA5STRING ) . 135The new entry is added to a position determined by 136.Fa loc 137and 138.Fa set . 139.Pp 140.Fn X509_NAME_add_entry 141adds a copy of an 142.Vt X509_NAME_ENTRY 143structure 144.Fa ne 145to 146.Fa name . 147The new entry is added to a position determined by 148.Fa loc 149and 150.Fa set . 151Since a copy of 152.Fa ne 153is added, 154.Fa ne 155must be freed up after the call. 156.Pp 157.Fn X509_NAME_delete_entry 158deletes an entry from 159.Fa name 160at position 161.Fa loc . 162The deleted entry is returned and must be freed up. 163.Pp 164The use of string types such as 165.Dv MBSTRING_ASC 166or 167.Dv MBSTRING_UTF8 168is strongly recommended for the 169.Fa type 170parameter. 171This allows the internal code to correctly determine the type of the 172field and to apply length checks according to the relevant standards. 173.Pp 174If instead an ASN.1 type is used, no checks are performed and the supplied 175data in 176.Fa bytes 177is used directly. 178.Pp 179In 180.Fn X509_NAME_add_entry_by_txt 181the 182.Fa field 183string represents the field name using 184.Fn OBJ_txt2obj field 0 . 185.Pp 186The 187.Fa loc 188and 189.Fa set 190parameters determine where a new entry should be added. 191For almost all applications, 192.Fa loc 193can be set to -1 and 194.Fa set 195to 0. 196This adds a new entry to the end of 197.Fa name 198as a single valued 199.Vt RelativeDistinguishedName 200(RDN). 201.Pp 202.Fa loc 203actually determines the index where the new entry is inserted: 204if it is -1 it is appended. 205.Pp 206.Fa set 207determines how the new type is added. 208If it is zero, a new RDN is created. 209.Pp 210If 211.Fa set 212is -1 or 1, it is added to the previous or next RDN structure 213respectively. 214This will then be a multivalued RDN: since multivalue RDNs are very 215seldom used, 216.Fa set 217is almost always set to zero. 218.Sh RETURN VALUES 219.Fn X509_NAME_add_entry_by_txt , 220.Fn X509_NAME_add_entry_by_OBJ , 221.Fn X509_NAME_add_entry_by_NID , 222and 223.Fn X509_NAME_add_entry 224return 1 for success or 0 if an error occurred. 225.Pp 226.Fn X509_NAME_delete_entry 227returns either the deleted 228.Vt X509_NAME_ENTRY 229structure or 230.Dv NULL 231if an error occurred. 232.Pp 233In some cases of failure, the reason can be determined with 234.Xr ERR_get_error 3 . 235.Sh EXAMPLES 236Create an 237.Vt X509_NAME 238structure: 239.Bd -literal -offset indent 240C=UK, O=Disorganized Organization, CN=Joe Bloggs 241 242X509_NAME *nm; 243nm = X509_NAME_new(); 244if (nm == NULL) 245 /* Some error */ 246if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC, 247 "UK", -1, -1, 0)) 248 /* Error */ 249if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC, 250 "Disorganized Organization", -1, -1, 0)) 251 /* Error */ 252if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC, 253 "Joe Bloggs", -1, -1, 0)) 254 /* Error */ 255.Ed 256.Sh SEE ALSO 257.Xr d2i_X509_NAME 3 , 258.Xr X509_NAME_ENTRY_get_object 3 , 259.Xr X509_NAME_get_index_by_NID 3 , 260.Xr X509_NAME_new 3 261.Sh HISTORY 262.Fn X509_NAME_add_entry 263and 264.Fn X509_NAME_delete_entry 265first appeared in SSLeay 0.8.0 and have been available since 266.Ox 2.4 . 267.Pp 268.Fn X509_NAME_add_entry_by_txt , 269.Fn X509_NAME_add_entry_by_OBJ , 270and 271.Fn X509_NAME_add_entry_by_NID 272first appeared in OpenSSL 0.9.5 and have been available since 273.Ox 2.7 . 274.Sh BUGS 275.Fa type 276can still be set to 277.Dv V_ASN1_APP_CHOOSE 278to use 279.Xr ASN1_PRINTABLE_type 3 280to determine field types. 281Since this form does not understand multicharacter types, performs 282no length checks, and can result in invalid field types, its use 283is strongly discouraged. 284