| blob | a2a9314c07fd89fe207fd52aa4979189da4dddef |
1 .\" $OpenBSD: X509_NAME_add_entry_by_txt.3,v 1.7 2017/01/06 03:00:56 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: January 6 2017 $
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
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 BUGS
259 .Fa type
260 can still be set to
261 .Dv V_ASN1_APP_CHOOSE
262 to use a different algorithm to determine field types.
263 Since this form does not understand multicharacter types, performs
264 no length checks, and can result in invalid field types, its use
265 is strongly discouraged.