summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ASN1_generate_nconf.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/ASN1_generate_nconf.3394
1 files changed, 0 insertions, 394 deletions
diff --git a/src/lib/libcrypto/man/ASN1_generate_nconf.3 b/src/lib/libcrypto/man/ASN1_generate_nconf.3
deleted file mode 100644
index b15d4295a9..0000000000
--- a/src/lib/libcrypto/man/ASN1_generate_nconf.3
+++ /dev/null
@@ -1,394 +0,0 @@
1.\" $OpenBSD: ASN1_generate_nconf.3,v 1.13 2019/06/10 14:58:48 schwarze Exp $
2.\" OpenSSL 05ea606a Fri May 20 20:52:46 2016 -0400
3.\"
4.\" This file was written by Dr. Stephen Henson.
5.\" Copyright (c) 2002, 2003, 2006-2009, 2013-2015 The OpenSSL Project.
6.\" All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\"
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\"
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in
17.\" the documentation and/or other materials provided with the
18.\" distribution.
19.\"
20.\" 3. All advertising materials mentioning features or use of this
21.\" software must display the following acknowledgment:
22.\" "This product includes software developed by the OpenSSL Project
23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24.\"
25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26.\" endorse or promote products derived from this software without
27.\" prior written permission. For written permission, please contact
28.\" openssl-core@openssl.org.
29.\"
30.\" 5. Products derived from this software may not be called "OpenSSL"
31.\" nor may "OpenSSL" appear in their names without prior written
32.\" permission of the OpenSSL Project.
33.\"
34.\" 6. Redistributions of any form whatsoever must retain the following
35.\" acknowledgment:
36.\" "This product includes software developed by the OpenSSL Project
37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38.\"
39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50.\" OF THE POSSIBILITY OF SUCH DAMAGE.
51.\"
52.Dd $Mdocdate: June 10 2019 $
53.Dt ASN1_GENERATE_NCONF 3
54.Os
55.Sh NAME
56.Nm ASN1_generate_nconf ,
57.Nm ASN1_generate_v3
58.Nd ASN.1 generation functions
59.Sh SYNOPSIS
60.In openssl/asn1.h
61.Ft ASN1_TYPE *
62.Fo ASN1_generate_nconf
63.Fa "const char *str"
64.Fa "CONF *nconf"
65.Fc
66.Ft ASN1_TYPE *
67.Fo ASN1_generate_v3
68.Fa "const char *str"
69.Fa "X509V3_CTX *cnf"
70.Fc
71.Sh DESCRIPTION
72These functions generate the ASN.1 encoding of a string in an
73.Vt ASN1_TYPE
74structure.
75.Pp
76.Fa str
77contains the string to encode
78.Fa nconf
79or
80.Fa cnf
81contains the optional configuration information
82where additional strings will be read from.
83.Fa nconf
84will typically come from a config file whereas
85.Fa cnf
86is obtained from an
87.Vt X509V3_CTX
88structure which will typically be used
89by X509 v3 certificate extension functions.
90.Fa cnf
91or
92.Fa nconf
93can be set to
94.Dv NULL
95if no additional configuration will be used.
96.Sh GENERATION STRING FORMAT
97The actual data encoded is determined by the string
98.Fa str
99and the configuration information.
100The general format of the string is:
101.Pp
102.D1 Oo Ar modifier , Oc Ns Ar type Ns Op : Ns Ar value
103.Pp
104That is zero or more comma separated modifiers followed by a type
105followed by an optional colon and a value.
106The formats of
107.Ar type ,
108.Ar value
109and
110.Ar modifier
111are explained below.
112.Ss Supported types
113The supported types are listed below.
114Unless otherwise specified, only the
115.Cm ASCII
116format is permissible.
117.Bl -tag -width Ds
118.It Cm BOOLEAN , BOOL
119This encodes a boolean type.
120The
121.Ar value
122string is mandatory and should be
123.Cm TRUE
124or
125.Cm FALSE .
126Additionally
127.Cm true ,
128.Cm Y ,
129.Cm y ,
130.Cm YES ,
131.Cm yes ,
132.Cm false ,
133.Cm N ,
134.Cm n ,
135.Cm NO
136and
137.Cm no
138are acceptable.
139.It Cm NULL
140Encode the NULL type.
141The
142.Ar value
143string must not be present.
144.It Cm INTEGER , INT
145Encodes an ASN.1 INTEGER type.
146The
147.Ar value
148string represents the value of the integer.
149It can be prefaced by a minus sign
150and is normally interpreted as a decimal value unless the prefix
151.Cm 0x
152is included.
153.It Cm ENUMERATED , ENUM
154Encodes the ASN.1 ENUMERATED type.
155It is otherwise identical to
156.Cm INTEGER .
157.It Cm OBJECT , OID
158Encodes an ASN.1 OBJECT IDENTIFIER.
159The
160.Ar value
161string can be a short name, a long name, or numerical format.
162.It Cm UTCTIME , UTC
163Encodes an ASN.1 UTCTime structure.
164The value should be in the format
165.Ar YYMMDDHHMMSSZ .
166.It Cm GENERALIZEDTIME , GENTIME
167Encodes an ASN.1 GeneralizedTime structure.
168The value should be in the format
169.Ar YYYYMMDDHHMMSSZ .
170.It Cm OCTETSTRING , OCT
171Encodes an ASN.1 OCTET STRING.
172.Ar value
173represents the contents of this structure.
174The format strings
175.Cm ASCII
176and
177.Cm HEX
178can be used to specify the format of
179.Ar value .
180.It Cm BITSTRING , BITSTR
181Encodes an ASN.1 BIT STRING.
182.Ar value
183represents the contents of this structure.
184The format strings
185.Cm ASCII ,
186.Cm HEX ,
187and
188.Cm BITLIST
189can be used to specify the format of
190.Ar value .
191.Pp
192If the format is anything other than
193.Cm BITLIST ,
194the number of unused bits is set to zero.
195.It Xo
196.Cm BMPSTRING , BMP ,
197.Cm GeneralString ,
198.Cm IA5STRING , IA5 ,
199.Cm NUMERICSTRING , NUMERIC ,
200.Cm PRINTABLESTRING , PRINTABLE ,
201.Cm T61STRING , T61 ,
202.Cm TELETEXSTRING ,
203.Cm UNIVERSALSTRING , UNIV ,
204.Cm UTF8String , UTF8 ,
205.Cm VISIBLESTRING , VISIBLE
206.Xc
207These encode the corresponding string types.
208.Ar value
209represents the contents of this structure.
210The format can be
211.Cm ASCII
212or
213.Cm UTF8 .
214.It Cm SEQUENCE , SEQ , SET
215Formats the result as an ASN.1 SEQUENCE or SET type.
216.Ar value
217should be a section name which will contain the contents.
218The field names in the section are ignored
219and the values are in the generated string format.
220If
221.Ar value
222is absent, then an empty SEQUENCE will be encoded.
223.El
224.Ss Modifiers
225Modifiers affect the following structure.
226They can be used to add EXPLICIT or IMPLICIT tagging, add wrappers,
227or to change the string format of the final type and value.
228The supported formats are:
229.Bl -tag -width Ds
230.It Cm EXPLICIT , EXP
231Add an explicit tag to the following structure.
232This string should be followed by a colon
233and the tag value to use as a decimal value.
234.Pp
235By following the number with
236.Cm U ,
237.Cm A ,
238.Cm P
239or
240.Cm C ,
241UNIVERSAL, APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used.
242The default is CONTEXT SPECIFIC.
243.It Cm IMPLICIT , IMP
244This is the same as
245.Cm EXPLICIT
246except IMPLICIT tagging is used instead.
247.It Cm OCTWRAP , SEQWRAP , SETWRAP , BITWRAP
248The following structure is surrounded by
249an OCTET STRING, a SEQUENCE, a SET, or a BIT STRING, respectively.
250For a BIT STRING the number of unused bits is set to zero.
251.It Cm FORMAT
252This specifies the format of the ultimate value.
253It should be followed by a colon and one of the strings
254.Cm ASCII ,
255.Cm UTF8 ,
256.Cm HEX ,
257or
258.Cm BITLIST .
259.Pp
260If no format specifier is included, then
261.Cm ASCII
262is used.
263If
264.Cm UTF8
265is specified, then the
266.Ar value
267string must be a valid UTF-8 string.
268For
269.Cm HEX ,
270the output must be a set of hex digits.
271.Cm BITLIST
272(which is only valid for a BIT STRING) is a comma separated list
273of the indices of the set bits, all other bits are zero.
274.El
275.Sh RETURN VALUES
276.Fn ASN1_generate_nconf
277and
278.Fn ASN1_generate_v3
279return the encoded data as an
280.Vt ASN1_TYPE
281structure or
282.Dv NULL
283if an error occurred.
284.Pp
285The error codes can be obtained by
286.Xr ERR_get_error 3 .
287.Sh EXAMPLES
288A simple
289.Vt IA5String :
290.Pp
291.Dl IA5STRING:Hello World
292.Pp
293An
294.Vt IA5String
295explicitly tagged:
296.Pp
297.Dl EXPLICIT:0,IA5STRING:Hello World
298.Pp
299An
300.Vt IA5String
301explicitly tagged using APPLICATION tagging:
302.Pp
303.Dl EXPLICIT:0A,IA5STRING:Hello World
304.Pp
305A BITSTRING with bits 1 and 5 set and all others zero:
306.Pp
307.Dl FORMAT:BITLIST,BITSTRING:1,5
308.Pp
309A more complex example using a config file to produce a
310SEQUENCE consisting of a BOOL an OID and a
311.Vt UTF8String :
312.Bd -literal -offset indent
313asn1 = SEQUENCE:seq_section
314
315[seq_section]
316
317field1 = BOOLEAN:TRUE
318field2 = OID:commonName
319field3 = UTF8:Third field
320.Ed
321.Pp
322This example produces an
323.Vt RSAPrivateKey
324structure.
325This is the key contained in the file
326.Pa client.pem
327in all OpenSSL distributions.
328Note that the field names such as
329.Qq coeff
330are ignored and are present just for clarity.
331.Bd -literal -offset 2n
332asn1=SEQUENCE:private_key
333[private_key]
334version=INTEGER:0
335
336n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
337D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
338
339e=INTEGER:0x010001
340
341d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
342F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
343
344p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
345D4BD57
346
347q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
34846EC4F
349
350exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
3519C0A39B9
352
353exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
354E7B2458F
355
356coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
357628657053A
358.Ed
359.Pp
360This example is the corresponding public key in an ASN.1
361.Vt SubjectPublicKeyInfo
362structure:
363.Bd -literal -offset 2n
364# Start with a SEQUENCE
365asn1=SEQUENCE:pubkeyinfo
366
367# pubkeyinfo contains an algorithm identifier and the public key
368# wrapped in a BIT STRING
369[pubkeyinfo]
370algorithm=SEQUENCE:rsa_alg
371pubkey=BITWRAP,SEQUENCE:rsapubkey
372
373# algorithm ID for RSA is just an OID and a NULL
374[rsa_alg]
375algorithm=OID:rsaEncryption
376parameter=NULL
377
378# Actual public key: modulus and exponent
379[rsapubkey]
380n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
381D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
382
383e=INTEGER:0x010001
384.Ed
385.Sh SEE ALSO
386.Xr ASN1_TYPE_get 3 ,
387.Xr d2i_ASN1_TYPE 3 ,
388.Xr x509v3.cnf 5
389.Sh HISTORY
390.Fn ASN1_generate_nconf
391and
392.Fn ASN1_generate_v3
393first appeared in OpenSSL 0.9.8 and have been available since
394.Ox 4.5 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 23:24:54 +0000