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