=head1 SYNOPSIS
- ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
- ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
+ #include <openssl/asn1.h>
+
+ ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
+ ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
=head1 DESCRIPTION
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
+file whereas 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.
the configuration information. The general format of the string
is:
- B<[modifier,]type[:value]>
+=over 2
+
+=item B<[modifier,]type[:value]>
+
+=back
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> are explained below.
-=head2 SUPPORTED TYPES
+=head2 Supported Types
The supported types are listed below. Unless otherwise specified
only the B<ASCII> format is permissible.
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.
+are acceptable.
=item B<NULL>
=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
+the value of the integer, it can be prefaced by a minus sign and
is normally interpreted as a decimal value unless the prefix B<0x>
is included.
=item B<UTCTIME>, B<UTC>
Encodes an ASN1 B<UTCTime> structure, the value should be in
-the format B<YYMMDDHHMMSSZ>.
+the format B<YYMMDDHHMMSSZ>.
=item B<GENERALIZEDTIME>, B<GENTIME>
Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
-the format B<YYYYMMDDHHMMSSZ>.
+the format B<YYYYMMDDHHMMSSZ>.
=item B<OCTETSTRING>, B<OCT>
-Emcodes an ASN1 B<OCTET STRING>. B<value> represents the contents
+Encodes 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>
+=item B<BITSTRING>, B<BITSTR>
-Emcodes an ASN1 B<BIT STRING>. B<value> represents the contents
+Encodes 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>.
=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>
+B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
+B<NUMERIC>
These encode the corresponding string types. B<value> represents the
contents of this structure. The format can be B<ASCII> or B<UTF8>.
=back
-=head2 MODIFIERS
+=head2 Modifiers
Modifiers affect the following structure, they can be used to
add EXPLICIT or IMPLICIT tagging, add wrappers or to change
This specifies the format of the ultimate value. It should be followed
by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
-If no format specifier is included then B<ASCII> is used. If B<UTF8> is specified
-then the value string must be a valid B<UTF8> string. For B<HEX> the output must
-be a set of hex digits. B<BITLIST> (which is only valid for a BIT STRING) is a
-comma separated list of set bits.
+If no format specifier is included then B<ASCII> is used. If B<UTF8> is
+specified then the value string must be a valid B<UTF8> string. For B<HEX> the
+output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT
+STRING) is a comma separated list of the indices of the set bits, all other
+bits are zero.
=back
EXPLICIT:0A,IA5STRING:Hello World
+A BITSTRING with bits 1 and 5 set and all others zero:
+
+ FORMAT:BITLIST,BITSTRING:1,5
+
A more complex example using a config file to produce a
-SEQUENCE consiting of a BOOL an OID and a UTF8String:
+SEQUENCE consisting of a BOOL an OID and a UTF8String:
-asn1 = SEQUENCE:seq_section
+ asn1 = SEQUENCE:seq_section
-[seq_section]
+ [seq_section]
-field1 = BOOLEAN:TRUE
-field2 = OID:commonName
-field3 = UTF8:Third field
+ field1 = BOOLEAN:TRUE
+ field2 = OID:commonName
+ field3 = UTF8:Third field
This example produces an RSAPrivateKey structure, this is the
key contained in the file client.pem in all OpenSSL distributions
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)>.
+The error codes that can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
-L<ERR_get_error(3)|ERR_get_error(3)>
+L<ERR_get_error(3)>
+
+=head1 COPYRIGHT
-=head1 HISTORY
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
=cut
projects / openssl.git / blobdiff