Debian Codegraph @

upstream/debian-unstable/man3/ASN1_generate_nconf.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ASN1_GENERATE_NCONF 3SSL"
58 .TH ASN1_GENERATE_NCONF 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 string generation functions
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/asn1.h>
69 \&
70 \& ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
71 \& ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 These functions generate the ASN1 encoding of a string
76 in an \fBASN1_TYPE\fR structure.
77 .PP
78 \&\fIstr\fR contains the string to encode. \fInconf\fR or \fIcnf\fR contains
79 the optional configuration information where additional strings
80 will be read from. \fInconf\fR will typically come from a config
81 file whereas \fIcnf\fR is obtained from an \fBX509V3_CTX\fR structure,
82 which will typically be used by X509 v3 certificate extension
83 functions. \fIcnf\fR or \fInconf\fR can be set to NULL if no additional
84 configuration will be used.
85 .SH "GENERATION STRING FORMAT"
86 .IX Header "GENERATION STRING FORMAT"
87 The actual data encoded is determined by the string \fIstr\fR and
88 the configuration information. The general format of the string
89 is:
90 .IP [\fImodifier\fR,]\fItype\fR[:\fIvalue\fR] 4
91 .IX Item "[modifier,]type[:value]"
92 .PP
93 That is zero or more comma separated modifiers followed by a type
94 followed by an optional colon and a value. The formats of \fItype\fR,
95 \&\fIvalue\fR and \fImodifier\fR are explained below.
96 .SS "Supported Types"
97 .IX Subsection "Supported Types"
98 The supported types are listed below.
99 Case is not significant in the type names.
100 Unless otherwise specified only the \fBASCII\fR format is permissible.
101 .IP "\fBBOOLEAN\fR, \fBBOOL\fR" 4
102 .IX Item "BOOLEAN, BOOL"
103 This encodes a boolean type. The \fIvalue\fR string is mandatory and
104 should be \fBTRUE\fR or \fBFALSE\fR. Additionally \fBTRUE\fR, \fBtrue\fR, \fBY\fR,
105 \&\fBy\fR, \fBYES\fR, \fByes\fR, \fBFALSE\fR, \fBfalse\fR, \fBN\fR, \fBn\fR, \fBNO\fR and \fBno\fR
106 are acceptable.
107 .IP \fBNULL\fR 4
108 .IX Item "NULL"
109 Encode the \fBNULL\fR type, the \fIvalue\fR string must not be present.
110 .IP "\fBINTEGER\fR, \fBINT\fR" 4
111 .IX Item "INTEGER, INT"
112 Encodes an ASN1 \fBINTEGER\fR type. The \fIvalue\fR string represents
113 the value of the integer, it can be prefaced by a minus sign and
114 is normally interpreted as a decimal value unless the prefix \fB0x\fR
115 is included.
116 .IP "\fBENUMERATED\fR, \fBENUM\fR" 4
117 .IX Item "ENUMERATED, ENUM"
118 Encodes the ASN1 \fBENUMERATED\fR type, it is otherwise identical to
119 \&\fBINTEGER\fR.
120 .IP "\fBOBJECT\fR, \fBOID\fR" 4
121 .IX Item "OBJECT, OID"
122 Encodes an ASN1 \fBOBJECT IDENTIFIER\fR, the \fIvalue\fR string can be
123 a short name, a long name or numerical format.
124 .IP "\fBUTCTIME\fR, \fBUTC\fR" 4
125 .IX Item "UTCTIME, UTC"
126 Encodes an ASN1 \fBUTCTime\fR structure, the value should be in
127 the format \fBYYMMDDHHMMSSZ\fR.
128 .IP "\fBGENERALIZEDTIME\fR, \fBGENTIME\fR" 4
129 .IX Item "GENERALIZEDTIME, GENTIME"
130 Encodes an ASN1 \fBGeneralizedTime\fR structure, the value should be in
131 the format \fBYYYYMMDDHHMMSSZ\fR.
132 .IP "\fBOCTETSTRING\fR, \fBOCT\fR" 4
133 .IX Item "OCTETSTRING, OCT"
134 Encodes an ASN1 \fBOCTET STRING\fR. \fIvalue\fR represents the contents
135 of this structure, the format strings \fBASCII\fR and \fBHEX\fR can be
136 used to specify the format of \fIvalue\fR.
137 .IP "\fBBITSTRING\fR, \fBBITSTR\fR" 4
138 .IX Item "BITSTRING, BITSTR"
139 Encodes an ASN1 \fBBIT STRING\fR. \fIvalue\fR represents the contents
140 of this structure, the format strings \fBASCII\fR, \fBHEX\fR and \fBBITLIST\fR
141 can be used to specify the format of \fIvalue\fR.
142 .Sp
143 If the format is anything other than \fBBITLIST\fR the number of unused
144 bits is set to zero.
145 .IP "\fBUNIVERSALSTRING\fR, \fBUNIV\fR, \fBIA5\fR, \fBIA5STRING\fR, \fBUTF8\fR, \fBUTF8String\fR, \fBBMP\fR, \fBBMPSTRING\fR, \fBVISIBLESTRING\fR, \fBVISIBLE\fR, \fBPRINTABLESTRING\fR, \fBPRINTABLE\fR, \fBT61\fR, \fBT61STRING\fR, \fBTELETEXSTRING\fR, \fBGeneralString\fR, \fBNUMERICSTRING\fR, \fBNUMERIC\fR" 4
146 .IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC"
147 These encode the corresponding string types. \fIvalue\fR represents the
148 contents of this structure. The format can be \fBASCII\fR or \fBUTF8\fR.
149 .IP "\fBSEQUENCE\fR, \fBSEQ\fR, \fBSET\fR" 4
150 .IX Item "SEQUENCE, SEQ, SET"
151 Formats the result as an ASN1 \fBSEQUENCE\fR or \fBSET\fR type. \fIvalue\fR
152 should be a section name which will contain the contents. The
153 field names in the section are ignored and the values are in the
154 generated string format. If \fIvalue\fR is absent then an empty SEQUENCE
155 will be encoded.
156 .SS Modifiers
157 .IX Subsection "Modifiers"
158 Modifiers affect the following structure, they can be used to
159 add EXPLICIT or IMPLICIT tagging, add wrappers or to change
160 the string format of the final type and value. The supported
161 formats are documented below.
162 .IP "\fBEXPLICIT\fR, \fBEXP\fR" 4
163 .IX Item "EXPLICIT, EXP"
164 Add an explicit tag to the following structure. This string
165 should be followed by a colon and the tag value to use as a
166 decimal value.
167 .Sp
168 By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR UNIVERSAL,
169 APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
170 the default is CONTEXT SPECIFIC.
171 .IP "\fBIMPLICIT\fR, \fBIMP\fR" 4
172 .IX Item "IMPLICIT, IMP"
173 This is the same as \fBEXPLICIT\fR except IMPLICIT tagging is used
174 instead.
175 .IP "\fBOCTWRAP\fR, \fBSEQWRAP\fR, \fBSETWRAP\fR, \fBBITWRAP\fR" 4
176 .IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
177 The following structure is surrounded by an OCTET STRING, a SEQUENCE,
178 a SET or a BIT STRING respectively. For a BIT STRING the number of unused
179 bits is set to zero.
180 .IP \fBFORMAT\fR 4
181 .IX Item "FORMAT"
182 This specifies the format of the ultimate value. It should be followed
183 by a colon and one of the strings \fBASCII\fR, \fBUTF8\fR, \fBHEX\fR or \fBBITLIST\fR.
184 .Sp
185 If no format specifier is included then \fBASCII\fR is used. If \fBUTF8\fR is
186 specified then the value string must be a valid \fBUTF8\fR string. For \fBHEX\fR the
187 output must be a set of hex digits. \fBBITLIST\fR (which is only valid for a BIT
188 STRING) is a comma separated list of the indices of the set bits, all other
189 bits are zero.
190 .SH "RETURN VALUES"
191 .IX Header "RETURN VALUES"
192 \&\fBASN1_generate_nconf()\fR and \fBASN1_generate_v3()\fR return the encoded
193 data as an \fBASN1_TYPE\fR structure or NULL if an error occurred.
194 .PP
195 The error codes that can be obtained by \fBERR_get_error\fR\|(3).
196 .SH EXAMPLES
197 .IX Header "EXAMPLES"
198 A simple IA5String:
199 .PP
200 .Vb 1
201 \& IA5STRING:Hello World
202 .Ve
203 .PP
204 An IA5String explicitly tagged:
205 .PP
206 .Vb 1
207 \& EXPLICIT:0,IA5STRING:Hello World
208 .Ve
209 .PP
210 An IA5String explicitly tagged using APPLICATION tagging:
211 .PP
212 .Vb 1
213 \& EXPLICIT:0A,IA5STRING:Hello World
214 .Ve
215 .PP
216 A BITSTRING with bits 1 and 5 set and all others zero:
217 .PP
218 .Vb 1
219 \& FORMAT:BITLIST,BITSTRING:1,5
220 .Ve
221 .PP
222 A more complex example using a config file to produce a
223 SEQUENCE consisting of a BOOL an OID and a UTF8String:
224 .PP
225 .Vb 1
226 \& asn1 = SEQUENCE:seq_section
227 \&
228 \& [seq_section]
229 \&
230 \& field1 = BOOLEAN:TRUE
231 \& field2 = OID:commonName
232 \& field3 = UTF8:Third field
233 .Ve
234 .PP
235 This example produces an RSAPrivateKey structure, this is the
236 key contained in the file client.pem in all OpenSSL distributions
237 (note: the field names such as 'coeff' are ignored and are present just
238 for clarity):
239 .PP
240 .Vb 3
241 \& asn1=SEQUENCE:private_key
242 \& [private_key]
243 \& version=INTEGER:0
244 \&
245 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
246 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
247 \&
248 \& e=INTEGER:0x010001
249 \&
250 \& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
251 \& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
252 \&
253 \& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
254 \& D4BD57
255 \&
256 \& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
257 \& 46EC4F
258 \&
259 \& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
260 \& 9C0A39B9
261 \&
262 \& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
263 \& E7B2458F
264 \&
265 \& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
266 \& 628657053A
267 .Ve
268 .PP
269 This example is the corresponding public key in a SubjectPublicKeyInfo
270 structure:
271 .PP
272 .Vb 2
273 \& # Start with a SEQUENCE
274 \& asn1=SEQUENCE:pubkeyinfo
275 \&
276 \& # pubkeyinfo contains an algorithm identifier and the public key wrapped
277 \& # in a BIT STRING
278 \& [pubkeyinfo]
279 \& algorithm=SEQUENCE:rsa_alg
280 \& pubkey=BITWRAP,SEQUENCE:rsapubkey
281 \&
282 \& # algorithm ID for RSA is just an OID and a NULL
283 \& [rsa_alg]
284 \& algorithm=OID:rsaEncryption
285 \& parameter=NULL
286 \&
287 \& # Actual public key: modulus and exponent
288 \& [rsapubkey]
289 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
290 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
291 \&
292 \& e=INTEGER:0x010001
293 .Ve
294 .SH "SEE ALSO"
295 .IX Header "SEE ALSO"
296 \&\fBERR_get_error\fR\|(3)
297 .SH COPYRIGHT
298 .IX Header "COPYRIGHT"
299 Copyright 2002\-2021 The OpenSSL Project Authors. All Rights Reserved.
300 .PP
301 Licensed under the Apache License 2.0 (the "License"). You may not use
302 this file except in compliance with the License. You can obtain a copy
303 in the file LICENSE in the source distribution or at
304 <https://www.openssl.org/source/license.html>.