Local adjustments for OpenSSL-1.0.1p.
[dragonfly.git] / secure / lib / libcrypto / man / ASN1_generate_nconf.3
CommitLineData
5a44c043 1.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
a561f9ff
SS
2.\"
3.\" Standard preamble:
4.\" ========================================================================
a561f9ff
SS
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
e257b235
PA
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-
a561f9ff
SS
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" ''
5a44c043
SW
41. ds C`
42. ds C'
a561f9ff
SS
43'br\}
44.\"
e257b235
PA
45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq
47.el .ds Aq '
48.\"
a561f9ff 49.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
a561f9ff
SS
51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion.
5a44c043
SW
53.\"
54.\" Avoid warning from groff about undefined register 'F'.
55.de IX
a561f9ff 56..
5a44c043
SW
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"
e257b235 63..
5a44c043
SW
64. if !\nF==2 \{
65. nr % 0
66. nr F 2
67. \}
68. \}
e257b235 69.\}
5a44c043 70.rr rF
aac4ff6f 71.\"
a561f9ff
SS
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"
7dc78669 136.TH ASN1_generate_nconf 3 "2015-07-09" "1.0.1p" "OpenSSL"
e257b235
PA
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
a561f9ff
SS
141.SH "NAME"
142ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
143.SH "SYNOPSIS"
144.IX Header "SYNOPSIS"
01185282
PA
145.Vb 1
146\& #include <openssl/asn1.h>
147\&
a561f9ff
SS
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"
153These functions generate the \s-1ASN1\s0 encoding of a string
154in an \fB\s-1ASN1_TYPE\s0\fR structure.
155.PP
156\&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
157the optional configuration information where additional strings
158will be read from. \fBnconf\fR will typically come from a config
159file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
160which will typically be used by X509 v3 certificate extension
161functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
162configuration will be used.
163.SH "GENERATION STRING FORMAT"
164.IX Header "GENERATION STRING FORMAT"
165The actual data encoded is determined by the string \fBstr\fR and
166the configuration information. The general format of the string
167is:
aac4ff6f
PA
168.IP "\fB[modifier,]type[:value]\fR" 2
169.IX Item "[modifier,]type[:value]"
a561f9ff
SS
170.PP
171That is zero or more comma separated modifiers followed by a type
172followed by an optional colon and a value. The formats of \fBtype\fR,
173\&\fBvalue\fR and \fBmodifier\fR are explained below.
5a44c043 174.SS "\s-1SUPPORTED TYPES\s0"
a561f9ff
SS
175.IX Subsection "SUPPORTED TYPES"
176The supported types are listed below. Unless otherwise specified
177only 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"
180This encodes a boolean type. The \fBvalue\fR string is mandatory and
181should 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
e257b235 183are acceptable.
a561f9ff
SS
184.IP "\fB\s-1NULL\s0\fR" 2
185.IX Item "NULL"
186Encode 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"
5a44c043 189Encodes an \s-1ASN1 \s0\fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
ecf90583 190the value of the integer, it can be prefaced by a minus sign and
a561f9ff
SS
191is normally interpreted as a decimal value unless the prefix \fB0x\fR
192is included.
193.IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
194.IX Item "ENUMERATED, ENUM"
5a44c043 195Encodes the \s-1ASN1 \s0\fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
a561f9ff
SS
196\&\fB\s-1INTEGER\s0\fR.
197.IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
198.IX Item "OBJECT, OID"
5a44c043 199Encodes an \s-1ASN1 \s0\fB\s-1OBJECT IDENTIFIER\s0\fR, the \fBvalue\fR string can be
a561f9ff
SS
200a 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"
5a44c043 203Encodes an \s-1ASN1 \s0\fBUTCTime\fR structure, the value should be in
e257b235 204the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
a561f9ff
SS
205.IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
206.IX Item "GENERALIZEDTIME, GENTIME"
5a44c043 207Encodes an \s-1ASN1 \s0\fBGeneralizedTime\fR structure, the value should be in
e257b235 208the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
a561f9ff
SS
209.IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
210.IX Item "OCTETSTRING, OCT"
5a44c043 211Encodes an \s-1ASN1 \s0\fB\s-1OCTET STRING\s0\fR. \fBvalue\fR represents the contents
a561f9ff
SS
212of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
213used to specify the format of \fBvalue\fR.
aac4ff6f
PA
214.IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
215.IX Item "BITSTRING, BITSTR"
5a44c043 216Encodes an \s-1ASN1 \s0\fB\s-1BIT STRING\s0\fR. \fBvalue\fR represents the contents
a561f9ff
SS
217of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
218can be used to specify the format of \fBvalue\fR.
219.Sp
220If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
221bits is set to zero.
01185282
PA
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"
a561f9ff
SS
224These encode the corresponding string types. \fBvalue\fR represents the
225contents 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"
5a44c043 228Formats the result as an \s-1ASN1 \s0\fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
a561f9ff
SS
229should be a section name which will contain the contents. The
230field names in the section are ignored and the values are in the
231generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
232will be encoded.
01185282 233.SS "\s-1MODIFIERS\s0"
a561f9ff
SS
234.IX Subsection "MODIFIERS"
235Modifiers affect the following structure, they can be used to
236add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
237the string format of the final type and value. The supported
238formats are documented below.
239.IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
240.IX Item "EXPLICIT, EXP"
241Add an explicit tag to the following structure. This string
242should be followed by a colon and the tag value to use as a
243decimal value.
244.Sp
5a44c043
SW
245By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL,
246APPLICATION, PRIVATE\s0 or \s-1CONTEXT SPECIFIC\s0 tagging can be used,
247the default is \s-1CONTEXT SPECIFIC.\s0
a561f9ff
SS
248.IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
249.IX Item "IMPLICIT, IMP"
250This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
251instead.
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"
5a44c043
SW
254The following structure is surrounded by an \s-1OCTET STRING,\s0 a \s-1SEQUENCE,\s0
255a \s-1SET\s0 or a \s-1BIT STRING\s0 respectively. For a \s-1BIT STRING\s0 the number of unused
a561f9ff
SS
256bits is set to zero.
257.IP "\fB\s-1FORMAT\s0\fR" 2
258.IX Item "FORMAT"
259This specifies the format of the ultimate value. It should be followed
260by 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
aac4ff6f
PA
262If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
263specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
5a44c043
SW
264output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT
265STRING\s0) is a comma separated list of the indices of the set bits, all other
aac4ff6f 266bits are zero.
a561f9ff
SS
267.SH "EXAMPLES"
268.IX Header "EXAMPLES"
269A simple IA5String:
270.PP
271.Vb 1
272\& IA5STRING:Hello World
273.Ve
274.PP
275An IA5String explicitly tagged:
276.PP
277.Vb 1
278\& EXPLICIT:0,IA5STRING:Hello World
279.Ve
280.PP
281An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
282.PP
283.Vb 1
284\& EXPLICIT:0A,IA5STRING:Hello World
285.Ve
286.PP
aac4ff6f
PA
287A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
288.PP
289.Vb 1
01185282 290\& FORMAT:BITLIST,BITSTRING:1,5
aac4ff6f
PA
291.Ve
292.PP
a561f9ff
SS
293A 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
aac4ff6f
PA
296.Vb 1
297\& asn1 = SEQUENCE:seq_section
e257b235 298\&
aac4ff6f 299\& [seq_section]
e257b235 300\&
aac4ff6f
PA
301\& field1 = BOOLEAN:TRUE
302\& field2 = OID:commonName
303\& field3 = UTF8:Third field
304.Ve
a561f9ff
SS
305.PP
306This example produces an RSAPrivateKey structure, this is the
307key contained in the file client.pem in all OpenSSL distributions
308(note: the field names such as 'coeff' are ignored and are present just
309for clarity):
310.PP
311.Vb 3
312\& asn1=SEQUENCE:private_key
313\& [private_key]
314\& version=INTEGER:0
e257b235 315\&
a561f9ff
SS
316\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
317\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
e257b235 318\&
a561f9ff 319\& e=INTEGER:0x010001
e257b235 320\&
a561f9ff
SS
321\& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
322\& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
e257b235 323\&
a561f9ff
SS
324\& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
325\& D4BD57
e257b235 326\&
a561f9ff
SS
327\& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
328\& 46EC4F
e257b235 329\&
a561f9ff
SS
330\& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
331\& 9C0A39B9
e257b235 332\&
a561f9ff
SS
333\& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
334\& E7B2458F
e257b235 335\&
a561f9ff
SS
336\& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
337\& 628657053A
338.Ve
339.PP
340This example is the corresponding public key in a SubjectPublicKeyInfo
341structure:
342.PP
343.Vb 2
344\& # Start with a SEQUENCE
345\& asn1=SEQUENCE:pubkeyinfo
e257b235 346\&
a561f9ff
SS
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
e257b235 352\&
a561f9ff
SS
353\& # algorithm ID for RSA is just an OID and a NULL
354\& [rsa_alg]
355\& algorithm=OID:rsaEncryption
356\& parameter=NULL
e257b235 357\&
a561f9ff
SS
358\& # Actual public key: modulus and exponent
359\& [rsapubkey]
360\& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
361\& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
e257b235 362\&
a561f9ff
SS
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
368data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
369.PP
370The 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