]>
Commit | Line | Data |
---|---|---|
ba36b61d DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
c264592d UM |
9 | #include <openssl/asn1.h> |
10 | ||
009951d2 | 11 | ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf); |
12eaf3b8 | 12 | ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf); |
ba36b61d DSH |
13 | |
14 | =head1 DESCRIPTION | |
15 | ||
16 | These functions generate the ASN1 encoding of a string | |
17 | in an B<ASN1_TYPE> structure. | |
18 | ||
19 | B<str> contains the string to encode B<nconf> or B<cnf> contains | |
20 | the optional configuration information where additional strings | |
21 | will be read from. B<nconf> will typically come from a config | |
186bb907 | 22 | file whereas B<cnf> is obtained from an B<X509V3_CTX> structure |
ba36b61d DSH |
23 | which will typically be used by X509 v3 certificate extension |
24 | functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional | |
25 | configuration will be used. | |
26 | ||
27 | =head1 GENERATION STRING FORMAT | |
28 | ||
29 | The actual data encoded is determined by the string B<str> and | |
30 | the configuration information. The general format of the string | |
31 | is: | |
32 | ||
e1271ac2 | 33 | =over 4 |
15bd07e9 BM |
34 | |
35 | =item B<[modifier,]type[:value]> | |
36 | ||
37 | =back | |
ba36b61d DSH |
38 | |
39 | That is zero or more comma separated modifiers followed by a type | |
40 | followed by an optional colon and a value. The formats of B<type>, | |
d78254aa | 41 | B<value> and B<modifier> are explained below. |
ba36b61d | 42 | |
05ea606a | 43 | =head2 Supported Types |
ba36b61d | 44 | |
137e7e3a DSH |
45 | The supported types are listed below. Unless otherwise specified |
46 | only the B<ASCII> format is permissible. | |
47 | ||
e1271ac2 | 48 | =over 4 |
ba36b61d DSH |
49 | |
50 | =item B<BOOLEAN>, B<BOOL> | |
51 | ||
52 | This encodes a boolean type. The B<value> string is mandatory and | |
53 | should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>, | |
d78254aa | 54 | B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no> |
1bc74519 | 55 | are acceptable. |
ba36b61d DSH |
56 | |
57 | =item B<NULL> | |
58 | ||
59 | Encode the B<NULL> type, the B<value> string must not be present. | |
60 | ||
61 | =item B<INTEGER>, B<INT> | |
62 | ||
63 | Encodes an ASN1 B<INTEGER> type. The B<value> string represents | |
fc1d88f0 | 64 | the value of the integer, it can be prefaced by a minus sign and |
ba36b61d DSH |
65 | is normally interpreted as a decimal value unless the prefix B<0x> |
66 | is included. | |
67 | ||
68 | =item B<ENUMERATED>, B<ENUM> | |
69 | ||
70 | Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to | |
71 | B<INTEGER>. | |
72 | ||
73 | =item B<OBJECT>, B<OID> | |
74 | ||
75 | Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be | |
76 | a short name, a long name or numerical format. | |
77 | ||
78 | =item B<UTCTIME>, B<UTC> | |
79 | ||
80 | Encodes an ASN1 B<UTCTime> structure, the value should be in | |
1bc74519 | 81 | the format B<YYMMDDHHMMSSZ>. |
ba36b61d | 82 | |
2d780dfd | 83 | =item B<GENERALIZEDTIME>, B<GENTIME> |
ba36b61d | 84 | |
2d780dfd | 85 | Encodes an ASN1 B<GeneralizedTime> structure, the value should be in |
1bc74519 | 86 | the format B<YYYYMMDDHHMMSSZ>. |
ba36b61d DSH |
87 | |
88 | =item B<OCTETSTRING>, B<OCT> | |
89 | ||
15bd07e9 | 90 | Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents |
ba36b61d DSH |
91 | of this structure, the format strings B<ASCII> and B<HEX> can be |
92 | used to specify the format of B<value>. | |
93 | ||
15bd07e9 | 94 | =item B<BITSTRING>, B<BITSTR> |
ba36b61d | 95 | |
15bd07e9 | 96 | Encodes an ASN1 B<BIT STRING>. B<value> represents the contents |
ba36b61d DSH |
97 | of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST> |
98 | can be used to specify the format of B<value>. | |
99 | ||
100 | If the format is anything other than B<BITLIST> the number of unused | |
101 | bits is set to zero. | |
102 | ||
103 | =item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>, | |
104 | B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>, | |
105 | B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>, | |
802d7fa6 NL |
106 | B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>, |
107 | B<NUMERIC> | |
ba36b61d DSH |
108 | |
109 | These encode the corresponding string types. B<value> represents the | |
110 | contents of this structure. The format can be B<ASCII> or B<UTF8>. | |
111 | ||
112 | =item B<SEQUENCE>, B<SEQ>, B<SET> | |
113 | ||
114 | Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value> | |
115 | should be a section name which will contain the contents. The | |
d78254aa DSH |
116 | field names in the section are ignored and the values are in the |
117 | generated string format. If B<value> is absent then an empty SEQUENCE | |
118 | will be encoded. | |
ba36b61d | 119 | |
56dc24d4 | 120 | =back |
ba36b61d | 121 | |
05ea606a | 122 | =head2 Modifiers |
ba36b61d | 123 | |
137e7e3a DSH |
124 | Modifiers affect the following structure, they can be used to |
125 | add EXPLICIT or IMPLICIT tagging, add wrappers or to change | |
126 | the string format of the final type and value. The supported | |
127 | formats are documented below. | |
128 | ||
e1271ac2 | 129 | =over 4 |
137e7e3a DSH |
130 | |
131 | =item B<EXPLICIT>, B<EXP> | |
132 | ||
133 | Add an explicit tag to the following structure. This string | |
134 | should be followed by a colon and the tag value to use as a | |
135 | decimal value. | |
136 | ||
137 | By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL, | |
138 | APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used, | |
139 | the default is CONTEXT SPECIFIC. | |
140 | ||
141 | =item B<IMPLICIT>, B<IMP> | |
142 | ||
143 | This is the same as B<EXPLICIT> except IMPLICIT tagging is used | |
144 | instead. | |
145 | ||
d78254aa | 146 | =item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP> |
137e7e3a | 147 | |
d78254aa DSH |
148 | The following structure is surrounded by an OCTET STRING, a SEQUENCE, |
149 | a SET or a BIT STRING respectively. For a BIT STRING the number of unused | |
137e7e3a DSH |
150 | bits is set to zero. |
151 | ||
152 | =item B<FORMAT> | |
153 | ||
154 | This specifies the format of the ultimate value. It should be followed | |
155 | by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>. | |
156 | ||
3b979c54 DSH |
157 | If no format specifier is included then B<ASCII> is used. If B<UTF8> is |
158 | specified then the value string must be a valid B<UTF8> string. For B<HEX> the | |
159 | output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT | |
160 | STRING) is a comma separated list of the indices of the set bits, all other | |
161 | bits are zero. | |
137e7e3a | 162 | |
56dc24d4 | 163 | =back |
137e7e3a DSH |
164 | |
165 | =head1 EXAMPLES | |
166 | ||
167 | A simple IA5String: | |
168 | ||
169 | IA5STRING:Hello World | |
170 | ||
171 | An IA5String explicitly tagged: | |
172 | ||
173 | EXPLICIT:0,IA5STRING:Hello World | |
174 | ||
175 | An IA5String explicitly tagged using APPLICATION tagging: | |
176 | ||
177 | EXPLICIT:0A,IA5STRING:Hello World | |
178 | ||
3b979c54 DSH |
179 | A BITSTRING with bits 1 and 5 set and all others zero: |
180 | ||
c2f0203d | 181 | FORMAT:BITLIST,BITSTRING:1,5 |
3b979c54 | 182 | |
137e7e3a | 183 | A more complex example using a config file to produce a |
186bb907 | 184 | SEQUENCE consisting of a BOOL an OID and a UTF8String: |
137e7e3a | 185 | |
15bd07e9 | 186 | asn1 = SEQUENCE:seq_section |
137e7e3a | 187 | |
15bd07e9 | 188 | [seq_section] |
137e7e3a | 189 | |
15bd07e9 BM |
190 | field1 = BOOLEAN:TRUE |
191 | field2 = OID:commonName | |
192 | field3 = UTF8:Third field | |
137e7e3a DSH |
193 | |
194 | This example produces an RSAPrivateKey structure, this is the | |
195 | key contained in the file client.pem in all OpenSSL distributions | |
196 | (note: the field names such as 'coeff' are ignored and are present just | |
197 | for 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 | ||
226 | This example is the corresponding public key in a SubjectPublicKeyInfo | |
227 | structure: | |
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 | |
ba36b61d DSH |
249 | |
250 | =head1 RETURN VALUES | |
251 | ||
252 | ASN1_generate_nconf() and ASN1_generate_v3() return the encoded | |
253 | data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred. | |
254 | ||
9b86974e | 255 | The error codes that can be obtained by L<ERR_get_error(3)>. |
ba36b61d | 256 | |
ba36b61d DSH |
257 | =head1 SEE ALSO |
258 | ||
9b86974e | 259 | L<ERR_get_error(3)> |
ba36b61d | 260 | |
e2f92610 RS |
261 | =head1 COPYRIGHT |
262 | ||
263 | Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. | |
264 | ||
265 | Licensed under the OpenSSL license (the "License"). You may not use | |
266 | this file except in compliance with the License. You can obtain a copy | |
267 | in the file LICENSE in the source distribution or at | |
268 | L<https://www.openssl.org/source/license.html>. | |
269 | ||
270 | =cut |