Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / X509_NAME_add_entry_by_txt.3
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 '''
6 .de Sh
7 .br
8 .if t .Sp
9 .ne 5
10 .PP
11 \fB\\$1\fR
12 .PP
13 ..
14 .de Sp
15 .if t .sp .5v
16 .if n .sp
17 ..
18 .de Ip
19 .br
20 .ie \\n(.$>=3 .ne \\$3
21 .el .ne 3
22 .IP "\\$1" \\$2
23 ..
24 .de Vb
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve
30 .ft R
31
32 .fi
33 ..
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 '''
40 .tr \(*W-|\(bv\*(Tr
41 .ie n \{\
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' '
62 'br\}
63 .el\{\
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
79 'br\}
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"
92 ..
93 .nr % 0
94 .rr F
95 .\}
96 .TH X509_NAME_add_entry_by_txt 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97 .UC
98 .if n .hy 0
99 .if n .na
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
112 .bd B 3
113 .       \" fudge factors for nroff and troff
114 .if n \{\
115 .       ds #H 0
116 .       ds #V .8m
117 .       ds #F .3m
118 .       ds #[ \f1
119 .       ds #] \fP
120 .\}
121 .if t \{\
122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123 .       ds #V .6m
124 .       ds #F 0
125 .       ds #[ \&
126 .       ds #] \&
127 .\}
128 .       \" simple accents for nroff and troff
129 .if n \{\
130 .       ds ' \&
131 .       ds ` \&
132 .       ds ^ \&
133 .       ds , \&
134 .       ds ~ ~
135 .       ds ? ?
136 .       ds ! !
137 .       ds /
138 .       ds q
139 .\}
140 .if t \{\
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'
150 .\}
151 .       \" troff and (daisy-wheel) nroff accents
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'
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'\*(#]
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
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
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'
170 .       \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
172 \{\
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
188 .\}
189 .rm #[ #] #H #V #F C
190 .SH "NAME"
191 X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
192 X509_NAME_add_entry, X509_NAME_delete_entry \- X509_NAME modification functions
193 .SH "SYNOPSIS"
194 int \fIX509_NAME_add_entry_by_txt\fR\|(X509_NAME *name, char *field, int type, unsigned char *bytes, int len, int loc, int set);
195 int \fIX509_NAME_add_entry_by_OBJ\fR\|(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set);
196 int \fIX509_NAME_add_entry_by_NID\fR\|(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set);
197 int \fIX509_NAME_add_entry\fR\|(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set);
198 X509_NAME_ENTRY *\fIX509_NAME_delete_entry\fR\|(X509_NAME *name, int loc);
199 .SH "DESCRIPTION"
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
202 by a string \fBfield\fR, an object \fBobj\fR or a NID \fBnid\fR respectively.
203 The field value to be added is in \fBbytes\fR of length \fBlen\fR. If
204 \fBlen\fR is \-1 then the field length is calculated internally using
205 \fIstrlen\fR\|(bytes).
206 .PP
207 The type of field is determined by \fBtype\fR which can either be a
208 definition of the type of \fBbytes\fR (such as \fBMBSTRING_ASC\fR) or a
209 standard ASN1 type (such as \fBV_ASN1_IA5STRING\fR). The new entry is
210 added to a position determined by \fBloc\fR and \fBset\fR.
211 .PP
212 \fIX509_NAME_add_entry()\fR adds a copy of \fBX509_NAME_ENTRY\fR structure \fBne\fR
213 to \fBname\fR. The new entry is added to a position determined by \fBloc\fR
214 and \fBset\fR. Since a copy of \fBne\fR is added \fBne\fR must be freed up after
215 the call.
216 .PP
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.
219 .SH "NOTES"
220 The use of string types such as \fBMBSTRING_ASC\fR or \fBMBSTRING_UTF8\fR
221 is strongly recommened for the \fBtype\fR parameter. This allows the
222 internal code to correctly determine the type of the field and to
223 apply length checks according to the relevant standards. This is
224 done using \fIASN1_STRING_set_by_NID()\fR.
225 .PP
226 If instead an ASN1 type is used no checks are performed and the
227 supplied data in \fBbytes\fR is used directly.
228 .PP
229 In \fIX509_NAME_add_entry_by_txt()\fR the \fBfield\fR string represents
230 the field name using \fIOBJ_txt2obj\fR\|(field, 0).
231 .PP
232 The \fBloc\fR and \fBset\fR parameters determine where a new entry should
233 be added. For almost all applications \fBloc\fR can be set to \-1 and \fBset\fR
234 to 0. This adds a new entry to the end of \fBname\fR as a single valued
235 RelativeDistinguishedName (RDN).
236 .PP
237 \fBloc\fR actually determines the index where the new entry is inserted:
238 if it is \-1 it is appended. 
239 .PP
240 \fBset\fR determines how the new type is added. If it is zero a
241 new RDN is created.
242 .PP
243 If \fBset\fR is \-1 or 1 it is added to the previous or next RDN
244 structure respectively. This will then be a multivalued RDN:
245 since multivalues RDNs are very seldom used \fBset\fR is almost
246 always set to zero.
247 .SH "EXAMPLES"
248 Create an \fBX509_NAME\fR structure:
249 .PP
250 \*(L"C=UK, O=Disorganized Organization, CN=Joe Bloggs\*(R"
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"
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
270 success of 0 if an error occurred.
271 .PP
272 \fIX509_NAME_delete_entry()\fR returns either the deleted \fBX509_NAME_ENTRY\fR
273 structure of \fBNULL\fR if an error occurred.
274 .SH "BUGS"
275 \fBtype\fR can still be set to \fBV_ASN1_APP_CHOOSE\fR to use a
276 different algorithm to determine field types. Since this form does
277 not understand multicharacter types, performs no length checks and
278 can result in invalid field types its use is strongly discouraged.
279 .SH "SEE ALSO"
280 ERR_get_error(3), d2i_X509_NAME(3)
281 .SH "HISTORY"
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,
286 X509_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
304 .IX Header "HISTORY"
305