Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / X509_NAME_add_entry_by_txt.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH X509_NAME_add_entry_by_txt 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
192X509_NAME_add_entry, X509_NAME_delete_entry \- X509_NAME modification functions
193.SH "SYNOPSIS"
74dab6c2
JR
194int \fIX509_NAME_add_entry_by_txt\fR\|(X509_NAME *name, char *field, int type, unsigned char *bytes, int len, int loc, int set);
195int \fIX509_NAME_add_entry_by_OBJ\fR\|(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set);
196int \fIX509_NAME_add_entry_by_NID\fR\|(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set);
197int \fIX509_NAME_add_entry\fR\|(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set);
198X509_NAME_ENTRY *\fIX509_NAME_delete_entry\fR\|(X509_NAME *name, int loc);
984263bc 199.SH "DESCRIPTION"
74dab6c2
JR
200\fIX509_NAME_add_entry_by_txt()\fR, \fIX509_NAME_add_entry_by_OBJ()\fR and
201\fIX509_NAME_add_entry_by_NID()\fR add a field whose name is defined
202by a string \fBfield\fR, an object \fBobj\fR or a NID \fBnid\fR respectively.
984263bc 203The field value to be added is in \fBbytes\fR of length \fBlen\fR. If
74dab6c2
JR
204\fBlen\fR is \-1 then the field length is calculated internally using
205\fIstrlen\fR\|(bytes).
984263bc
MD
206.PP
207The type of field is determined by \fBtype\fR which can either be a
74dab6c2
JR
208definition of the type of \fBbytes\fR (such as \fBMBSTRING_ASC\fR) or a
209standard ASN1 type (such as \fBV_ASN1_IA5STRING\fR). The new entry is
984263bc
MD
210added to a position determined by \fBloc\fR and \fBset\fR.
211.PP
74dab6c2 212\fIX509_NAME_add_entry()\fR adds a copy of \fBX509_NAME_ENTRY\fR structure \fBne\fR
984263bc
MD
213to \fBname\fR. The new entry is added to a position determined by \fBloc\fR
214and \fBset\fR. Since a copy of \fBne\fR is added \fBne\fR must be freed up after
215the call.
216.PP
74dab6c2
JR
217\fIX509_NAME_delete_entry()\fR deletes an entry from \fBname\fR at position
218\fBloc\fR. The deleted entry is returned and must be freed up.
984263bc 219.SH "NOTES"
74dab6c2 220The use of string types such as \fBMBSTRING_ASC\fR or \fBMBSTRING_UTF8\fR
984263bc
MD
221is strongly recommened for the \fBtype\fR parameter. This allows the
222internal code to correctly determine the type of the field and to
223apply length checks according to the relevant standards. This is
224done using \fIASN1_STRING_set_by_NID()\fR.
225.PP
74dab6c2 226If instead an ASN1 type is used no checks are performed and the
984263bc
MD
227supplied data in \fBbytes\fR is used directly.
228.PP
229In \fIX509_NAME_add_entry_by_txt()\fR the \fBfield\fR string represents
74dab6c2 230the field name using \fIOBJ_txt2obj\fR\|(field, 0).
984263bc
MD
231.PP
232The \fBloc\fR and \fBset\fR parameters determine where a new entry should
233be added. For almost all applications \fBloc\fR can be set to \-1 and \fBset\fR
234to 0. This adds a new entry to the end of \fBname\fR as a single valued
74dab6c2 235RelativeDistinguishedName (RDN).
984263bc 236.PP
74dab6c2 237\fBloc\fR actually determines the index where the new entry is inserted:
984263bc
MD
238if it is \-1 it is appended.
239.PP
74dab6c2
JR
240\fBset\fR determines how the new type is added. If it is zero a
241new RDN is created.
984263bc 242.PP
74dab6c2
JR
243If \fBset\fR is \-1 or 1 it is added to the previous or next RDN
244structure respectively. This will then be a multivalued RDN:
984263bc
MD
245since multivalues RDNs are very seldom used \fBset\fR is almost
246always set to zero.
247.SH "EXAMPLES"
984263bc
MD
248Create an \fBX509_NAME\fR structure:
249.PP
74dab6c2 250\*(L"C=UK, O=Disorganized Organization, CN=Joe Bloggs\*(R"
984263bc
MD
251.PP
252.Vb 13
253\& X509_NAME *nm;
254\& nm = X509_NAME_new();
255\& if (nm == NULL)
256\& /* Some error */
257\& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
258\& "C", "UK", -1, -1, 0))
259\& /* Error */
260\& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
261\& "O", "Disorganized Organization", -1, -1, 0))
262\& /* Error */
263\& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
264\& "CN", "Joe Bloggs", -1, -1, 0))
265\& /* Error */
266.Ve
267.SH "RETURN VALUES"
74dab6c2
JR
268\fIX509_NAME_add_entry_by_txt()\fR, \fIX509_NAME_add_entry_by_OBJ()\fR,
269\fIX509_NAME_add_entry_by_NID()\fR and \fIX509_NAME_add_entry()\fR return 1 for
984263bc
MD
270success of 0 if an error occurred.
271.PP
74dab6c2
JR
272\fIX509_NAME_delete_entry()\fR returns either the deleted \fBX509_NAME_ENTRY\fR
273structure of \fBNULL\fR if an error occurred.
984263bc 274.SH "BUGS"
74dab6c2 275\fBtype\fR can still be set to \fBV_ASN1_APP_CHOOSE\fR to use a
984263bc
MD
276different algorithm to determine field types. Since this form does
277not understand multicharacter types, performs no length checks and
278can result in invalid field types its use is strongly discouraged.
279.SH "SEE ALSO"
984263bc
MD
280ERR_get_error(3), d2i_X509_NAME(3)
281.SH "HISTORY"
74dab6c2
JR
282
283.rn }` ''
284.IX Title "X509_NAME_add_entry_by_txt 3"
285.IX Name "X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
286X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions"
287
288.IX Header "NAME"
289
290.IX Header "SYNOPSIS"
291
292.IX Header "DESCRIPTION"
293
294.IX Header "NOTES"
295
296.IX Header "EXAMPLES"
297
298.IX Header "RETURN VALUES"
299
300.IX Header "BUGS"
301
302.IX Header "SEE ALSO"
303
984263bc 304.IX Header "HISTORY"
74dab6c2 305