1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
.\" $OpenBSD: X509_NAME_add_entry_by_txt.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
.\"
.Dd $Mdocdate: November 6 2016 $
.Dt X509_NAME_ADD_ENTRY_BY_TXT 3
.Os
.Sh NAME
.Nm X509_NAME_add_entry_by_txt ,
.Nm X509_NAME_add_entry_by_OBJ ,
.Nm X509_NAME_add_entry_by_NID ,
.Nm X509_NAME_add_entry ,
.Nm X509_NAME_delete_entry
.Nd X509_NAME modification functions
.Sh SYNOPSIS
.In openssl/x509.h
.Ft int
.Fo X509_NAME_add_entry_by_txt
.Fa "X509_NAME *name"
.Fa "const char *field"
.Fa "int type"
.Fa "const unsigned char *bytes"
.Fa "int len"
.Fa "int loc"
.Fa "int set"
.Fc
.Ft int
.Fo X509_NAME_add_entry_by_OBJ
.Fa "X509_NAME *name"
.Fa "ASN1_OBJECT *obj"
.Fa "int type"
.Fa "unsigned char *bytes"
.Fa "int len"
.Fa "int loc"
.Fa "int set"
.Fc
.Ft int
.Fo X509_NAME_add_entry_by_NID
.Fa "X509_NAME *name"
.Fa "int nid"
.Fa "int type"
.Fa "unsigned char *bytes"
.Fa "int len"
.Fa "int loc"
.Fa "int set"
.Fc
.Ft int
.Fo X509_NAME_add_entry
.Fa "X509_NAME *name"
.Fa "X509_NAME_ENTRY *ne"
.Fa "int loc"
.Fa "int set"
.Fc
.Ft X509_NAME_ENTRY *
.Fo X509_NAME_delete_entry
.Fa "X509_NAME *name"
.Fa "int loc"
.Fc
.Sh DESCRIPTION
.Fn X509_NAME_add_entry_by_txt ,
.Fn X509_NAME_add_entry_by_OBJ ,
and
.Fn X509_NAME_add_entry_by_NID
add a field whose name is defined by a string
.Fa field ,
an object
.Fa obj
or a NID
.Fa nid ,
respectively.
The field value to be added is in
.Fa bytes
of length
.Fa len .
If
.Fa len
is -1 then the field length is calculated internally using
.Fn strlen bytes .
.Pp
The type of field is determined by
.Fa type
which can either be a definition of the type of
.Fa bytes
(such as
.Dv MBSTRING_ASC )
or a standard ASN1 type (such as
.Dv V_ASN1_IA5STRING ) .
The new entry is added to a position determined by
.Fa loc
and
.Fa set .
.Pp
.Fn X509_NAME_add_entry
adds a copy of a
.Vt X509_NAME_ENTRY
structure
.Fa ne
to
.Fa name .
The new entry is added to a position determined by
.Fa loc
and
.Fa set .
Since a copy of
.Fa ne
is added,
.Fa ne
must be freed up after the call.
.Pp
.Fn X509_NAME_delete_entry
deletes an entry from
.Fa name
at position
.Fa loc .
The deleted entry is returned and must be freed up.
.Pp
The use of string types such as
.Dv MBSTRING_ASC
or
.Dv MBSTRING_UTF8
is strongly recommended for the
.Fa type
parameter.
This allows the internal code to correctly determine the type of the
field and to apply length checks according to the relevant standards.
This is done using
.Xr ASN1_STRING_set_by_NID 3 .
.Pp
If instead an ASN1 type is used, no checks are performed and the supplied
data in
.Fa bytes
is used directly.
.Pp
In
.Fn X509_NAME_add_entry_by_txt
the
.Fa field
string represents the field name using
.Fn OBJ_txt2obj field 0 .
.Pp
The
.Fa loc
and
.Fa set
parameters determine where a new entry should be added.
For almost all applications,
.Fa loc
can be set to -1 and
.Fa set
to 0.
This adds a new entry to the end of
.Fa name
as a single valued RelativeDistinguishedName (RDN).
.Pp
.Fa loc
actually determines the index where the new entry is inserted:
if it is -1 it is appended.
.Pp
.Fa set
determines how the new type is added.
If it is zero a new RDN is created.
.Pp
If
.Fa set
is -1 or 1 it is added to the previous or next RDN structure
respectively.
This will then be a multivalued RDN: since multivalues RDNs are very
seldom used,
.Fa set
is almost always set to zero.
.Sh RETURN VALUES
.Fn X509_NAME_add_entry_by_txt ,
.Fn X509_NAME_add_entry_by_OBJ ,
.Fn X509_NAME_add_entry_by_NID ,
and
.Fn X509_NAME_add_entry
return 1 for success or 0 if an error occurred.
.Pp
.Fn X509_NAME_delete_entry
returns either the deleted
.Vt X509_NAME_ENTRY
structure or
.Dv NULL
if an error occurred.
.Sh EXAMPLES
Create an
.Vt X509_NAME
structure:
.Pp
.D1 C=UK, O=Disorganized Organization, CN=Joe Bloggs
.Bd -literal
X509_NAME *nm;
nm = X509_NAME_new();
if (nm == NULL)
/* Some error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"C", "UK", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"O", "Disorganized Organization", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"CN", "Joe Bloggs", -1, -1, 0))
/* Error */
.Ed
.Sh SEE ALSO
.Xr d2i_X509_NAME 3 ,
.Xr ERR_get_error 3
.Sh BUGS
.Fa type
can still be set to
.Dv V_ASN1_APP_CHOOSE
to use a different algorithm to determine field types.
Since this form does not understand multicharacter types, performs
no length checks, and can result in invalid field types, its use
is strongly discouraged.
|
