lib/libcrypto/man/X509_NAME_add_entry_by_txt.3

   1 .\"     $OpenBSD: X509_NAME_add_entry_by_txt.3,v 1.9 2018/03/22 16:06:33 schwarze 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 22 2018 $
  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 "ASN1_OBJECT *obj"
  78 .Fa "int type"
  79 .Fa "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 "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 "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 ,
 109 and
 110 .Fn X509_NAME_add_entry_by_NID
 111 add a field whose name is defined by a string
 112 .Fa field ,
 113 an object
 114 .Fa obj
 115 or a NID
 116 .Fa nid ,
 117 respectively.
 118 The field value to be added is in
 119 .Fa bytes
 120 of length
 121 .Fa len .
 122 If
 123 .Fa len
 124 is -1 then the field length is calculated internally using
 125 .Fn strlen bytes .
 126 .Pp
 127 The type of field is determined by
 128 .Fa type
 129 which can either be a definition of the type of
 130 .Fa bytes
 131 (such as
 132 .Dv MBSTRING_ASC )
 133 or a standard ASN.1 type (such as
 134 .Dv V_ASN1_IA5STRING ) .
 135 The new entry is added to a position determined by
 136 .Fa loc
 137 and
 138 .Fa set .
 139 .Pp
 140 .Fn X509_NAME_add_entry
 141 adds a copy of an
 142 .Vt X509_NAME_ENTRY
 143 structure
 144 .Fa ne
 145 to
 146 .Fa name .
 147 The new entry is added to a position determined by
 148 .Fa loc
 149 and
 150 .Fa set .
 151 Since a copy of
 152 .Fa ne
 153 is added,
 154 .Fa ne
 155 must be freed up after the call.
 156 .Pp
 157 .Fn X509_NAME_delete_entry
 158 deletes an entry from
 159 .Fa name
 160 at position
 161 .Fa loc .
 162 The deleted entry is returned and must be freed up.
 163 .Pp
 164 The use of string types such as
 165 .Dv MBSTRING_ASC
 166 or
 167 .Dv MBSTRING_UTF8
 168 is strongly recommended for the
 169 .Fa type
 170 parameter.
 171 This allows the internal code to correctly determine the type of the
 172 field and to apply length checks according to the relevant standards.
 173 .Pp
 174 If instead an ASN.1 type is used, no checks are performed and the supplied
 175 data in
 176 .Fa bytes
 177 is used directly.
 178 .Pp
 179 In
 180 .Fn X509_NAME_add_entry_by_txt
 181 the
 182 .Fa field
 183 string represents the field name using
 184 .Fn OBJ_txt2obj field 0 .
 185 .Pp
 186 The
 187 .Fa loc
 188 and
 189 .Fa set
 190 parameters determine where a new entry should be added.
 191 For almost all applications,
 192 .Fa loc
 193 can be set to -1 and
 194 .Fa set
 195 to 0.
 196 This adds a new entry to the end of
 197 .Fa name
 198 as a single valued
 199 .Vt RelativeDistinguishedName
 200 (RDN).
 201 .Pp
 202 .Fa loc
 203 actually determines the index where the new entry is inserted:
 204 if it is -1 it is appended.
 205 .Pp
 206 .Fa set
 207 determines how the new type is added.
 208 If it is zero a new RDN is created.
 209 .Pp
 210 If
 211 .Fa set
 212 is -1 or 1 it is added to the previous or next RDN structure
 213 respectively.
 214 This will then be a multivalued RDN: since multivalue RDNs are very
 215 seldom used,
 216 .Fa set
 217 is 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 ,
 222 and
 223 .Fn X509_NAME_add_entry
 224 return 1 for success or 0 if an error occurred.
 225 .Pp
 226 .Fn X509_NAME_delete_entry
 227 returns either the deleted
 228 .Vt X509_NAME_ENTRY
 229 structure or
 230 .Dv NULL
 231 if an error occurred.
 232 .Sh EXAMPLES
 233 Create an
 234 .Vt X509_NAME
 235 structure:
 236 .Bd -literal -offset indent
 237 C=UK, O=Disorganized Organization, CN=Joe Bloggs
 238
 239 X509_NAME *nm;
 240 nm = X509_NAME_new();
 241 if (nm == NULL)
 242         /* Some error */
 243 if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC,
 244                 "UK", -1, -1, 0))
 245         /* Error */
 246 if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC,
 247                 "Disorganized Organization", -1, -1, 0))
 248         /* Error */
 249 if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC,
 250                 "Joe Bloggs", -1, -1, 0))
 251         /* Error */
 252 .Ed
 253 .Sh SEE ALSO
 254 .Xr d2i_X509_NAME 3 ,
 255 .Xr ERR_get_error 3 ,
 256 .Xr X509_NAME_get_index_by_NID 3 ,
 257 .Xr X509_NAME_new 3
 258 .Sh HISTORY
 259 .Fn X509_NAME_add_entry
 260 and
 261 .Fn X509_NAME_delete_entry
 262 appeared before SSLeay 0.8 and have been available since
 263 .Ox 2.4 .
 264 .Pp
 265 .Fn X509_NAME_add_entry_by_txt ,
 266 .Fn X509_NAME_add_entry_by_OBJ ,
 267 and
 268 .Fn X509_NAME_add_entry_by_NID
 269 first appeared in OpenSSL 0.9.5 and have been available since
 270 .Ox 2.7 .
 271 .Sh BUGS
 272 .Fa type
 273 can still be set to
 274 .Dv V_ASN1_APP_CHOOSE
 275 to use a different algorithm to determine field types.
 276 Since this form does not understand multicharacter types, performs
 277 no length checks, and can result in invalid field types, its use
 278 is strongly discouraged.