- update OpenSSL to 0.9.8
[dragonfly.git] / secure / lib / libcrypto / man / ASN1_generate_nconf.3
CommitLineData
a561f9ff
SS
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
13.de Sp \" Vertical space (when we can't use .PP)
14.if t .sp .5v
15.if n .sp
16..
17.de Vb \" Begin verbatim text
18.ft CW
19.nf
20.ne \\$1
21..
22.de Ve \" End verbatim text
23.ft R
24.fi
25..
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34.ie n \{\
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' ""
43'br\}
44.el\{\
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
49'br\}
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"
58..
59. nr % 0
60. rr F
61.\}
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
71.if n \{\
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
77.\}
78.if t \{\
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
84.\}
85. \" simple accents for nroff and troff
86.if n \{\
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
93.\}
94.if t \{\
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101.\}
102. \" troff and (daisy-wheel) nroff accents
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
112. \" corrections for vroff
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115. \" for low resolution devices (crt and lpr)
116.if \n(.H>23 .if \n(.V>19 \
117\{\
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
127.\}
128.rm #[ #] #H #V #F C
129.\" ========================================================================
130.\"
131.IX Title "ASN1_generate_nconf 3"
132.TH ASN1_generate_nconf 3 "2005-07-06" "0.9.8" "OpenSSL"
133.SH "NAME"
134ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS"
137.Vb 2
138\& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
139\& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
140.Ve
141.SH "DESCRIPTION"
142.IX Header "DESCRIPTION"
143These functions generate the \s-1ASN1\s0 encoding of a string
144in an \fB\s-1ASN1_TYPE\s0\fR structure.
145.PP
146\&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
147the optional configuration information where additional strings
148will be read from. \fBnconf\fR will typically come from a config
149file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
150which will typically be used by X509 v3 certificate extension
151functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
152configuration will be used.
153.SH "GENERATION STRING FORMAT"
154.IX Header "GENERATION STRING FORMAT"
155The actual data encoded is determined by the string \fBstr\fR and
156the configuration information. The general format of the string
157is:
158.PP
159.Vb 1
160\& B<[modifier,]type[:value]>
161.Ve
162.PP
163That is zero or more comma separated modifiers followed by a type
164followed by an optional colon and a value. The formats of \fBtype\fR,
165\&\fBvalue\fR and \fBmodifier\fR are explained below.
166.Sh "\s-1SUPPORTED\s0 \s-1TYPES\s0"
167.IX Subsection "SUPPORTED TYPES"
168The supported types are listed below. Unless otherwise specified
169only the \fB\s-1ASCII\s0\fR format is permissible.
170.IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
171.IX Item "BOOLEAN, BOOL"
172This encodes a boolean type. The \fBvalue\fR string is mandatory and
173should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
174\&\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
175are acceptable.
176.IP "\fB\s-1NULL\s0\fR" 2
177.IX Item "NULL"
178Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
179.IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
180.IX Item "INTEGER, INT"
181Encodes an \s-1ASN1\s0 \fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
182the value of the integer, it can be preceeded by a minus sign and
183is normally interpreted as a decimal value unless the prefix \fB0x\fR
184is included.
185.IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
186.IX Item "ENUMERATED, ENUM"
187Encodes the \s-1ASN1\s0 \fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
188\&\fB\s-1INTEGER\s0\fR.
189.IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
190.IX Item "OBJECT, OID"
191Encodes an \s-1ASN1\s0 \fB\s-1OBJECT\s0 \s-1IDENTIFIER\s0\fR, the \fBvalue\fR string can be
192a short name, a long name or numerical format.
193.IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
194.IX Item "UTCTIME, UTC"
195Encodes an \s-1ASN1\s0 \fBUTCTime\fR structure, the value should be in
196the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
197.IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
198.IX Item "GENERALIZEDTIME, GENTIME"
199Encodes an \s-1ASN1\s0 \fBGeneralizedTime\fR structure, the value should be in
200the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
201.IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
202.IX Item "OCTETSTRING, OCT"
203Emcodes an \s-1ASN1\s0 \fB\s-1OCTET\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
204of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
205used to specify the format of \fBvalue\fR.
206.IP "\fB\s-1BITSRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
207.IX Item "BITSRING, BITSTR"
208Emcodes an \s-1ASN1\s0 \fB\s-1BIT\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
209of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
210can be used to specify the format of \fBvalue\fR.
211.Sp
212If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
213bits is set to zero.
214.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" 2
215.IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString"
216These encode the corresponding string types. \fBvalue\fR represents the
217contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
218.IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
219.IX Item "SEQUENCE, SEQ, SET"
220Formats the result as an \s-1ASN1\s0 \fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
221should be a section name which will contain the contents. The
222field names in the section are ignored and the values are in the
223generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
224will be encoded.
225.Sh "\s-1MODIFIERS\s0"
226.IX Subsection "MODIFIERS"
227Modifiers affect the following structure, they can be used to
228add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
229the string format of the final type and value. The supported
230formats are documented below.
231.IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
232.IX Item "EXPLICIT, EXP"
233Add an explicit tag to the following structure. This string
234should be followed by a colon and the tag value to use as a
235decimal value.
236.Sp
237By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL\s0,
238\&\s-1APPLICATION\s0, \s-1PRIVATE\s0 or \s-1CONTEXT\s0 \s-1SPECIFIC\s0 tagging can be used,
239the default is \s-1CONTEXT\s0 \s-1SPECIFIC\s0.
240.IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
241.IX Item "IMPLICIT, IMP"
242This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
243instead.
244.IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
245.IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
246The following structure is surrounded by an \s-1OCTET\s0 \s-1STRING\s0, a \s-1SEQUENCE\s0,
247a \s-1SET\s0 or a \s-1BIT\s0 \s-1STRING\s0 respectively. For a \s-1BIT\s0 \s-1STRING\s0 the number of unused
248bits is set to zero.
249.IP "\fB\s-1FORMAT\s0\fR" 2
250.IX Item "FORMAT"
251This specifies the format of the ultimate value. It should be followed
252by 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.
253.Sp
254If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is specified
255then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the output must
256be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT\s0 \s-1STRING\s0) is a
257comma separated list of set bits.
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
278A more complex example using a config file to produce a
279\&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
280.PP
281asn1 = SEQUENCE:seq_section
282.PP
283[seq_section]
284.PP
285field1 = \s-1BOOLEAN:TRUE\s0
286field2 = OID:commonName
287field3 = UTF8:Third field
288.PP
289This example produces an RSAPrivateKey structure, this is the
290key contained in the file client.pem in all OpenSSL distributions
291(note: the field names such as 'coeff' are ignored and are present just
292for clarity):
293.PP
294.Vb 3
295\& asn1=SEQUENCE:private_key
296\& [private_key]
297\& version=INTEGER:0
298.Ve
299.PP
300.Vb 2
301\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
302\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
303.Ve
304.PP
305.Vb 1
306\& e=INTEGER:0x010001
307.Ve
308.PP
309.Vb 2
310\& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
311\& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
312.Ve
313.PP
314.Vb 2
315\& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
316\& D4BD57
317.Ve
318.PP
319.Vb 2
320\& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
321\& 46EC4F
322.Ve
323.PP
324.Vb 2
325\& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
326\& 9C0A39B9
327.Ve
328.PP
329.Vb 2
330\& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
331\& E7B2458F
332.Ve
333.PP
334.Vb 2
335\& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
336\& 628657053A
337.Ve
338.PP
339This example is the corresponding public key in a SubjectPublicKeyInfo
340structure:
341.PP
342.Vb 2
343\& # Start with a SEQUENCE
344\& asn1=SEQUENCE:pubkeyinfo
345.Ve
346.PP
347.Vb 5
348\& # pubkeyinfo contains an algorithm identifier and the public key wrapped
349\& # in a BIT STRING
350\& [pubkeyinfo]
351\& algorithm=SEQUENCE:rsa_alg
352\& pubkey=BITWRAP,SEQUENCE:rsapubkey
353.Ve
354.PP
355.Vb 4
356\& # algorithm ID for RSA is just an OID and a NULL
357\& [rsa_alg]
358\& algorithm=OID:rsaEncryption
359\& parameter=NULL
360.Ve
361.PP
362.Vb 4
363\& # Actual public key: modulus and exponent
364\& [rsapubkey]
365\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
366\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
367.Ve
368.PP
369.Vb 1
370\& e=INTEGER:0x010001
371.Ve
372.SH "RETURN VALUES"
373.IX Header "RETURN VALUES"
374\&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
375data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
376.PP
377The error codes that can be obtained by \fIERR_get_error\fR\|(3).
378.SH "SEE ALSO"
379.IX Header "SEE ALSO"
380\&\fIERR_get_error\fR\|(3)
381.SH "HISTORY"
382.IX Header "HISTORY"
383\&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8