1ASN1_GENERATE_NCONF(3)              OpenSSL             ASN1_GENERATE_NCONF(3)
2
3
4

NAME

6       ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
7

SYNOPSIS

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

DESCRIPTION

15       These functions generate the ASN1 encoding of a string in an ASN1_TYPE
16       structure.
17
18       str contains the string to encode nconf or cnf contains the optional
19       configuration information where additional strings will be read from.
20       nconf will typically come from a config file whereas cnf is obtained
21       from an X509V3_CTX structure which will typically be used by X509 v3
22       certificate extension functions. cnf or nconf can be set to NULL if no
23       additional configuration will be used.
24

GENERATION STRING FORMAT

26       The actual data encoded is determined by the string str and the
27       configuration information. The general format of the string is:
28
29       [modifier,]type[:value]
30
31       That is zero or more comma separated modifiers followed by a type
32       followed by an optional colon and a value. The formats of type, value
33       and modifier are explained below.
34
35   Supported Types
36       The supported types are listed below. Unless otherwise specified only
37       the ASCII format is permissible.
38
39       BOOLEAN, BOOL
40           This encodes a boolean type. The value string is mandatory and
41           should be TRUE or FALSE. Additionally TRUE, true, Y, y, YES, yes,
42           FALSE, false, N, n, NO and no are acceptable.
43
44       NULL
45           Encode the NULL type, the value string must not be present.
46
47       INTEGER, INT
48           Encodes an ASN1 INTEGER type. The value string represents the value
49           of the integer, it can be prefaced by a minus sign and is normally
50           interpreted as a decimal value unless the prefix 0x is included.
51
52       ENUMERATED, ENUM
53           Encodes the ASN1 ENUMERATED type, it is otherwise identical to
54           INTEGER.
55
56       OBJECT, OID
57           Encodes an ASN1 OBJECT IDENTIFIER, the value string can be a short
58           name, a long name or numerical format.
59
60       UTCTIME, UTC
61           Encodes an ASN1 UTCTime structure, the value should be in the
62           format YYMMDDHHMMSSZ.
63
64       GENERALIZEDTIME, GENTIME
65           Encodes an ASN1 GeneralizedTime structure, the value should be in
66           the format YYYYMMDDHHMMSSZ.
67
68       OCTETSTRING, OCT
69           Encodes an ASN1 OCTET STRING. value represents the contents of this
70           structure, the format strings ASCII and HEX can be used to specify
71           the format of value.
72
73       BITSTRING, BITSTR
74           Encodes an ASN1 BIT STRING. value represents the contents of this
75           structure, the format strings ASCII, HEX and BITLIST can be used to
76           specify the format of value.
77
78           If the format is anything other than BITLIST the number of unused
79           bits is set to zero.
80
81       UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP,
82       BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61,
83       T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC
84           These encode the corresponding string types. value represents the
85           contents of this structure. The format can be ASCII or UTF8.
86
87       SEQUENCE, SEQ, SET
88           Formats the result as an ASN1 SEQUENCE or SET type. value should be
89           a section name which will contain the contents. The field names in
90           the section are ignored and the values are in the generated string
91           format. If value is absent then an empty SEQUENCE will be encoded.
92
93   Modifiers
94       Modifiers affect the following structure, they can be used to add
95       EXPLICIT or IMPLICIT tagging, add wrappers or to change the string
96       format of the final type and value. The supported formats are
97       documented below.
98
99       EXPLICIT, EXP
100           Add an explicit tag to the following structure. This string should
101           be followed by a colon and the tag value to use as a decimal value.
102
103           By following the number with U, A, P or C UNIVERSAL, APPLICATION,
104           PRIVATE or CONTEXT SPECIFIC tagging can be used, the default is
105           CONTEXT SPECIFIC.
106
107       IMPLICIT, IMP
108           This is the same as EXPLICIT except IMPLICIT tagging is used
109           instead.
110
111       OCTWRAP, SEQWRAP, SETWRAP, BITWRAP
112           The following structure is surrounded by an OCTET STRING, a
113           SEQUENCE, a SET or a BIT STRING respectively. For a BIT STRING the
114           number of unused bits is set to zero.
115
116       FORMAT
117           This specifies the format of the ultimate value. It should be
118           followed by a colon and one of the strings ASCII, UTF8, HEX or
119           BITLIST.
120
121           If no format specifier is included then ASCII is used. If UTF8 is
122           specified then the value string must be a valid UTF8 string. For
123           HEX the output must be a set of hex digits. BITLIST (which is only
124           valid for a BIT STRING) is a comma separated list of the indices of
125           the set bits, all other bits are zero.
126

RETURN VALUES

128       ASN1_generate_nconf() and ASN1_generate_v3() return the encoded data as
129       an ASN1_TYPE structure or NULL if an error occurred.
130
131       The error codes that can be obtained by ERR_get_error(3).
132

EXAMPLES

134       A simple IA5String:
135
136        IA5STRING:Hello World
137
138       An IA5String explicitly tagged:
139
140        EXPLICIT:0,IA5STRING:Hello World
141
142       An IA5String explicitly tagged using APPLICATION tagging:
143
144        EXPLICIT:0A,IA5STRING:Hello World
145
146       A BITSTRING with bits 1 and 5 set and all others zero:
147
148        FORMAT:BITLIST,BITSTRING:1,5
149
150       A more complex example using a config file to produce a SEQUENCE
151       consisting of a BOOL an OID and a UTF8String:
152
153        asn1 = SEQUENCE:seq_section
154
155        [seq_section]
156
157        field1 = BOOLEAN:TRUE
158        field2 = OID:commonName
159        field3 = UTF8:Third field
160
161       This example produces an RSAPrivateKey structure, this is the key
162       contained in the file client.pem in all OpenSSL distributions (note:
163       the field names such as 'coeff' are ignored and are present just for
164       clarity):
165
166        asn1=SEQUENCE:private_key
167        [private_key]
168        version=INTEGER:0
169
170        n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
171        D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
172
173        e=INTEGER:0x010001
174
175        d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
176        F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
177
178        p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
179        D4BD57
180
181        q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
182        46EC4F
183
184        exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
185        9C0A39B9
186
187        exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
188        E7B2458F
189
190        coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
191        628657053A
192
193       This example is the corresponding public key in a SubjectPublicKeyInfo
194       structure:
195
196        # Start with a SEQUENCE
197        asn1=SEQUENCE:pubkeyinfo
198
199        # pubkeyinfo contains an algorithm identifier and the public key wrapped
200        # in a BIT STRING
201        [pubkeyinfo]
202        algorithm=SEQUENCE:rsa_alg
203        pubkey=BITWRAP,SEQUENCE:rsapubkey
204
205        # algorithm ID for RSA is just an OID and a NULL
206        [rsa_alg]
207        algorithm=OID:rsaEncryption
208        parameter=NULL
209
210        # Actual public key: modulus and exponent
211        [rsapubkey]
212        n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
213        D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
214
215        e=INTEGER:0x010001
216

SEE ALSO

218       ERR_get_error(3)
219
221       Copyright 2002-2019 The OpenSSL Project Authors. All Rights Reserved.
222
223       Licensed under the OpenSSL license (the "License").  You may not use
224       this file except in compliance with the License.  You can obtain a copy
225       in the file LICENSE in the source distribution or at
226       <https://www.openssl.org/source/license.html>.
227
228
229
2301.1.1i                            2021-01-26            ASN1_GENERATE_NCONF(3)
Impressum