1 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.22)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
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<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
53 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 . \" simple accents for nroff and troff
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
124 .\" ========================================================================
126 .IX Title "ASN1_generate_nconf 3"
127 .TH ASN1_generate_nconf 3 "2012-05-10" "1.0.1c" "OpenSSL"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
133 ASN1_generate_nconf, ASN1_generate_v3 \- ASN1 generation functions
135 .IX Header "SYNOPSIS"
137 \& #include <openssl/asn1.h>
139 \& ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
140 \& ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
143 .IX Header "DESCRIPTION"
144 These functions generate the \s-1ASN1\s0 encoding of a string
145 in an \fB\s-1ASN1_TYPE\s0\fR structure.
147 \&\fBstr\fR contains the string to encode \fBnconf\fR or \fBcnf\fR contains
148 the optional configuration information where additional strings
149 will be read from. \fBnconf\fR will typically come from a config
150 file wherease \fBcnf\fR is obtained from an \fBX509V3_CTX\fR structure
151 which will typically be used by X509 v3 certificate extension
152 functions. \fBcnf\fR or \fBnconf\fR can be set to \fB\s-1NULL\s0\fR if no additional
153 configuration will be used.
154 .SH "GENERATION STRING FORMAT"
155 .IX Header "GENERATION STRING FORMAT"
156 The actual data encoded is determined by the string \fBstr\fR and
157 the configuration information. The general format of the string
159 .IP "\fB[modifier,]type[:value]\fR" 2
160 .IX Item "[modifier,]type[:value]"
162 That is zero or more comma separated modifiers followed by a type
163 followed by an optional colon and a value. The formats of \fBtype\fR,
164 \&\fBvalue\fR and \fBmodifier\fR are explained below.
165 .SS "\s-1SUPPORTED\s0 \s-1TYPES\s0"
166 .IX Subsection "SUPPORTED TYPES"
167 The supported types are listed below. Unless otherwise specified
168 only the \fB\s-1ASCII\s0\fR format is permissible.
169 .IP "\fB\s-1BOOLEAN\s0\fR, \fB\s-1BOOL\s0\fR" 2
170 .IX Item "BOOLEAN, BOOL"
171 This encodes a boolean type. The \fBvalue\fR string is mandatory and
172 should be \fB\s-1TRUE\s0\fR or \fB\s-1FALSE\s0\fR. Additionally \fB\s-1TRUE\s0\fR, \fBtrue\fR, \fBY\fR,
173 \&\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
175 .IP "\fB\s-1NULL\s0\fR" 2
177 Encode the \fB\s-1NULL\s0\fR type, the \fBvalue\fR string must not be present.
178 .IP "\fB\s-1INTEGER\s0\fR, \fB\s-1INT\s0\fR" 2
179 .IX Item "INTEGER, INT"
180 Encodes an \s-1ASN1\s0 \fB\s-1INTEGER\s0\fR type. The \fBvalue\fR string represents
181 the value of the integer, it can be preceeded by a minus sign and
182 is normally interpreted as a decimal value unless the prefix \fB0x\fR
184 .IP "\fB\s-1ENUMERATED\s0\fR, \fB\s-1ENUM\s0\fR" 2
185 .IX Item "ENUMERATED, ENUM"
186 Encodes the \s-1ASN1\s0 \fB\s-1ENUMERATED\s0\fR type, it is otherwise identical to
187 \&\fB\s-1INTEGER\s0\fR.
188 .IP "\fB\s-1OBJECT\s0\fR, \fB\s-1OID\s0\fR" 2
189 .IX Item "OBJECT, OID"
190 Encodes an \s-1ASN1\s0 \fB\s-1OBJECT\s0 \s-1IDENTIFIER\s0\fR, the \fBvalue\fR string can be
191 a short name, a long name or numerical format.
192 .IP "\fB\s-1UTCTIME\s0\fR, \fB\s-1UTC\s0\fR" 2
193 .IX Item "UTCTIME, UTC"
194 Encodes an \s-1ASN1\s0 \fBUTCTime\fR structure, the value should be in
195 the format \fB\s-1YYMMDDHHMMSSZ\s0\fR.
196 .IP "\fB\s-1GENERALIZEDTIME\s0\fR, \fB\s-1GENTIME\s0\fR" 2
197 .IX Item "GENERALIZEDTIME, GENTIME"
198 Encodes an \s-1ASN1\s0 \fBGeneralizedTime\fR structure, the value should be in
199 the format \fB\s-1YYYYMMDDHHMMSSZ\s0\fR.
200 .IP "\fB\s-1OCTETSTRING\s0\fR, \fB\s-1OCT\s0\fR" 2
201 .IX Item "OCTETSTRING, OCT"
202 Encodes an \s-1ASN1\s0 \fB\s-1OCTET\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
203 of this structure, the format strings \fB\s-1ASCII\s0\fR and \fB\s-1HEX\s0\fR can be
204 used to specify the format of \fBvalue\fR.
205 .IP "\fB\s-1BITSTRING\s0\fR, \fB\s-1BITSTR\s0\fR" 2
206 .IX Item "BITSTRING, BITSTR"
207 Encodes an \s-1ASN1\s0 \fB\s-1BIT\s0 \s-1STRING\s0\fR. \fBvalue\fR represents the contents
208 of this structure, the format strings \fB\s-1ASCII\s0\fR, \fB\s-1HEX\s0\fR and \fB\s-1BITLIST\s0\fR
209 can be used to specify the format of \fBvalue\fR.
211 If the format is anything other than \fB\s-1BITLIST\s0\fR the number of unused
213 .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
214 .IX Item "UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC"
215 These encode the corresponding string types. \fBvalue\fR represents the
216 contents of this structure. The format can be \fB\s-1ASCII\s0\fR or \fB\s-1UTF8\s0\fR.
217 .IP "\fB\s-1SEQUENCE\s0\fR, \fB\s-1SEQ\s0\fR, \fB\s-1SET\s0\fR" 2
218 .IX Item "SEQUENCE, SEQ, SET"
219 Formats the result as an \s-1ASN1\s0 \fB\s-1SEQUENCE\s0\fR or \fB\s-1SET\s0\fR type. \fBvalue\fR
220 should be a section name which will contain the contents. The
221 field names in the section are ignored and the values are in the
222 generated string format. If \fBvalue\fR is absent then an empty \s-1SEQUENCE\s0
224 .SS "\s-1MODIFIERS\s0"
225 .IX Subsection "MODIFIERS"
226 Modifiers affect the following structure, they can be used to
227 add \s-1EXPLICIT\s0 or \s-1IMPLICIT\s0 tagging, add wrappers or to change
228 the string format of the final type and value. The supported
229 formats are documented below.
230 .IP "\fB\s-1EXPLICIT\s0\fR, \fB\s-1EXP\s0\fR" 2
231 .IX Item "EXPLICIT, EXP"
232 Add an explicit tag to the following structure. This string
233 should be followed by a colon and the tag value to use as a
236 By following the number with \fBU\fR, \fBA\fR, \fBP\fR or \fBC\fR \s-1UNIVERSAL\s0,
237 \&\s-1APPLICATION\s0, \s-1PRIVATE\s0 or \s-1CONTEXT\s0 \s-1SPECIFIC\s0 tagging can be used,
238 the default is \s-1CONTEXT\s0 \s-1SPECIFIC\s0.
239 .IP "\fB\s-1IMPLICIT\s0\fR, \fB\s-1IMP\s0\fR" 2
240 .IX Item "IMPLICIT, IMP"
241 This is the same as \fB\s-1EXPLICIT\s0\fR except \s-1IMPLICIT\s0 tagging is used
243 .IP "\fB\s-1OCTWRAP\s0\fR, \fB\s-1SEQWRAP\s0\fR, \fB\s-1SETWRAP\s0\fR, \fB\s-1BITWRAP\s0\fR" 2
244 .IX Item "OCTWRAP, SEQWRAP, SETWRAP, BITWRAP"
245 The following structure is surrounded by an \s-1OCTET\s0 \s-1STRING\s0, a \s-1SEQUENCE\s0,
246 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
248 .IP "\fB\s-1FORMAT\s0\fR" 2
250 This specifies the format of the ultimate value. It should be followed
251 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.
253 If no format specifier is included then \fB\s-1ASCII\s0\fR is used. If \fB\s-1UTF8\s0\fR is
254 specified then the value string must be a valid \fB\s-1UTF8\s0\fR string. For \fB\s-1HEX\s0\fR the
255 output must be a set of hex digits. \fB\s-1BITLIST\s0\fR (which is only valid for a \s-1BIT\s0
256 \&\s-1STRING\s0) is a comma separated list of the indices of the set bits, all other
259 .IX Header "EXAMPLES"
263 \& IA5STRING:Hello World
266 An IA5String explicitly tagged:
269 \& EXPLICIT:0,IA5STRING:Hello World
272 An IA5String explicitly tagged using \s-1APPLICATION\s0 tagging:
275 \& EXPLICIT:0A,IA5STRING:Hello World
278 A \s-1BITSTRING\s0 with bits 1 and 5 set and all others zero:
281 \& FORMAT:BITLIST,BITSTRING:1,5
284 A more complex example using a config file to produce a
285 \&\s-1SEQUENCE\s0 consiting of a \s-1BOOL\s0 an \s-1OID\s0 and a UTF8String:
288 \& asn1 = SEQUENCE:seq_section
292 \& field1 = BOOLEAN:TRUE
293 \& field2 = OID:commonName
294 \& field3 = UTF8:Third field
297 This example produces an RSAPrivateKey structure, this is the
298 key contained in the file client.pem in all OpenSSL distributions
299 (note: the field names such as 'coeff' are ignored and are present just
303 \& asn1=SEQUENCE:private_key
307 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
308 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
310 \& e=INTEGER:0x010001
312 \& d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\e
313 \& F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
315 \& p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\e
318 \& q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\e
321 \& exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\e
324 \& exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\e
327 \& coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\e
331 This example is the corresponding public key in a SubjectPublicKeyInfo
335 \& # Start with a SEQUENCE
336 \& asn1=SEQUENCE:pubkeyinfo
338 \& # pubkeyinfo contains an algorithm identifier and the public key wrapped
341 \& algorithm=SEQUENCE:rsa_alg
342 \& pubkey=BITWRAP,SEQUENCE:rsapubkey
344 \& # algorithm ID for RSA is just an OID and a NULL
346 \& algorithm=OID:rsaEncryption
349 \& # Actual public key: modulus and exponent
351 \& n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\e
352 \& D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
354 \& e=INTEGER:0x010001
357 .IX Header "RETURN VALUES"
358 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR return the encoded
359 data as an \fB\s-1ASN1_TYPE\s0\fR structure or \fB\s-1NULL\s0\fR if an error occurred.
361 The error codes that can be obtained by \fIERR_get_error\fR\|(3).
363 .IX Header "SEE ALSO"
364 \&\fIERR_get_error\fR\|(3)
367 \&\fIASN1_generate_nconf()\fR and \fIASN1_generate_v3()\fR were added to OpenSSL 0.9.8