ASN1_generate_nconf.pod revision 279265 
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 preceded 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>, B<NUMERICSTRING>,
107B<NUMERIC>
108
109These encode the corresponding string types. B<value> represents the
110contents of this structure. The format can be B<ASCII> or B<UTF8>.
111
112=item B<SEQUENCE>, B<SEQ>, B<SET>
113
114Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
115should be a section name which will contain the contents. The
116field names in the section are ignored and the values are in the
117generated string format. If B<value> is absent then an empty SEQUENCE
118will be encoded.
119
120=back
121
122=head2 MODIFIERS
123
124Modifiers affect the following structure, they can be used to
125add EXPLICIT or IMPLICIT tagging, add wrappers or to change
126the string format of the final type and value. The supported
127formats are documented below.
128
129=over 2
130
131=item B<EXPLICIT>, B<EXP>
132
133Add an explicit tag to the following structure. This string
134should be followed by a colon and the tag value to use as a
135decimal value.
136
137By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL,
138APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
139the default is CONTEXT SPECIFIC.
140
141=item B<IMPLICIT>, B<IMP>
142
143This is the same as B<EXPLICIT> except IMPLICIT tagging is used
144instead.
145
146=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP>
147
148The following structure is surrounded by an OCTET STRING, a SEQUENCE,
149a SET or a BIT STRING respectively. For a BIT STRING the number of unused
150bits is set to zero.
151
152=item B<FORMAT>
153
154This specifies the format of the ultimate value. It should be followed
155by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
156
157If no format specifier is included then B<ASCII> is used. If B<UTF8> is
158specified then the value string must be a valid B<UTF8> string. For B<HEX> the
159output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT
160STRING) is a comma separated list of the indices of the set bits, all other
161bits are zero.
162
163=back
164
165=head1 EXAMPLES
166
167A simple IA5String:
168
169 IA5STRING:Hello World
170
171An IA5String explicitly tagged:
172
173 EXPLICIT:0,IA5STRING:Hello World
174
175An IA5String explicitly tagged using APPLICATION tagging:
176
177 EXPLICIT:0A,IA5STRING:Hello World
178
179A BITSTRING with bits 1 and 5 set and all others zero:
180
181 FORMAT:BITLIST,BITSTRING:1,5
182
183A more complex example using a config file to produce a
184SEQUENCE consiting of a BOOL an OID and a UTF8String:
185
186 asn1 = SEQUENCE:seq_section
187
188 [seq_section]
189
190 field1 = BOOLEAN:TRUE
191 field2 = OID:commonName
192 field3 = UTF8:Third field
193
194This example produces an RSAPrivateKey structure, this is the
195key contained in the file client.pem in all OpenSSL distributions
196(note: the field names such as 'coeff' are ignored and are present just
197for clarity):
198
199 asn1=SEQUENCE:private_key
200 [private_key]
201 version=INTEGER:0
202
203 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
204 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
205
206 e=INTEGER:0x010001
207
208 d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
209 F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
210
211 p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
212 D4BD57
213
214 q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
215 46EC4F
216
217 exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
218 9C0A39B9
219
220 exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
221 E7B2458F
222
223 coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
224 628657053A
225
226This example is the corresponding public key in a SubjectPublicKeyInfo
227structure:
228
229 # Start with a SEQUENCE
230 asn1=SEQUENCE:pubkeyinfo
231
232 # pubkeyinfo contains an algorithm identifier and the public key wrapped
233 # in a BIT STRING
234 [pubkeyinfo]
235 algorithm=SEQUENCE:rsa_alg
236 pubkey=BITWRAP,SEQUENCE:rsapubkey
237
238 # algorithm ID for RSA is just an OID and a NULL
239 [rsa_alg]
240 algorithm=OID:rsaEncryption
241 parameter=NULL
242
243 # Actual public key: modulus and exponent
244 [rsapubkey]
245 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
246 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
247
248 e=INTEGER:0x010001
249
250=head1 RETURN VALUES
251
252ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
253data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
254
255The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
256
257=head1 SEE ALSO
258
259L<ERR_get_error(3)|ERR_get_error(3)>
260
261=head1 HISTORY
262
263ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
264
265=cut
266