1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), 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.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "ASN1_generate_nconf 3"
132 .TH ASN1_generate_nconf 3 "2010-03-24" "0.9.8n" "OpenSSL"
134 ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
136 .IX Header "SYNOPSIS"
138 \& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
139 \& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
142 .IX Header "DESCRIPTION"
143 These functions generate the \s-1ASN1\s0 encoding of a string
144 in an \fB\s-1ASN1_TYPE\s0\fR structure.
146 \&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
147 the optional configuration information where additional strings
148 will be read from. \fBnconf\fR will typically come from a config
149 file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
150 which will typically be used by X509 v3 certificate extension
151 functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
152 configuration will be used.
153 .SH "GENERATION STRING FORMAT"
154 .IX Header "GENERATION STRING FORMAT"
155 The actual data encoded is determined by the string \fBstr\fR and
156 the configuration information. The general format of the string
158 .IP "\fB[modifier,]type[:value]\fR" 2
159 .IX Item "[modifier,]type[:value]"
161 That is zero or more comma separated modifiers followed by a type
162 followed by an optional colon and a value. The formats of \fBtype\fR,
163 \&\fBvalue\fR and \fBmodifier\fR are explained below.
164 .Sh "\s-1SUPPORTED\s0 \s-1TYPES\s0"
165 .IX Subsection "SUPPORTED TYPES"
166 The supported types are listed below. Unless otherwise specified
167 only the \fB\s-1ASCII\s0\fR format is permissible.
168 .IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
169 .IX Item "BOOLEAN, BOOL"
170 This encodes a boolean type. The \fBvalue\fR string is mandatory and
171 should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
172 \&\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
174 .IP "\fB\s-1NULL\s0\fR" 2
176 Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
177 .IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
178 .IX Item "INTEGER, INT"
179 Encodes an \s-1ASN1\s0 \fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
180 the value of the integer, it can be preceeded by a minus sign and
181 is normally interpreted as a decimal value unless the prefix \fB0x\fR
183 .IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
184 .IX Item "ENUMERATED, ENUM"
185 Encodes the \s-1ASN1\s0 \fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
186 \&\fB\s-1INTEGER\s0\fR.
187 .IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
188 .IX Item "OBJECT, OID"
189 Encodes an \s-1ASN1\s0 \fB\s-1OBJECT\s0 \s-1IDENTIFIER\s0\fR, the \fBvalue\fR string can be
190 a short name, a long name or numerical format.
191 .IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
192 .IX Item "UTCTIME, UTC"
193 Encodes an \s-1ASN1\s0 \fBUTCTime\fR structure, the value should be in
194 the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
195 .IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
196 .IX Item "GENERALIZEDTIME, GENTIME"
197 Encodes an \s-1ASN1\s0 \fBGeneralizedTime\fR structure, the value should be in
198 the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
199 .IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
200 .IX Item "OCTETSTRING, OCT"
201 Encodes an \s-1ASN1\s0 \fB\s-1OCTET\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
202 of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
203 used to specify the format of \fBvalue\fR.
204 .IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
205 .IX Item "BITSTRING, BITSTR"
206 Encodes an \s-1ASN1\s0 \fB\s-1BIT\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
207 of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
208 can be used to specify the format of \fBvalue\fR.
210 If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
212 .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" 2
213 .IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString"
214 These encode the corresponding string types. \fBvalue\fR represents the
215 contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
216 .IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
217 .IX Item "SEQUENCE, SEQ, SET"
218 Formats the result as an \s-1ASN1\s0 \fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
219 should be a section name which will contain the contents. The
220 field names in the section are ignored and the values are in the
221 generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
223 .Sh "\s-1MODIFIERS\s0"
224 .IX Subsection "MODIFIERS"
225 Modifiers affect the following structure, they can be used to
226 add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
227 the string format of the final type and value. The supported
228 formats are documented below.
229 .IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
230 .IX Item "EXPLICIT, EXP"
231 Add an explicit tag to the following structure. This string
232 should be followed by a colon and the tag value to use as a
235 By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL\s0,
236 \&\s-1APPLICATION\s0, \s-1PRIVATE\s0 or \s-1CONTEXT\s0 \s-1SPECIFIC\s0 tagging can be used,
237 the default is \s-1CONTEXT\s0 \s-1SPECIFIC\s0.
238 .IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
239 .IX Item "IMPLICIT, IMP"
240 This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
242 .IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
243 .IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
244 The following structure is surrounded by an \s-1OCTET\s0 \s-1STRING\s0, a \s-1SEQUENCE\s0,
245 a \s-1SET\s0 or a \s-1BIT\s0 \s-1STRING\s0 respectively. For a \s-1BIT\s0 \s-1STRING\s0 the number of unused
247 .IP "\fB\s-1FORMAT\s0\fR" 2
249 This specifies the format of the ultimate value. It should be followed
250 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.
252 If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
253 specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
254 output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT\s0
255 \&\s-1STRING\s0) is a comma separated list of the indices of the set bits, all other
258 .IX Header "EXAMPLES"
262 \& IA5STRING:Hello World
265 An IA5String explicitly tagged:
268 \& EXPLICIT:0,IA5STRING:Hello World
271 An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
274 \& EXPLICIT:0A,IA5STRING:Hello World
277 A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
280 \& FORMAT:BITLIST,BITSTRING:1,5
283 A more complex example using a config file to produce a
284 \&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
287 \& asn1 = SEQUENCE:seq_section
295 \& field1 = BOOLEAN:TRUE
296 \& field2 = OID:commonName
297 \& field3 = UTF8:Third field
300 This example produces an RSAPrivateKey structure, this is the
301 key contained in the file client.pem in all OpenSSL distributions
302 (note: the field names such as 'coeff' are ignored and are present just
306 \& asn1=SEQUENCE:private_key
312 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
313 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
317 \& e=INTEGER:0x010001
321 \& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
322 \& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
326 \& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
331 \& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
336 \& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
341 \& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
346 \& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
350 This example is the corresponding public key in a SubjectPublicKeyInfo
354 \& # Start with a SEQUENCE
355 \& asn1=SEQUENCE:pubkeyinfo
359 \& # pubkeyinfo contains an algorithm identifier and the public key wrapped
362 \& algorithm=SEQUENCE:rsa_alg
363 \& pubkey=BITWRAP,SEQUENCE:rsapubkey
367 \& # algorithm ID for RSA is just an OID and a NULL
369 \& algorithm=OID:rsaEncryption
374 \& # Actual public key: modulus and exponent
376 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
377 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
381 \& e=INTEGER:0x010001
384 .IX Header "RETURN VALUES"
385 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
386 data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
388 The error codes that can be obtained by \fIERR_get_error\fR\|(3).
390 .IX Header "SEE ALSO"
391 \&\fIERR_get_error\fR\|(3)
394 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8