1=pod
2
3=head1 NAME
4
5ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
6
7=head1 SYNOPSIS
8
9 ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
10 ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
11
12=head1 DESCRIPTION
13
14These functions generate the ASN1 encoding of a string
15in an B<ASN1_TYPE> structure.
16
17B<str> contains the string to encode B<nconf> or B<cnf> contains
18the optional configuration information where additional strings
19will be read from. B<nconf> will typically come from a config
20file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
21which will typically be used by X509 v3 certificate extension
22functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
23configuration will be used.
24
25=head1 GENERATION STRING FORMAT
26
27The actual data encoded is determined by the string B<str> and
28the configuration information. The general format of the string
29is:
30
31 B<[modifier,]type[:value]>
32
33That is zero or more comma separated modifiers followed by a type
34followed by an optional colon and a value. The formats of B<type>,
35B<value> and B<modifier> are explained below.
36
37=head2 SUPPORTED TYPES
38
39The supported types are listed below. Unless otherwise specified
40only the B<ASCII> format is permissible.
41
42=over 2
43
44=item B<BOOLEAN>, B<BOOL>
45
46This encodes a boolean type. The B<value> string is mandatory and
47should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
48B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
49are acceptable. 
50
51=item B<NULL>
52
53Encode the B<NULL> type, the B<value> string must not be present.
54
55=item B<INTEGER>, B<INT>
56
57Encodes an ASN1 B<INTEGER> type. The B<value> string represents
58the value of the integer, it can be preceeded by a minus sign and
59is normally interpreted as a decimal value unless the prefix B<0x>
60is included.
61
62=item B<ENUMERATED>, B<ENUM>
63
64Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
65B<INTEGER>.
66
67=item B<OBJECT>, B<OID>
68
69Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
70a short name, a long name or numerical format.
71
72=item B<UTCTIME>, B<UTC>
73
74Encodes an ASN1 B<UTCTime> structure, the value should be in
75the format B<YYMMDDHHMMSSZ>. 
76
77=item B<GENERALIZEDTIME>, B<GENTIME>
78
79Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
80the format B<YYYYMMDDHHMMSSZ>. 
81
82=item B<OCTETSTRING>, B<OCT>
83
84Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents
85of this structure, the format strings B<ASCII> and B<HEX> can be
86used to specify the format of B<value>.
87
88=item B<BITSRING>, B<BITSTR>
89
90Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents
91of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
92can be used to specify the format of B<value>.
93
94If the format is anything other than B<BITLIST> the number of unused
95bits is set to zero.
96
97=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
98B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
99B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
100B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>
101
102These encode the corresponding string types. B<value> represents the
103contents of this structure. The format can be B<ASCII> or B<UTF8>.
104
105=item B<SEQUENCE>, B<SEQ>, B<SET>
106
107Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
108should be a section name which will contain the contents. The
109field names in the section are ignored and the values are in the
110generated string format. If B<value> is absent then an empty SEQUENCE
111will be encoded.
112
113=back
114
115=head2 MODIFIERS
116
117Modifiers affect the following structure, they can be used to
118add EXPLICIT or IMPLICIT tagging, add wrappers or to change
119the string format of the final type and value. The supported
120formats are documented below.
121
122=over 2
123
124=item B<EXPLICIT>, B<EXP>
125
126Add an explicit tag to the following structure. This string
127should be followed by a colon and the tag value to use as a
128decimal value.
129
130By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL,
131APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
132the default is CONTEXT SPECIFIC.
133
134=item B<IMPLICIT>, B<IMP>
135
136This is the same as B<EXPLICIT> except IMPLICIT tagging is used
137instead.
138
139=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP>
140
141The following structure is surrounded by an OCTET STRING, a SEQUENCE,
142a SET or a BIT STRING respectively. For a BIT STRING the number of unused
143bits is set to zero.
144
145=item B<FORMAT>
146
147This specifies the format of the ultimate value. It should be followed
148by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
149
150If no format specifier is included then B<ASCII> is used. If B<UTF8> is specified
151then the value string must be a valid B<UTF8> string. For B<HEX> the output must
152be a set of hex digits. B<BITLIST> (which is only valid for a BIT STRING) is a
153comma separated list of set bits.
154
155=back
156
157=head1 EXAMPLES
158
159A simple IA5String:
160
161 IA5STRING:Hello World
162
163An IA5String explicitly tagged:
164
165 EXPLICIT:0,IA5STRING:Hello World
166
167An IA5String explicitly tagged using APPLICATION tagging:
168
169 EXPLICIT:0A,IA5STRING:Hello World
170
171A more complex example using a config file to produce a
172SEQUENCE consiting of a BOOL an OID and a UTF8String:
173
174asn1 = SEQUENCE:seq_section
175
176[seq_section]
177
178field1 = BOOLEAN:TRUE
179field2 = OID:commonName
180field3 = UTF8:Third field
181
182This example produces an RSAPrivateKey structure, this is the
183key contained in the file client.pem in all OpenSSL distributions
184(note: the field names such as 'coeff' are ignored and are present just
185for clarity):
186
187 asn1=SEQUENCE:private_key
188 [private_key]
189 version=INTEGER:0
190
191 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
192 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
193
194 e=INTEGER:0x010001
195
196 d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
197 F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
198
199 p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
200 D4BD57
201
202 q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
203 46EC4F
204
205 exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
206 9C0A39B9
207
208 exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
209 E7B2458F
210
211 coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
212 628657053A
213
214This example is the corresponding public key in a SubjectPublicKeyInfo
215structure:
216
217 # Start with a SEQUENCE
218 asn1=SEQUENCE:pubkeyinfo
219
220 # pubkeyinfo contains an algorithm identifier and the public key wrapped
221 # in a BIT STRING
222 [pubkeyinfo]
223 algorithm=SEQUENCE:rsa_alg
224 pubkey=BITWRAP,SEQUENCE:rsapubkey
225
226 # algorithm ID for RSA is just an OID and a NULL
227 [rsa_alg]
228 algorithm=OID:rsaEncryption
229 parameter=NULL
230
231 # Actual public key: modulus and exponent
232 [rsapubkey]
233 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
234 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
235
236 e=INTEGER:0x010001
237
238=head1 RETURN VALUES
239
240ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
241data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
242
243The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
244
245=head1 SEE ALSO
246
247L<ERR_get_error(3)|ERR_get_error(3)>
248
249=head1 HISTORY
250
251ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
252
253=cut
254