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