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