1ASN1_GENERATE_NCONF(3ossl) OpenSSL ASN1_GENERATE_NCONF(3ossl)
2
6 ASN1_generate_nconf, ASN1_generate_v3 - ASN1 string generation
7 functions
8
10 #include <openssl/asn1.h>
11 ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
13 ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
14
16 These functions generate the ASN1 encoding of a string in an ASN1_TYPE
17 structure.
18 str contains the string to encode. nconf or cnf contains the optional
20 configuration information where additional strings will be read from.
21 nconf will typically come from a config file whereas cnf is obtained
22 from an X509V3_CTX structure, which will typically be used by X509 v3
23 certificate extension functions. cnf or nconf can be set to NULL if no
24 additional configuration will be used.
25
27 The actual data encoded is determined by the string str and the
28 configuration information. The general format of the string is:
29 [modifier,]type[:value]
31 That is zero or more comma separated modifiers followed by a type
33 followed by an optional colon and a value. The formats of type, value
34 and modifier are explained below.
35 Supported Types
37 The supported types are listed below. Case is not significant in the
38 type names. Unless otherwise specified only the ASCII format is
39 permissible.
40 BOOLEAN, BOOL
42 This encodes a boolean type. The value string is mandatory and
43 should be TRUE or FALSE. Additionally TRUE, true, Y, y, YES, yes,
44 FALSE, false, N, n, NO and no are acceptable.
45 NULL
47 Encode the NULL type, the value string must not be present.
48 INTEGER, INT
50 Encodes an ASN1 INTEGER type. The value string represents the value
51 of the integer, it can be prefaced by a minus sign and is normally
52 interpreted as a decimal value unless the prefix 0x is included.
53 ENUMERATED, ENUM
55 Encodes the ASN1 ENUMERATED type, it is otherwise identical to
56 INTEGER.
57 OBJECT, OID
59 Encodes an ASN1 OBJECT IDENTIFIER, the value string can be a short
60 name, a long name or numerical format.
61 UTCTIME, UTC
63 Encodes an ASN1 UTCTime structure, the value should be in the
64 format YYMMDDHHMMSSZ.
65 GENERALIZEDTIME, GENTIME
67 Encodes an ASN1 GeneralizedTime structure, the value should be in
68 the format YYYYMMDDHHMMSSZ.
69 OCTETSTRING, OCT
71 Encodes an ASN1 OCTET STRING. value represents the contents of this
72 structure, the format strings ASCII and HEX can be used to specify
73 the format of value.
74 BITSTRING, BITSTR
76 Encodes an ASN1 BIT STRING. value represents the contents of this
77 structure, the format strings ASCII, HEX and BITLIST can be used to
78 specify the format of value.
79 If the format is anything other than BITLIST the number of unused
81 bits is set to zero.
82 UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP,
84 BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61,
85 T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC
86 These encode the corresponding string types. value represents the
87 contents of this structure. The format can be ASCII or UTF8.
88 SEQUENCE, SEQ, SET
90 Formats the result as an ASN1 SEQUENCE or SET type. value should be
91 a section name which will contain the contents. The field names in
92 the section are ignored and the values are in the generated string
93 format. If value is absent then an empty SEQUENCE will be encoded.
94 Modifiers
96 Modifiers affect the following structure, they can be used to add
97 EXPLICIT or IMPLICIT tagging, add wrappers or to change the string
98 format of the final type and value. The supported formats are
99 documented below.
100 EXPLICIT, EXP
102 Add an explicit tag to the following structure. This string should
103 be followed by a colon and the tag value to use as a decimal value.
104 By following the number with U, A, P or C UNIVERSAL, APPLICATION,
106 PRIVATE or CONTEXT SPECIFIC tagging can be used, the default is
107 CONTEXT SPECIFIC.
108 IMPLICIT, IMP
110 This is the same as EXPLICIT except IMPLICIT tagging is used
111 instead.
112 OCTWRAP, SEQWRAP, SETWRAP, BITWRAP
114 The following structure is surrounded by an OCTET STRING, a
115 SEQUENCE, a SET or a BIT STRING respectively. For a BIT STRING the
116 number of unused bits is set to zero.
117 FORMAT
119 This specifies the format of the ultimate value. It should be
120 followed by a colon and one of the strings ASCII, UTF8, HEX or
121 BITLIST.
122 If no format specifier is included then ASCII is used. If UTF8 is
124 specified then the value string must be a valid UTF8 string. For
125 HEX the output must be a set of hex digits. BITLIST (which is only
126 valid for a BIT STRING) is a comma separated list of the indices of
127 the set bits, all other bits are zero.
128
130 ASN1_generate_nconf() and ASN1_generate_v3() return the encoded data as
131 an ASN1_TYPE structure or NULL if an error occurred.
132 The error codes that can be obtained by ERR_get_error(3).
134
136 A simple IA5String:
137 IA5STRING:Hello World
139 An IA5String explicitly tagged:
141 EXPLICIT:0,IA5STRING:Hello World
143 An IA5String explicitly tagged using APPLICATION tagging:
145 EXPLICIT:0A,IA5STRING:Hello World
147 A BITSTRING with bits 1 and 5 set and all others zero:
149 FORMAT:BITLIST,BITSTRING:1,5
151 A more complex example using a config file to produce a SEQUENCE
153 consisting of a BOOL an OID and a UTF8String:
154 asn1 = SEQUENCE:seq_section
156 [seq_section]
158 field1 = BOOLEAN:TRUE
160 field2 = OID:commonName
161 field3 = UTF8:Third field
162 This example produces an RSAPrivateKey structure, this is the key
164 contained in the file client.pem in all OpenSSL distributions (note:
165 the field names such as 'coeff' are ignored and are present just for
166 clarity):
167 asn1=SEQUENCE:private_key
169 [private_key]
170 version=INTEGER:0
171 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
173 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
174 e=INTEGER:0x010001
176 d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
178 F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
179 p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
181 D4BD57
182 q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
184 46EC4F
185 exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
187 9C0A39B9
188 exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
190 E7B2458F
191 coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
193 628657053A
194 This example is the corresponding public key in a SubjectPublicKeyInfo
196 structure:
197 # Start with a SEQUENCE
199 asn1=SEQUENCE:pubkeyinfo
200 # pubkeyinfo contains an algorithm identifier and the public key wrapped
202 # in a BIT STRING
203 [pubkeyinfo]
204 algorithm=SEQUENCE:rsa_alg
205 pubkey=BITWRAP,SEQUENCE:rsapubkey
206 # algorithm ID for RSA is just an OID and a NULL
208 [rsa_alg]
209 algorithm=OID:rsaEncryption
210 parameter=NULL
211 # Actual public key: modulus and exponent
213 [rsapubkey]
214 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
215 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
216 e=INTEGER:0x010001
218
220 ERR_get_error(3)
221
223 Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.
224 Licensed under the Apache License 2.0 (the "License"). You may not use
226 this file except in compliance with the License. You can obtain a copy
227 in the file LICENSE in the source distribution or at
228 <https://www.openssl.org/source/license.html>.
2293.1.1 2023-08-31 ASN1_GENERATE_NCONF(3ossl)