Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / ASN1_generate_nconf.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
a561f9ff
SS
2.\"
3.\" Standard preamble:
4.\" ========================================================================
a561f9ff
SS
5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v
7.if n .sp
8..
9.de Vb \" Begin verbatim text
10.ft CW
11.nf
12.ne \\$1
13..
14.de Ve \" End verbatim text
15.ft R
16.fi
17..
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
a561f9ff
SS
25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26.ie n \{\
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
35'br\}
36.el\{\
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
41'br\}
42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
a561f9ff 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
a561f9ff
SS
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
a561f9ff
SS
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
54..
55. nr % 0
56. rr F
57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
a561f9ff
SS
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
66.if n \{\
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
72.\}
73.if t \{\
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
79.\}
80. \" simple accents for nroff and troff
81.if n \{\
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
88.\}
89.if t \{\
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'
96.\}
97. \" troff and (daisy-wheel) nroff accents
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
107. \" corrections for vroff
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'
110. \" for low resolution devices (crt and lpr)
111.if \n(.H>23 .if \n(.V>19 \
112\{\
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
122.\}
123.rm #[ #] #H #V #F C
124.\" ========================================================================
125.\"
126.IX Title "ASN1_generate_nconf 3"
e3261593 127.TH ASN1_generate_nconf 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
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
a561f9ff
SS
132.SH "NAME"
133ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
134.SH "SYNOPSIS"
135.IX Header "SYNOPSIS"
01185282
PA
136.Vb 1
137\& #include <openssl/asn1.h>
138\&
a561f9ff
SS
139\& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
140\& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
141.Ve
142.SH "DESCRIPTION"
143.IX Header "DESCRIPTION"
144These functions generate the \s-1ASN1\s0 encoding of a string
145in an \fB\s-1ASN1_TYPE\s0\fR structure.
146.PP
147\&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
148the optional configuration information where additional strings
149will be read from. \fBnconf\fR will typically come from a config
150file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
151which will typically be used by X509 v3 certificate extension
152functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
153configuration will be used.
154.SH "GENERATION STRING FORMAT"
155.IX Header "GENERATION STRING FORMAT"
156The actual data encoded is determined by the string \fBstr\fR and
157the configuration information. The general format of the string
158is:
aac4ff6f
PA
159.IP "\fB[modifier,]type[:value]\fR" 2
160.IX Item "[modifier,]type[:value]"
a561f9ff
SS
161.PP
162That is zero or more comma separated modifiers followed by a type
163followed by an optional colon and a value. The formats of \fBtype\fR,
164\&\fBvalue\fR and \fBmodifier\fR are explained below.
01185282 165.SS "\s-1SUPPORTED\s0 \s-1TYPES\s0"
a561f9ff
SS
166.IX Subsection "SUPPORTED TYPES"
167The supported types are listed below. Unless otherwise specified
168only the \fB\s-1ASCII\s0\fR format is permissible.
169.IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
170.IX Item "BOOLEAN, BOOL"
171This encodes a boolean type. The \fBvalue\fR string is mandatory and
172should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
173\&\fBy\fR, \fB\s-1YES\s0\fR, \fByes\fR, \fB\s-1FALSE\s0\fR, \fBfalse\fR, \fBN\fR, \fBn\fR, \fB\s-1NO\s0\fR and \fBno\fR
e257b235 174are acceptable.
a561f9ff
SS
175.IP "\fB\s-1NULL\s0\fR" 2
176.IX Item "NULL"
177Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
178.IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
179.IX Item "INTEGER, INT"
180Encodes an \s-1ASN1\s0 \fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
181the value of the integer, it can be preceeded by a minus sign and
182is normally interpreted as a decimal value unless the prefix \fB0x\fR
183is included.
184.IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
185.IX Item "ENUMERATED, ENUM"
186Encodes the \s-1ASN1\s0 \fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
187\&\fB\s-1INTEGER\s0\fR.
188.IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
189.IX Item "OBJECT, OID"
190Encodes an \s-1ASN1\s0 \fB\s-1OBJECT\s0 \s-1IDENTIFIER\s0\fR, the \fBvalue\fR string can be
191a short name, a long name or numerical format.
192.IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
193.IX Item "UTCTIME, UTC"
194Encodes an \s-1ASN1\s0 \fBUTCTime\fR structure, the value should be in
e257b235 195the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
a561f9ff
SS
196.IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
197.IX Item "GENERALIZEDTIME, GENTIME"
198Encodes an \s-1ASN1\s0 \fBGeneralizedTime\fR structure, the value should be in
e257b235 199the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
a561f9ff
SS
200.IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
201.IX Item "OCTETSTRING, OCT"
aac4ff6f 202Encodes an \s-1ASN1\s0 \fB\s-1OCTET\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
a561f9ff
SS
203of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
204used to specify the format of \fBvalue\fR.
aac4ff6f
PA
205.IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
206.IX Item "BITSTRING, BITSTR"
207Encodes an \s-1ASN1\s0 \fB\s-1BIT\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
a561f9ff
SS
208of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
209can be used to specify the format of \fBvalue\fR.
210.Sp
211If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
212bits is set to zero.
01185282
PA
213.IP "\fB\s-1UNIVERSALSTRING\s0\fR, \fB\s-1UNIV\s0\fR, \fB\s-1IA5\s0\fR, \fB\s-1IA5STRING\s0\fR, \fB\s-1UTF8\s0\fR, \fBUTF8String\fR, \fB\s-1BMP\s0\fR, \fB\s-1BMPSTRING\s0\fR, \fB\s-1VISIBLESTRING\s0\fR, \fB\s-1VISIBLE\s0\fR, \fB\s-1PRINTABLESTRING\s0\fR, \fB\s-1PRINTABLE\s0\fR, \fBT61\fR, \fBT61STRING\fR, \fB\s-1TELETEXSTRING\s0\fR, \fBGeneralString\fR, \fB\s-1NUMERICSTRING\s0\fR, \fB\s-1NUMERIC\s0\fR" 2
214.IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC"
a561f9ff
SS
215These encode the corresponding string types. \fBvalue\fR represents the
216contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
217.IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
218.IX Item "SEQUENCE, SEQ, SET"
219Formats the result as an \s-1ASN1\s0 \fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
220should be a section name which will contain the contents. The
221field names in the section are ignored and the values are in the
222generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
223will be encoded.
01185282 224.SS "\s-1MODIFIERS\s0"
a561f9ff
SS
225.IX Subsection "MODIFIERS"
226Modifiers affect the following structure, they can be used to
227add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
228the string format of the final type and value. The supported
229formats are documented below.
230.IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
231.IX Item "EXPLICIT, EXP"
232Add an explicit tag to the following structure. This string
233should be followed by a colon and the tag value to use as a
234decimal value.
235.Sp
236By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL\s0,
237\&\s-1APPLICATION\s0, \s-1PRIVATE\s0 or \s-1CONTEXT\s0 \s-1SPECIFIC\s0 tagging can be used,
238the default is \s-1CONTEXT\s0 \s-1SPECIFIC\s0.
239.IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
240.IX Item "IMPLICIT, IMP"
241This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
242instead.
243.IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
244.IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
245The following structure is surrounded by an \s-1OCTET\s0 \s-1STRING\s0, a \s-1SEQUENCE\s0,
246a \s-1SET\s0 or a \s-1BIT\s0 \s-1STRING\s0 respectively. For a \s-1BIT\s0 \s-1STRING\s0 the number of unused
247bits is set to zero.
248.IP "\fB\s-1FORMAT\s0\fR" 2
249.IX Item "FORMAT"
250This specifies the format of the ultimate value. It should be followed
251by a colon and one of the strings \fB\s-1ASCII\s0\fR, \fB\s-1UTF8\s0\fR, \fB\s-1HEX\s0\fR or \fB\s-1BITLIST\s0\fR.
252.Sp
aac4ff6f
PA
253If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
254specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
255output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT\s0
256\&\s-1STRING\s0) is a comma separated list of the indices of the set bits, all other
257bits are zero.
a561f9ff
SS
258.SH "EXAMPLES"
259.IX Header "EXAMPLES"
260A simple IA5String:
261.PP
262.Vb 1
263\& IA5STRING:Hello World
264.Ve
265.PP
266An IA5String explicitly tagged:
267.PP
268.Vb 1
269\& EXPLICIT:0,IA5STRING:Hello World
270.Ve
271.PP
272An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
273.PP
274.Vb 1
275\& EXPLICIT:0A,IA5STRING:Hello World
276.Ve
277.PP
aac4ff6f
PA
278A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
279.PP
280.Vb 1
01185282 281\& FORMAT:BITLIST,BITSTRING:1,5
aac4ff6f
PA
282.Ve
283.PP
a561f9ff
SS
284A more complex example using a config file to produce a
285\&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
286.PP
aac4ff6f
PA
287.Vb 1
288\& asn1 = SEQUENCE:seq_section
e257b235 289\&
aac4ff6f 290\& [seq_section]
e257b235 291\&
aac4ff6f
PA
292\& field1 = BOOLEAN:TRUE
293\& field2 = OID:commonName
294\& field3 = UTF8:Third field
295.Ve
a561f9ff
SS
296.PP
297This example produces an RSAPrivateKey structure, this is the
298key contained in the file client.pem in all OpenSSL distributions
299(note: the field names such as 'coeff' are ignored and are present just
300for clarity):
301.PP
302.Vb 3
303\& asn1=SEQUENCE:private_key
304\& [private_key]
305\& version=INTEGER:0
e257b235 306\&
a561f9ff
SS
307\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
308\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
e257b235 309\&
a561f9ff 310\& e=INTEGER:0x010001
e257b235 311\&
a561f9ff
SS
312\& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
313\& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
e257b235 314\&
a561f9ff
SS
315\& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
316\& D4BD57
e257b235 317\&
a561f9ff
SS
318\& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
319\& 46EC4F
e257b235 320\&
a561f9ff
SS
321\& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
322\& 9C0A39B9
e257b235 323\&
a561f9ff
SS
324\& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
325\& E7B2458F
e257b235 326\&
a561f9ff
SS
327\& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
328\& 628657053A
329.Ve
330.PP
331This example is the corresponding public key in a SubjectPublicKeyInfo
332structure:
333.PP
334.Vb 2
335\& # Start with a SEQUENCE
336\& asn1=SEQUENCE:pubkeyinfo
e257b235 337\&
a561f9ff
SS
338\& # pubkeyinfo contains an algorithm identifier and the public key wrapped
339\& # in a BIT STRING
340\& [pubkeyinfo]
341\& algorithm=SEQUENCE:rsa_alg
342\& pubkey=BITWRAP,SEQUENCE:rsapubkey
e257b235 343\&
a561f9ff
SS
344\& # algorithm ID for RSA is just an OID and a NULL
345\& [rsa_alg]
346\& algorithm=OID:rsaEncryption
347\& parameter=NULL
e257b235 348\&
a561f9ff
SS
349\& # Actual public key: modulus and exponent
350\& [rsapubkey]
351\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
352\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
e257b235 353\&
a561f9ff
SS
354\& e=INTEGER:0x010001
355.Ve
356.SH "RETURN VALUES"
357.IX Header "RETURN VALUES"
358\&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
359data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
360.PP
361The error codes that can be obtained by \fIERR_get_error\fR\|(3).
362.SH "SEE ALSO"
363.IX Header "SEE ALSO"
364\&\fIERR_get_error\fR\|(3)
365.SH "HISTORY"
366.IX Header "HISTORY"
367\&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8