Update build for OpenSSL-0.9.8j upgrade.
[dragonfly.git] / secure / lib / libcrypto / man / ASN1_generate_nconf.3
CommitLineData
e257b235 1.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
a561f9ff
SS
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
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-
a561f9ff
SS
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.\"
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.\"
a561f9ff
SS
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 \{\
a561f9ff
SS
60. de IX
61. tm Index:\\$1\t\\n%\t"\\$2"
62..
63. nr % 0
64. rr F
65.\}
e257b235
PA
66.el \{\
67. de IX
68..
69.\}
aac4ff6f 70.\"
a561f9ff
SS
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
74.if n \{\
75. ds #H 0
76. ds #V .8m
77. ds #F .3m
78. ds #[ \f1
79. ds #] \fP
80.\}
81.if t \{\
82. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83. ds #V .6m
84. ds #F 0
85. ds #[ \&
86. ds #] \&
87.\}
88. \" simple accents for nroff and troff
89.if n \{\
90. ds ' \&
91. ds ` \&
92. ds ^ \&
93. ds , \&
94. ds ~ ~
95. ds /
96.\}
97.if t \{\
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'
104.\}
105. \" troff and (daisy-wheel) nroff accents
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
115. \" corrections for vroff
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'
118. \" for low resolution devices (crt and lpr)
119.if \n(.H>23 .if \n(.V>19 \
120\{\
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
130.\}
131.rm #[ #] #H #V #F C
132.\" ========================================================================
133.\"
134.IX Title "ASN1_generate_nconf 3"
e257b235
PA
135.TH ASN1_generate_nconf 3 "2009-01-11" "0.9.8j" "OpenSSL"
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
a561f9ff
SS
140.SH "NAME"
141ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
142.SH "SYNOPSIS"
143.IX Header "SYNOPSIS"
144.Vb 2
145\& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
146\& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
147.Ve
148.SH "DESCRIPTION"
149.IX Header "DESCRIPTION"
150These functions generate the \s-1ASN1\s0 encoding of a string
151in an \fB\s-1ASN1_TYPE\s0\fR structure.
152.PP
153\&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
154the optional configuration information where additional strings
155will be read from. \fBnconf\fR will typically come from a config
156file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
157which will typically be used by X509 v3 certificate extension
158functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
159configuration will be used.
160.SH "GENERATION STRING FORMAT"
161.IX Header "GENERATION STRING FORMAT"
162The actual data encoded is determined by the string \fBstr\fR and
163the configuration information. The general format of the string
164is:
aac4ff6f
PA
165.IP "\fB[modifier,]type[:value]\fR" 2
166.IX Item "[modifier,]type[:value]"
a561f9ff
SS
167.PP
168That is zero or more comma separated modifiers followed by a type
169followed by an optional colon and a value. The formats of \fBtype\fR,
170\&\fBvalue\fR and \fBmodifier\fR are explained below.
171.Sh "\s-1SUPPORTED\s0 \s-1TYPES\s0"
172.IX Subsection "SUPPORTED TYPES"
173The supported types are listed below. Unless otherwise specified
174only the \fB\s-1ASCII\s0\fR format is permissible.
175.IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
176.IX Item "BOOLEAN, BOOL"
177This encodes a boolean type. The \fBvalue\fR string is mandatory and
178should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
179\&\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 180are acceptable.
a561f9ff
SS
181.IP "\fB\s-1NULL\s0\fR" 2
182.IX Item "NULL"
183Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
184.IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
185.IX Item "INTEGER, INT"
186Encodes an \s-1ASN1\s0 \fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
187the value of the integer, it can be preceeded by a minus sign and
188is normally interpreted as a decimal value unless the prefix \fB0x\fR
189is included.
190.IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
191.IX Item "ENUMERATED, ENUM"
192Encodes the \s-1ASN1\s0 \fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
193\&\fB\s-1INTEGER\s0\fR.
194.IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
195.IX Item "OBJECT, OID"
196Encodes an \s-1ASN1\s0 \fB\s-1OBJECT\s0 \s-1IDENTIFIER\s0\fR, the \fBvalue\fR string can be
197a short name, a long name or numerical format.
198.IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
199.IX Item "UTCTIME, UTC"
200Encodes an \s-1ASN1\s0 \fBUTCTime\fR structure, the value should be in
e257b235 201the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
a561f9ff
SS
202.IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
203.IX Item "GENERALIZEDTIME, GENTIME"
204Encodes an \s-1ASN1\s0 \fBGeneralizedTime\fR structure, the value should be in
e257b235 205the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
a561f9ff
SS
206.IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
207.IX Item "OCTETSTRING, OCT"
aac4ff6f 208Encodes an \s-1ASN1\s0 \fB\s-1OCTET\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
a561f9ff
SS
209of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
210used to specify the format of \fBvalue\fR.
aac4ff6f
PA
211.IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
212.IX Item "BITSTRING, BITSTR"
213Encodes an \s-1ASN1\s0 \fB\s-1BIT\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
a561f9ff
SS
214of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
215can be used to specify the format of \fBvalue\fR.
216.Sp
217If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
218bits is set to zero.
219.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
220.IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString"
221These encode the corresponding string types. \fBvalue\fR represents the
222contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
223.IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
224.IX Item "SEQUENCE, SEQ, SET"
225Formats the result as an \s-1ASN1\s0 \fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
226should be a section name which will contain the contents. The
227field names in the section are ignored and the values are in the
228generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
229will be encoded.
230.Sh "\s-1MODIFIERS\s0"
231.IX Subsection "MODIFIERS"
232Modifiers affect the following structure, they can be used to
233add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
234the string format of the final type and value. The supported
235formats are documented below.
236.IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
237.IX Item "EXPLICIT, EXP"
238Add an explicit tag to the following structure. This string
239should be followed by a colon and the tag value to use as a
240decimal value.
241.Sp
242By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL\s0,
243\&\s-1APPLICATION\s0, \s-1PRIVATE\s0 or \s-1CONTEXT\s0 \s-1SPECIFIC\s0 tagging can be used,
244the default is \s-1CONTEXT\s0 \s-1SPECIFIC\s0.
245.IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
246.IX Item "IMPLICIT, IMP"
247This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
248instead.
249.IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
250.IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
251The following structure is surrounded by an \s-1OCTET\s0 \s-1STRING\s0, a \s-1SEQUENCE\s0,
252a \s-1SET\s0 or a \s-1BIT\s0 \s-1STRING\s0 respectively. For a \s-1BIT\s0 \s-1STRING\s0 the number of unused
253bits is set to zero.
254.IP "\fB\s-1FORMAT\s0\fR" 2
255.IX Item "FORMAT"
256This specifies the format of the ultimate value. It should be followed
257by 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.
258.Sp
aac4ff6f
PA
259If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
260specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
261output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT\s0
262\&\s-1STRING\s0) is a comma separated list of the indices of the set bits, all other
263bits are zero.
a561f9ff
SS
264.SH "EXAMPLES"
265.IX Header "EXAMPLES"
266A simple IA5String:
267.PP
268.Vb 1
269\& IA5STRING:Hello World
270.Ve
271.PP
272An IA5String explicitly tagged:
273.PP
274.Vb 1
275\& EXPLICIT:0,IA5STRING:Hello World
276.Ve
277.PP
278An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
279.PP
280.Vb 1
281\& EXPLICIT:0A,IA5STRING:Hello World
282.Ve
283.PP
aac4ff6f
PA
284A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
285.PP
286.Vb 1
287\& FORMAT=BITLIST,BITSTRING:1,5
288.Ve
289.PP
a561f9ff
SS
290A more complex example using a config file to produce a
291\&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
292.PP
aac4ff6f
PA
293.Vb 1
294\& asn1 = SEQUENCE:seq_section
e257b235 295\&
aac4ff6f 296\& [seq_section]
e257b235 297\&
aac4ff6f
PA
298\& field1 = BOOLEAN:TRUE
299\& field2 = OID:commonName
300\& field3 = UTF8:Third field
301.Ve
a561f9ff
SS
302.PP
303This example produces an RSAPrivateKey structure, this is the
304key contained in the file client.pem in all OpenSSL distributions
305(note: the field names such as 'coeff' are ignored and are present just
306for clarity):
307.PP
308.Vb 3
309\& asn1=SEQUENCE:private_key
310\& [private_key]
311\& version=INTEGER:0
e257b235 312\&
a561f9ff
SS
313\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
314\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
e257b235 315\&
a561f9ff 316\& e=INTEGER:0x010001
e257b235 317\&
a561f9ff
SS
318\& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
319\& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
e257b235 320\&
a561f9ff
SS
321\& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
322\& D4BD57
e257b235 323\&
a561f9ff
SS
324\& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
325\& 46EC4F
e257b235 326\&
a561f9ff
SS
327\& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
328\& 9C0A39B9
e257b235 329\&
a561f9ff
SS
330\& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
331\& E7B2458F
e257b235 332\&
a561f9ff
SS
333\& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
334\& 628657053A
335.Ve
336.PP
337This example is the corresponding public key in a SubjectPublicKeyInfo
338structure:
339.PP
340.Vb 2
341\& # Start with a SEQUENCE
342\& asn1=SEQUENCE:pubkeyinfo
e257b235 343\&
a561f9ff
SS
344\& # pubkeyinfo contains an algorithm identifier and the public key wrapped
345\& # in a BIT STRING
346\& [pubkeyinfo]
347\& algorithm=SEQUENCE:rsa_alg
348\& pubkey=BITWRAP,SEQUENCE:rsapubkey
e257b235 349\&
a561f9ff
SS
350\& # algorithm ID for RSA is just an OID and a NULL
351\& [rsa_alg]
352\& algorithm=OID:rsaEncryption
353\& parameter=NULL
e257b235 354\&
a561f9ff
SS
355\& # Actual public key: modulus and exponent
356\& [rsapubkey]
357\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
358\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
e257b235 359\&
a561f9ff
SS
360\& e=INTEGER:0x010001
361.Ve
362.SH "RETURN VALUES"
363.IX Header "RETURN VALUES"
364\&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
365data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
366.PP
367The error codes that can be obtained by \fIERR_get_error\fR\|(3).
368.SH "SEE ALSO"
369.IX Header "SEE ALSO"
370\&\fIERR_get_error\fR\|(3)
371.SH "HISTORY"
372.IX Header "HISTORY"
373\&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8