bdee4067c754bb7cb889a367d600d8add171a877
[openssl.git] / doc / crypto / ASN1_generate_nconf.pod
1 =pod
2
3 =head1 NAME
4
5 ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
6
7 =head1 SYNOPSIS
8
9  ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
10  ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
11
12 =head1 DESCRIPTION
13
14 These functions generate the ASN1 encoding of a string
15 in an B<ASN1_TYPE> structure.
16
17 B<str> contains the string to encode B<nconf> or B<cnf> contains
18 the optional configuration information where additional strings
19 will be read from. B<nconf> will typically come from a config
20 file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
21 which will typically be used by X509 v3 certificate extension
22 functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
23 configuration will be used.
24
25 =head1 GENERATION STRING FORMAT
26
27 The actual data encoded is determined by the string B<str> and
28 the configuration information. The general format of the string
29 is:
30
31  B<[modifier,]type[:value]>
32
33 That is zero or more comma separated modifiers followed by a type
34 followed by an optional colon and a value. The formats of B<type>,
35 B<value> and B<modifier> is explained below.
36
37 =head2 SUPPORTED TYPES
38
39 =over 2
40
41 =item B<BOOLEAN>, B<BOOL>
42
43 This encodes a boolean type. The B<value> string is mandatory and
44 should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
45 B<y>, B<YES>, B<yes>, B<FALSE> B<false>, B<N>, B<n>, B<NO> and B<no>
46 are acceptable. 
47
48 =item B<NULL>
49
50 Encode the B<NULL> type, the B<value> string must not be present.
51
52 =item B<INTEGER>, B<INT>
53
54 Encodes an ASN1 B<INTEGER> type. The B<value> string represents
55 the value of the integer, it can be preceeded by a minus sign and
56 is normally interpreted as a decimal value unless the prefix B<0x>
57 is included.
58
59 =item B<ENUMERATED>, B<ENUM>
60
61 Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
62 B<INTEGER>.
63
64 =item B<OBJECT>, B<OID>
65
66 Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
67 a short name, a long name or numerical format.
68
69 =item B<UTCTIME>, B<UTC>
70
71 Encodes an ASN1 B<UTCTime> structure, the value should be in
72 the format B<YYMMDDHHMMSSZ>. 
73
74 =item B<GENERALIZETIME>, B<GEN>
75
76 Encodes an ASN1 B<GeneralizeTime> structure, the value should be in
77 the format B<YYYYMMDDHHMMSSZ>. 
78
79 =item B<OCTETSTRING>, B<OCT>
80
81 Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents
82 of this structure, the format strings B<ASCII> and B<HEX> can be
83 used to specify the format of B<value>.
84
85 =item B<BITSRING>, B<BITSTR>
86
87 Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents
88 of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
89 can be used to specify the format of B<value>.
90
91 If the format is anything other than B<BITLIST> the number of unused
92 bits is set to zero.
93
94 =item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
95 B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
96 B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
97 B<T61STRING>, B<TELETEXSTRING>
98
99 These encode the corresponding string types. B<value> represents the
100 contents of this structure. The format can be B<ASCII> or B<UTF8>.
101
102 =item B<SEQUENCE>, B<SEQ>, B<SET>
103
104 Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
105 should be a section name which will contain the contents. The
106 field names are ignored and the values are in the generated
107 string format. If B<value> is absent the the content will be empty.
108
109 =cut
110
111 =head2 MODIFIERS
112
113 ...
114
115 =head1 RETURN VALUES
116
117 ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
118 data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
119
120 The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
121
122 X509_free() returns no value.
123
124 =head1 SEE ALSO
125
126 L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)>
127
128 =head1 HISTORY
129
130 ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
131
132 =cut