1 .\" $NetBSD: ASN1_generate_nconf.3,v 1.14 2015/06/12 17:01:13 christos Exp $
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
11 .de Vb \" Begin verbatim text
16 .de Ve \" End verbatim text
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
56 .\" Avoid warning from groff about undefined register 'F'.
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
64 . tm Index:\\$1\t\\n%\t"\\$2"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
91 . \" simple accents for nroff and troff
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
135 .\" ========================================================================
137 .IX Title "ASN1_generate_nconf 3"
138 .TH ASN1_generate_nconf 3 "2014-08-10" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
144 ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
148 .IX Header "SYNOPSIS"
150 \& #include <openssl/asn1.h>
152 \& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
153 \& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
156 .IX Header "DESCRIPTION"
157 These functions generate the \s-1ASN1\s0 encoding of a string
158 in an \fB\s-1ASN1_TYPE\s0\fR structure.
160 \&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
161 the optional configuration information where additional strings
162 will be read from. \fBnconf\fR will typically come from a config
163 file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
164 which will typically be used by X509 v3 certificate extension
165 functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
166 configuration will be used.
167 .SH "GENERATION STRING FORMAT"
168 .IX Header "GENERATION STRING FORMAT"
169 The actual data encoded is determined by the string \fBstr\fR and
170 the configuration information. The general format of the string
172 .IP "\fB[modifier,]type[:value]\fR" 2
173 .IX Item "[modifier,]type[:value]"
175 That is zero or more comma separated modifiers followed by a type
176 followed by an optional colon and a value. The formats of \fBtype\fR,
177 \&\fBvalue\fR and \fBmodifier\fR are explained below.
178 .SS "\s-1SUPPORTED TYPES\s0"
179 .IX Subsection "SUPPORTED TYPES"
180 The supported types are listed below. Unless otherwise specified
181 only the \fB\s-1ASCII\s0\fR format is permissible.
182 .IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
183 .IX Item "BOOLEAN, BOOL"
184 This encodes a boolean type. The \fBvalue\fR string is mandatory and
185 should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
186 \&\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
188 .IP "\fB\s-1NULL\s0\fR" 2
190 Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
191 .IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
192 .IX Item "INTEGER, INT"
193 Encodes an \s-1ASN1 \s0\fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
194 the value of the integer, it can be prefaced by a minus sign and
195 is normally interpreted as a decimal value unless the prefix \fB0x\fR
197 .IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
198 .IX Item "ENUMERATED, ENUM"
199 Encodes the \s-1ASN1 \s0\fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
200 \&\fB\s-1INTEGER\s0\fR.
201 .IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
202 .IX Item "OBJECT, OID"
203 Encodes an \s-1ASN1 \s0\fB\s-1OBJECT IDENTIFIER\s0\fR, the \fBvalue\fR string can be
204 a short name, a long name or numerical format.
205 .IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
206 .IX Item "UTCTIME, UTC"
207 Encodes an \s-1ASN1 \s0\fBUTCTime\fR structure, the value should be in
208 the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
209 .IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
210 .IX Item "GENERALIZEDTIME, GENTIME"
211 Encodes an \s-1ASN1 \s0\fBGeneralizedTime\fR structure, the value should be in
212 the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
213 .IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
214 .IX Item "OCTETSTRING, OCT"
215 Encodes an \s-1ASN1 \s0\fB\s-1OCTET STRING\s0\fR. \fBvalue\fR represents the contents
216 of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
217 used to specify the format of \fBvalue\fR.
218 .IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
219 .IX Item "BITSTRING, BITSTR"
220 Encodes an \s-1ASN1 \s0\fB\s-1BIT STRING\s0\fR. \fBvalue\fR represents the contents
221 of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
222 can be used to specify the format of \fBvalue\fR.
224 If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
226 .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
227 .IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC"
228 These encode the corresponding string types. \fBvalue\fR represents the
229 contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
230 .IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
231 .IX Item "SEQUENCE, SEQ, SET"
232 Formats the result as an \s-1ASN1 \s0\fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
233 should be a section name which will contain the contents. The
234 field names in the section are ignored and the values are in the
235 generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
237 .SS "\s-1MODIFIERS\s0"
238 .IX Subsection "MODIFIERS"
239 Modifiers affect the following structure, they can be used to
240 add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
241 the string format of the final type and value. The supported
242 formats are documented below.
243 .IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
244 .IX Item "EXPLICIT, EXP"
245 Add an explicit tag to the following structure. This string
246 should be followed by a colon and the tag value to use as a
249 By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL,
250 APPLICATION, PRIVATE\s0 or \s-1CONTEXT SPECIFIC\s0 tagging can be used,
251 the default is \s-1CONTEXT SPECIFIC.\s0
252 .IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
253 .IX Item "IMPLICIT, IMP"
254 This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
256 .IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
257 .IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
258 The following structure is surrounded by an \s-1OCTET STRING,\s0 a \s-1SEQUENCE,\s0
259 a \s-1SET\s0 or a \s-1BIT STRING\s0 respectively. For a \s-1BIT STRING\s0 the number of unused
261 .IP "\fB\s-1FORMAT\s0\fR" 2
263 This specifies the format of the ultimate value. It should be followed
264 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.
266 If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
267 specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
268 output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT
269 STRING\s0) is a comma separated list of the indices of the set bits, all other
272 .IX Header "EXAMPLES"
276 \& IA5STRING:Hello World
279 An IA5String explicitly tagged:
282 \& EXPLICIT:0,IA5STRING:Hello World
285 An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
288 \& EXPLICIT:0A,IA5STRING:Hello World
291 A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
294 \& FORMAT:BITLIST,BITSTRING:1,5
297 A more complex example using a config file to produce a
298 \&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
301 \& asn1 = SEQUENCE:seq_section
305 \& field1 = BOOLEAN:TRUE
306 \& field2 = OID:commonName
307 \& field3 = UTF8:Third field
310 This example produces an RSAPrivateKey structure, this is the
311 key contained in the file client.pem in all OpenSSL distributions
312 (note: the field names such as 'coeff' are ignored and are present just
316 \& asn1=SEQUENCE:private_key
320 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
321 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
323 \& e=INTEGER:0x010001
325 \& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
326 \& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
328 \& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
331 \& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
334 \& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
337 \& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
340 \& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
344 This example is the corresponding public key in a SubjectPublicKeyInfo
348 \& # Start with a SEQUENCE
349 \& asn1=SEQUENCE:pubkeyinfo
351 \& # pubkeyinfo contains an algorithm identifier and the public key wrapped
354 \& algorithm=SEQUENCE:rsa_alg
355 \& pubkey=BITWRAP,SEQUENCE:rsapubkey
357 \& # algorithm ID for RSA is just an OID and a NULL
359 \& algorithm=OID:rsaEncryption
362 \& # Actual public key: modulus and exponent
364 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
365 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
367 \& e=INTEGER:0x010001
370 .IX Header "RETURN VALUES"
371 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
372 data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
374 The error codes that can be obtained by \fIERR_get_error\fR\|(3).
376 .IX Header "SEE ALSO"
377 \&\fIERR_get_error\fR\|(3)
380 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8