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
+I<str> contains the string to encode I<nconf> or I<cnf> contains
the optional configuration information where additional strings
-will be read from. B<nconf> will typically come from a config
-file whereas B<cnf> is obtained from an B<X509V3_CTX> structure
+will be read from. I<nconf> will typically come from a config
+file whereas I<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
+functions. I<cnf> or I<nconf> can be set to 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 actual data encoded is determined by the string I<str> and
the configuration information. The general format of the string
is:
=over 4
-=item B<[modifier,]type[:value]>
+=item [I<modifier>,]I<type>[:I<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.
+followed by an optional colon and a value. The formats of I<type>,
+I<value> and I<modifier> are explained below.
=head2 Supported Types
=item B<BOOLEAN>, B<BOOL>
-This encodes a boolean type. The B<value> string is mandatory and
+This encodes a boolean type. The I<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.
+Encode the B<NULL> type, the I<value> string must not be present.
=item B<INTEGER>, B<INT>
-Encodes an ASN1 B<INTEGER> type. The B<value> string represents
+Encodes an ASN1 B<INTEGER> type. The I<value> string represents
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<OBJECT>, B<OID>
-Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
+Encodes an ASN1 B<OBJECT IDENTIFIER>, the I<value> string can be
a short name, a long name or numerical format.
=item B<UTCTIME>, B<UTC>
=item B<OCTETSTRING>, B<OCT>
-Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents
+Encodes an ASN1 B<OCTET STRING>. I<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>.
+used to specify the format of I<value>.
=item B<BITSTRING>, B<BITSTR>
-Encodes an ASN1 B<BIT STRING>. B<value> represents the contents
+Encodes an ASN1 B<BIT STRING>. I<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>.
+can be used to specify the format of I<value>.
If the format is anything other than B<BITLIST> the number of unused
bits is set to zero.
B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
B<NUMERIC>
-These encode the corresponding string types. B<value> represents the
+These encode the corresponding string types. I<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>
+Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. I<value>
should be a section name which will contain the contents. The
field names in the section are ignored and the values are in the
-generated string format. If B<value> is absent then an empty SEQUENCE
+generated string format. If I<value> is absent then an empty SEQUENCE
will be encoded.
=back
=back
+=head1 RETURN VALUES
+
+ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
+data as an B<ASN1_TYPE> structure or NULL if an error occurred.
+
+The error codes that can be obtained by L<ERR_get_error(3)>.
+
=head1 EXAMPLES
A simple IA5String:
e=INTEGER:0x010001
-=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)>.
-
=head1 SEE ALSO
L<ERR_get_error(3)>
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+Licensed under the Apache License 2.0 (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>.
projects / openssl.git / blobdiff