425a784052e806d57a4b6bb9a879f8598659258e
[dragonfly.git] / secure / lib / libcrypto / man / ASN1_generate_nconf.3
1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 .    ds C`
42 .    ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el       .ds Aq '
48 .\"
49 .\" If the F register is turned on, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{
60 .    if \nF \{
61 .        de IX
62 .        tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 .        if !\nF==2 \{
65 .            nr % 0
66 .            nr F 2
67 .        \}
68 .    \}
69 .\}
70 .rr rF
71 .\"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
74 .    \" fudge factors for nroff and troff
75 .if n \{\
76 .    ds #H 0
77 .    ds #V .8m
78 .    ds #F .3m
79 .    ds #[ \f1
80 .    ds #] \fP
81 .\}
82 .if t \{\
83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 .    ds #V .6m
85 .    ds #F 0
86 .    ds #[ \&
87 .    ds #] \&
88 .\}
89 .    \" simple accents for nroff and troff
90 .if n \{\
91 .    ds ' \&
92 .    ds ` \&
93 .    ds ^ \&
94 .    ds , \&
95 .    ds ~ ~
96 .    ds /
97 .\}
98 .if t \{\
99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 .\}
106 .    \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 .    \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 .    \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
121 \{\
122 .    ds : e
123 .    ds 8 ss
124 .    ds o a
125 .    ds d- d\h'-1'\(ga
126 .    ds D- D\h'-1'\(hy
127 .    ds th \o'bp'
128 .    ds Th \o'LP'
129 .    ds ae ae
130 .    ds Ae AE
131 .\}
132 .rm #[ #] #H #V #F C
133 .\" ========================================================================
134 .\"
135 .IX Title "ASN1_generate_nconf 3"
136 .TH ASN1_generate_nconf 3 "2015-06-12" "1.0.1o" "OpenSSL"
137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
139 .if n .ad l
140 .nh
141 .SH "NAME"
142 ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
143 .SH "SYNOPSIS"
144 .IX Header "SYNOPSIS"
145 .Vb 1
146 \& #include <openssl/asn1.h>
147 \&
148 \& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
149 \& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
150 .Ve
151 .SH "DESCRIPTION"
152 .IX Header "DESCRIPTION"
153 These functions generate the \s-1ASN1\s0 encoding of a string
154 in an \fB\s-1ASN1_TYPE\s0\fR structure.
155 .PP
156 \&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
157 the optional configuration information where additional strings
158 will be read from. \fBnconf\fR will typically come from a config
159 file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
160 which will typically be used by X509 v3 certificate extension
161 functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
162 configuration will be used.
163 .SH "GENERATION STRING FORMAT"
164 .IX Header "GENERATION STRING FORMAT"
165 The actual data encoded is determined by the string \fBstr\fR and
166 the configuration information. The general format of the string
167 is:
168 .IP "\fB[modifier,]type[:value]\fR" 2
169 .IX Item "[modifier,]type[:value]"
170 .PP
171 That is zero or more comma separated modifiers followed by a type
172 followed by an optional colon and a value. The formats of \fBtype\fR,
173 \&\fBvalue\fR and \fBmodifier\fR are explained below.
174 .SS "\s-1SUPPORTED TYPES\s0"
175 .IX Subsection "SUPPORTED TYPES"
176 The supported types are listed below. Unless otherwise specified
177 only the \fB\s-1ASCII\s0\fR format is permissible.
178 .IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
179 .IX Item "BOOLEAN, BOOL"
180 This encodes a boolean type. The \fBvalue\fR string is mandatory and
181 should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
182 \&\fBy\fR, \fB\s-1YES\s0\fR, \fByes\fR, \fB\s-1FALSE\s0\fR, \fBfalse\fR, \fBN\fR, \fBn\fR, \fB\s-1NO\s0\fR and \fBno\fR
183 are acceptable.
184 .IP "\fB\s-1NULL\s0\fR" 2
185 .IX Item "NULL"
186 Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
187 .IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
188 .IX Item "INTEGER, INT"
189 Encodes an \s-1ASN1 \s0\fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
190 the value of the integer, it can be prefaced by a minus sign and
191 is normally interpreted as a decimal value unless the prefix \fB0x\fR
192 is included.
193 .IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
194 .IX Item "ENUMERATED, ENUM"
195 Encodes the \s-1ASN1 \s0\fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
196 \&\fB\s-1INTEGER\s0\fR.
197 .IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
198 .IX Item "OBJECT, OID"
199 Encodes an \s-1ASN1 \s0\fB\s-1OBJECT IDENTIFIER\s0\fR, the \fBvalue\fR string can be
200 a short name, a long name or numerical format.
201 .IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
202 .IX Item "UTCTIME, UTC"
203 Encodes an \s-1ASN1 \s0\fBUTCTime\fR structure, the value should be in
204 the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
205 .IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
206 .IX Item "GENERALIZEDTIME, GENTIME"
207 Encodes an \s-1ASN1 \s0\fBGeneralizedTime\fR structure, the value should be in
208 the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
209 .IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
210 .IX Item "OCTETSTRING, OCT"
211 Encodes an \s-1ASN1 \s0\fB\s-1OCTET STRING\s0\fR. \fBvalue\fR represents the contents
212 of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
213 used to specify the format of \fBvalue\fR.
214 .IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
215 .IX Item "BITSTRING, BITSTR"
216 Encodes an \s-1ASN1 \s0\fB\s-1BIT STRING\s0\fR. \fBvalue\fR represents the contents
217 of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
218 can be used to specify the format of \fBvalue\fR.
219 .Sp
220 If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
221 bits is set to zero.
222 .IP "\fB\s-1UNIVERSALSTRING\s0\fR, \fB\s-1UNIV\s0\fR, \fB\s-1IA5\s0\fR, \fB\s-1IA5STRING\s0\fR, \fB\s-1UTF8\s0\fR, \fBUTF8String\fR, \fB\s-1BMP\s0\fR, \fB\s-1BMPSTRING\s0\fR, \fB\s-1VISIBLESTRING\s0\fR, \fB\s-1VISIBLE\s0\fR, \fB\s-1PRINTABLESTRING\s0\fR, \fB\s-1PRINTABLE\s0\fR, \fBT61\fR, \fBT61STRING\fR, \fB\s-1TELETEXSTRING\s0\fR, \fBGeneralString\fR, \fB\s-1NUMERICSTRING\s0\fR, \fB\s-1NUMERIC\s0\fR" 2
223 .IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC"
224 These encode the corresponding string types. \fBvalue\fR represents the
225 contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
226 .IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
227 .IX Item "SEQUENCE, SEQ, SET"
228 Formats the result as an \s-1ASN1 \s0\fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
229 should be a section name which will contain the contents. The
230 field names in the section are ignored and the values are in the
231 generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
232 will be encoded.
233 .SS "\s-1MODIFIERS\s0"
234 .IX Subsection "MODIFIERS"
235 Modifiers affect the following structure, they can be used to
236 add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
237 the string format of the final type and value. The supported
238 formats are documented below.
239 .IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
240 .IX Item "EXPLICIT, EXP"
241 Add an explicit tag to the following structure. This string
242 should be followed by a colon and the tag value to use as a
243 decimal value.
244 .Sp
245 By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL,
246 APPLICATION, PRIVATE\s0 or \s-1CONTEXT SPECIFIC\s0 tagging can be used,
247 the default is \s-1CONTEXT SPECIFIC.\s0
248 .IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
249 .IX Item "IMPLICIT, IMP"
250 This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
251 instead.
252 .IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
253 .IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
254 The following structure is surrounded by an \s-1OCTET STRING,\s0 a \s-1SEQUENCE,\s0
255 a \s-1SET\s0 or a \s-1BIT STRING\s0 respectively. For a \s-1BIT STRING\s0 the number of unused
256 bits is set to zero.
257 .IP "\fB\s-1FORMAT\s0\fR" 2
258 .IX Item "FORMAT"
259 This specifies the format of the ultimate value. It should be followed
260 by a colon and one of the strings \fB\s-1ASCII\s0\fR, \fB\s-1UTF8\s0\fR, \fB\s-1HEX\s0\fR or \fB\s-1BITLIST\s0\fR.
261 .Sp
262 If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
263 specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
264 output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT
265 STRING\s0) is a comma separated list of the indices of the set bits, all other
266 bits are zero.
267 .SH "EXAMPLES"
268 .IX Header "EXAMPLES"
269 A simple IA5String:
270 .PP
271 .Vb 1
272 \& IA5STRING:Hello World
273 .Ve
274 .PP
275 An IA5String explicitly tagged:
276 .PP
277 .Vb 1
278 \& EXPLICIT:0,IA5STRING:Hello World
279 .Ve
280 .PP
281 An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
282 .PP
283 .Vb 1
284 \& EXPLICIT:0A,IA5STRING:Hello World
285 .Ve
286 .PP
287 A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
288 .PP
289 .Vb 1
290 \& FORMAT:BITLIST,BITSTRING:1,5
291 .Ve
292 .PP
293 A more complex example using a config file to produce a
294 \&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
295 .PP
296 .Vb 1
297 \& asn1 = SEQUENCE:seq_section
298 \&
299 \& [seq_section]
300 \&
301 \& field1 = BOOLEAN:TRUE
302 \& field2 = OID:commonName
303 \& field3 = UTF8:Third field
304 .Ve
305 .PP
306 This example produces an RSAPrivateKey structure, this is the
307 key contained in the file client.pem in all OpenSSL distributions
308 (note: the field names such as 'coeff' are ignored and are present just
309 for clarity):
310 .PP
311 .Vb 3
312 \& asn1=SEQUENCE:private_key
313 \& [private_key]
314 \& version=INTEGER:0
315 \&
316 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
317 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
318 \&
319 \& e=INTEGER:0x010001
320 \&
321 \& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
322 \& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
323 \&
324 \& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
325 \& D4BD57
326 \&
327 \& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
328 \& 46EC4F
329 \&
330 \& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
331 \& 9C0A39B9
332 \&
333 \& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
334 \& E7B2458F
335 \&
336 \& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
337 \& 628657053A
338 .Ve
339 .PP
340 This example is the corresponding public key in a SubjectPublicKeyInfo
341 structure:
342 .PP
343 .Vb 2
344 \& # Start with a SEQUENCE
345 \& asn1=SEQUENCE:pubkeyinfo
346 \&
347 \& # pubkeyinfo contains an algorithm identifier and the public key wrapped
348 \& # in a BIT STRING
349 \& [pubkeyinfo]
350 \& algorithm=SEQUENCE:rsa_alg
351 \& pubkey=BITWRAP,SEQUENCE:rsapubkey
352 \&
353 \& # algorithm ID for RSA is just an OID and a NULL
354 \& [rsa_alg]
355 \& algorithm=OID:rsaEncryption
356 \& parameter=NULL
357 \&
358 \& # Actual public key: modulus and exponent
359 \& [rsapubkey]
360 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
361 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
362 \&
363 \& e=INTEGER:0x010001
364 .Ve
365 .SH "RETURN VALUES"
366 .IX Header "RETURN VALUES"
367 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
368 data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
369 .PP
370 The error codes that can be obtained by \fIERR_get_error\fR\|(3).
371 .SH "SEE ALSO"
372 .IX Header "SEE ALSO"
373 \&\fIERR_get_error\fR\|(3)
374 .SH "HISTORY"
375 .IX Header "HISTORY"
376 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8