Merge branch 'vendor/OPENSSL'
[dragonfly.git] / secure / lib / libcrypto / man / X509_NAME_add_entry_by_txt.3
CommitLineData
e257b235 1.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
28.\" double quote, and \*(R" will give a right double quote. \*(C+ will
29.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31.\" nothing in troff, for use with C<>.
32.tr \(*W-
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb 50.\"
e257b235
PA
51.\" Escape single quotes in literal strings from groff's Unicode transform.
52.ie \n(.g .ds Aq \(aq
53.el .ds Aq '
54.\"
8b0cefbb
JR
55.\" If the F register is turned on, we'll generate index entries on stderr for
56.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57.\" entries marked with X<> in POD. Of course, you'll have to process the
58.\" output yourself in some meaningful fashion.
e257b235 59.ie \nF \{\
8b0cefbb
JR
60. de IX
61. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 62..
8b0cefbb
JR
63. nr % 0
64. rr F
984263bc 65.\}
e257b235
PA
66.el \{\
67. de IX
68..
69.\}
aac4ff6f 70.\"
8b0cefbb
JR
71.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72.\" Fear. Run. Save yourself. No user-serviceable parts.
73. \" fudge factors for nroff and troff
984263bc 74.if n \{\
8b0cefbb
JR
75. ds #H 0
76. ds #V .8m
77. ds #F .3m
78. ds #[ \f1
79. ds #] \fP
984263bc
MD
80.\}
81.if t \{\
8b0cefbb
JR
82. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83. ds #V .6m
84. ds #F 0
85. ds #[ \&
86. ds #] \&
984263bc 87.\}
8b0cefbb 88. \" simple accents for nroff and troff
984263bc 89.if n \{\
8b0cefbb
JR
90. ds ' \&
91. ds ` \&
92. ds ^ \&
93. ds , \&
94. ds ~ ~
95. ds /
984263bc
MD
96.\}
97.if t \{\
8b0cefbb
JR
98. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 104.\}
8b0cefbb 105. \" troff and (daisy-wheel) nroff accents
984263bc
MD
106.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113.ds ae a\h'-(\w'a'u*4/10)'e
114.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 115. \" corrections for vroff
984263bc
MD
116.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 118. \" for low resolution devices (crt and lpr)
984263bc
MD
119.if \n(.H>23 .if \n(.V>19 \
120\{\
8b0cefbb
JR
121. ds : e
122. ds 8 ss
123. ds o a
124. ds d- d\h'-1'\(ga
125. ds D- D\h'-1'\(hy
126. ds th \o'bp'
127. ds Th \o'LP'
128. ds ae ae
129. ds Ae AE
984263bc
MD
130.\}
131.rm #[ #] #H #V #F C
8b0cefbb
JR
132.\" ========================================================================
133.\"
134.IX Title "X509_NAME_add_entry_by_txt 3"
fc468453 135.TH X509_NAME_add_entry_by_txt 3 "2010-02-27" "0.9.8m" "OpenSSL"
e257b235
PA
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents.
138.if n .ad l
139.nh
984263bc
MD
140.SH "NAME"
141X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
142X509_NAME_add_entry, X509_NAME_delete_entry \- X509_NAME modification functions
143.SH "SYNOPSIS"
8b0cefbb 144.IX Header "SYNOPSIS"
a561f9ff
SS
145int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set);
146.PP
8b0cefbb 147int X509_NAME_add_entry_by_OBJ(X509_NAME *name, \s-1ASN1_OBJECT\s0 *obj, int type, unsigned char *bytes, int len, int loc, int set);
a561f9ff 148.PP
8b0cefbb 149int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set);
a561f9ff 150.PP
8b0cefbb 151int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set);
a561f9ff 152.PP
8b0cefbb 153X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc);
984263bc 154.SH "DESCRIPTION"
8b0cefbb
JR
155.IX Header "DESCRIPTION"
156\&\fIX509_NAME_add_entry_by_txt()\fR, \fIX509_NAME_add_entry_by_OBJ()\fR and
157\&\fIX509_NAME_add_entry_by_NID()\fR add a field whose name is defined
158by a string \fBfield\fR, an object \fBobj\fR or a \s-1NID\s0 \fBnid\fR respectively.
984263bc 159The field value to be added is in \fBbytes\fR of length \fBlen\fR. If
8b0cefbb
JR
160\&\fBlen\fR is \-1 then the field length is calculated internally using
161strlen(bytes).
984263bc
MD
162.PP
163The type of field is determined by \fBtype\fR which can either be a
8b0cefbb
JR
164definition of the type of \fBbytes\fR (such as \fB\s-1MBSTRING_ASC\s0\fR) or a
165standard \s-1ASN1\s0 type (such as \fBV_ASN1_IA5STRING\fR). The new entry is
984263bc
MD
166added to a position determined by \fBloc\fR and \fBset\fR.
167.PP
8b0cefbb 168\&\fIX509_NAME_add_entry()\fR adds a copy of \fBX509_NAME_ENTRY\fR structure \fBne\fR
984263bc
MD
169to \fBname\fR. The new entry is added to a position determined by \fBloc\fR
170and \fBset\fR. Since a copy of \fBne\fR is added \fBne\fR must be freed up after
171the call.
172.PP
8b0cefbb
JR
173\&\fIX509_NAME_delete_entry()\fR deletes an entry from \fBname\fR at position
174\&\fBloc\fR. The deleted entry is returned and must be freed up.
984263bc 175.SH "NOTES"
8b0cefbb
JR
176.IX Header "NOTES"
177The use of string types such as \fB\s-1MBSTRING_ASC\s0\fR or \fB\s-1MBSTRING_UTF8\s0\fR
984263bc
MD
178is strongly recommened for the \fBtype\fR parameter. This allows the
179internal code to correctly determine the type of the field and to
180apply length checks according to the relevant standards. This is
181done using \fIASN1_STRING_set_by_NID()\fR.
182.PP
8b0cefbb 183If instead an \s-1ASN1\s0 type is used no checks are performed and the
984263bc
MD
184supplied data in \fBbytes\fR is used directly.
185.PP
186In \fIX509_NAME_add_entry_by_txt()\fR the \fBfield\fR string represents
8b0cefbb 187the field name using OBJ_txt2obj(field, 0).
984263bc
MD
188.PP
189The \fBloc\fR and \fBset\fR parameters determine where a new entry should
190be added. For almost all applications \fBloc\fR can be set to \-1 and \fBset\fR
191to 0. This adds a new entry to the end of \fBname\fR as a single valued
8b0cefbb 192RelativeDistinguishedName (\s-1RDN\s0).
984263bc 193.PP
8b0cefbb 194\&\fBloc\fR actually determines the index where the new entry is inserted:
e257b235 195if it is \-1 it is appended.
984263bc 196.PP
8b0cefbb
JR
197\&\fBset\fR determines how the new type is added. If it is zero a
198new \s-1RDN\s0 is created.
984263bc 199.PP
8b0cefbb
JR
200If \fBset\fR is \-1 or 1 it is added to the previous or next \s-1RDN\s0
201structure respectively. This will then be a multivalued \s-1RDN:\s0
984263bc
MD
202since multivalues RDNs are very seldom used \fBset\fR is almost
203always set to zero.
204.SH "EXAMPLES"
8b0cefbb 205.IX Header "EXAMPLES"
984263bc
MD
206Create an \fBX509_NAME\fR structure:
207.PP
8b0cefbb 208\&\*(L"C=UK, O=Disorganized Organization, CN=Joe Bloggs\*(R"
984263bc 209.PP
e257b235 210.Vb 10
984263bc
MD
211\& X509_NAME *nm;
212\& nm = X509_NAME_new();
213\& if (nm == NULL)
214\& /* Some error */
215\& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
e257b235 216\& "C", "UK", \-1, \-1, 0))
984263bc
MD
217\& /* Error */
218\& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
e257b235 219\& "O", "Disorganized Organization", \-1, \-1, 0))
984263bc
MD
220\& /* Error */
221\& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
e257b235 222\& "CN", "Joe Bloggs", \-1, \-1, 0))
984263bc
MD
223\& /* Error */
224.Ve
225.SH "RETURN VALUES"
8b0cefbb
JR
226.IX Header "RETURN VALUES"
227\&\fIX509_NAME_add_entry_by_txt()\fR, \fIX509_NAME_add_entry_by_OBJ()\fR,
228\&\fIX509_NAME_add_entry_by_NID()\fR and \fIX509_NAME_add_entry()\fR return 1 for
984263bc
MD
229success of 0 if an error occurred.
230.PP
8b0cefbb
JR
231\&\fIX509_NAME_delete_entry()\fR returns either the deleted \fBX509_NAME_ENTRY\fR
232structure of \fB\s-1NULL\s0\fR if an error occurred.
984263bc 233.SH "BUGS"
8b0cefbb
JR
234.IX Header "BUGS"
235\&\fBtype\fR can still be set to \fBV_ASN1_APP_CHOOSE\fR to use a
984263bc
MD
236different algorithm to determine field types. Since this form does
237not understand multicharacter types, performs no length checks and
238can result in invalid field types its use is strongly discouraged.
239.SH "SEE ALSO"
74dab6c2 240.IX Header "SEE ALSO"
8b0cefbb
JR
241\&\fIERR_get_error\fR\|(3), \fId2i_X509_NAME\fR\|(3)
242.SH "HISTORY"
984263bc 243.IX Header "HISTORY"