=pod

=head1 NAME

ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions

=head1 SYNOPSIS

 ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
 ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);

=head1 DESCRIPTION

These functions generate the ASN1 encoding of a string
in an B<ASN1_TYPE> structure.

B<str> contains the string to encode B<nconf> or B<cnf> contains
the optional configuration information where additional strings
will be read from. B<nconf> will typically come from a config
file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
which will typically be used by X509 v3 certificate extension
functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
configuration will be used.

=head1 GENERATION STRING FORMAT

The actual data encoded is determined by the string B<str> and
the configuration information. The general format of the string
is:

 B<[modifier,]type[:value]>

That is zero or more comma separated modifiers followed by a type
followed by an optional colon and a value. The formats of B<type>,
B<value> and B<modifier> is explained below.

=head2 SUPPORTED TYPES

=over 2

=item B<BOOLEAN>, B<BOOL>

This encodes a boolean type. The B<value> string is mandatory and
should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
B<y>, B<YES>, B<yes>, B<FALSE> B<false>, B<N>, B<n>, B<NO> and B<no>
are acceptable. 

=item B<NULL>

Encode the B<NULL> type, the B<value> string must not be present.

=item B<INTEGER>, B<INT>

Encodes an ASN1 B<INTEGER> type. The B<value> string represents
the value of the integer, it can be preceeded by a minus sign and
is normally interpreted as a decimal value unless the prefix B<0x>
is included.

=item B<ENUMERATED>, B<ENUM>

Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
B<INTEGER>.

=item B<OBJECT>, B<OID>

Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
a short name, a long name or numerical format.

=item B<UTCTIME>, B<UTC>

Encodes an ASN1 B<UTCTime> structure, the value should be in
the format B<YYMMDDHHMMSSZ>. 

=item B<GENERALIZETIME>, B<GEN>

Encodes an ASN1 B<GeneralizeTime> structure, the value should be in
the format B<YYYYMMDDHHMMSSZ>. 

=item B<OCTETSTRING>, B<OCT>

Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents
of this structure, the format strings B<ASCII> and B<HEX> can be
used to specify the format of B<value>.

=item B<BITSRING>, B<BITSTR>

Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents
of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
can be used to specify the format of B<value>.

If the format is anything other than B<BITLIST> the number of unused
bits is set to zero.

=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
B<T61STRING>, B<TELETEXSTRING>

These encode the corresponding string types. B<value> represents the
contents of this structure. The format can be B<ASCII> or B<UTF8>.

=item B<SEQUENCE>, B<SEQ>, B<SET>

Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
should be a section name which will contain the contents. The
field names are ignored and the values are in the generated
string format. If B<value> is absent the the content will be empty.

=cut

=head2 MODIFIERS

...

=head1 RETURN VALUES

ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.

The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.

X509_free() returns no value.

=head1 SEE ALSO

L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)>

=head1 HISTORY

ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8

=cut