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(const char *str, CONF *nconf);
12 ASN1_TYPE *ASN1_generate_v3(const 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 whereas 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 4
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 4
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 prefaced 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 4
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 RETURN VALUES
166
167ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
168data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
169
170The error codes that can be obtained by L<ERR_get_error(3)>.
171
172=head1 EXAMPLES
173
174A simple IA5String:
175
176 IA5STRING:Hello World
177
178An IA5String explicitly tagged:
179
180 EXPLICIT:0,IA5STRING:Hello World
181
182An IA5String explicitly tagged using APPLICATION tagging:
183
184 EXPLICIT:0A,IA5STRING:Hello World
185
186A BITSTRING with bits 1 and 5 set and all others zero:
187
188 FORMAT:BITLIST,BITSTRING:1,5
189
190A more complex example using a config file to produce a
191SEQUENCE consisting of a BOOL an OID and a UTF8String:
192
193 asn1 = SEQUENCE:seq_section
194
195 [seq_section]
196
197 field1 = BOOLEAN:TRUE
198 field2 = OID:commonName
199 field3 = UTF8:Third field
200
201This example produces an RSAPrivateKey structure, this is the
202key contained in the file client.pem in all OpenSSL distributions
203(note: the field names such as 'coeff' are ignored and are present just
204for clarity):
205
206 asn1=SEQUENCE:private_key
207 [private_key]
208 version=INTEGER:0
209
210 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
211 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
212
213 e=INTEGER:0x010001
214
215 d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
216 F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
217
218 p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
219 D4BD57
220
221 q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
222 46EC4F
223
224 exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
225 9C0A39B9
226
227 exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
228 E7B2458F
229
230 coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
231 628657053A
232
233This example is the corresponding public key in a SubjectPublicKeyInfo
234structure:
235
236 # Start with a SEQUENCE
237 asn1=SEQUENCE:pubkeyinfo
238
239 # pubkeyinfo contains an algorithm identifier and the public key wrapped
240 # in a BIT STRING
241 [pubkeyinfo]
242 algorithm=SEQUENCE:rsa_alg
243 pubkey=BITWRAP,SEQUENCE:rsapubkey
244
245 # algorithm ID for RSA is just an OID and a NULL
246 [rsa_alg]
247 algorithm=OID:rsaEncryption
248 parameter=NULL
249
250 # Actual public key: modulus and exponent
251 [rsapubkey]
252 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
253 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
254
255 e=INTEGER:0x010001
256
257=head1 SEE ALSO
258
259L<ERR_get_error(3)>
260
261=head1 COPYRIGHT
262
263Copyright 2002-2019 The OpenSSL Project Authors. All Rights Reserved.
264
265Licensed under the OpenSSL license (the "License").  You may not use
266this file except in compliance with the License.  You can obtain a copy
267in the file LICENSE in the source distribution or at
268L<https://www.openssl.org/source/license.html>.
269
270=cut
271