structures.
ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type
-If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails
+If successful it returns 1 and sets I<*pr> to the value of I<a>. If it fails
(due to invalid type or the value being too big to fit into an B<int64_t> type)
it returns 0.
converts to a B<uint64_t> type and an error is returned if the passed integer
is negative.
-ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is
+ASN1_INTEGER_get() also returns the value of I<a> but it returns 0 if I<a> is
NULL and -1 on error (which is ambiguous because -1 is a legitimate value for
an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64()
instead.
-ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the
-B<int64_t> value B<r>.
+ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> I<a> to the
+B<int64_t> value I<r>.
-ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> B<a> to the
-B<uint64_t> value B<r>.
+ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> I<a> to the
+B<uint64_t> value I<r>.
-ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value
-B<v>.
+ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> I<a> to the I<long> value
+I<v>.
-BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai>
-is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then
+BN_to_ASN1_INTEGER() converts B<BIGNUM> I<bn> to an B<ASN1_INTEGER>. If I<ai>
+is NULL a new B<ASN1_INTEGER> structure is returned. If I<ai> is not NULL then
the existing structure will be used instead.
-ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is
-NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the
+ASN1_INTEGER_to_BN() converts ASN1_INTEGER I<ai> into a B<BIGNUM>. If I<bn> is
+NULL a new B<BIGNUM> structure is returned. If I<bn> is not NULL then the
existing structure will be used instead.
ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(),
behave in an identical way to their ASN1_INTEGER counterparts except they
operate on an B<ASN1_ENUMERATED> value.
-ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to
-ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not
+ASN1_ENUMERATED_get() returns the value of I<a> in a similar way to
+ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of I<a> will not
fit in a long type. New applications should use ASN1_ENUMERATED_get_int64()
instead.
=head1 DESCRIPTION
-ASN1_ITEM_lookup() returns the B<ASN1_ITEM name>.
+ASN1_ITEM_lookup() returns the B<ASN1_ITEM> named I<name>.
-ASN1_ITEM_get() returns the B<ASN1_ITEM> with index B<i>. This function
-returns B<NULL> if the index B<i> is out of range.
+ASN1_ITEM_get() returns the B<ASN1_ITEM> with index I<i>. This function
+returns NULL if the index I<i> is out of range.
=head1 RETURN VALUES
ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid B<ASN1_ITEM> structure
-or B<NULL> if an error occurred.
+or NULL if an error occurred.
=head1 SEE ALSO
=head1 DESCRIPTION
-The ASN1_OBJECT allocation routines, allocate and free an
-ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
+The B<ASN1_OBJECT> allocation routines, allocate and free an
+B<ASN1_OBJECT> structure, which represents an ASN1 OBJECT IDENTIFIER.
-ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.
+ASN1_OBJECT_new() allocates and initializes an B<ASN1_OBJECT> structure.
-ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
-If B<a> is NULL, nothing is done.
+ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure I<a>.
+If I<a> is NULL, nothing is done.
=head1 NOTES
-Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
+Although ASN1_OBJECT_new() allocates a new B<ASN1_OBJECT> structure it
is almost never used in applications. The ASN1 object utility functions
such as OBJ_nid2obj() are used instead.
=head1 RETURN VALUES
-If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
+If the allocation fails, ASN1_OBJECT_new() returns NULL and sets an error
code that can be obtained by L<ERR_get_error(3)>.
Otherwise it returns a pointer to the newly allocated structure.
=head2 Functions
ASN1_STRING_TABLE_add() adds a new B<ASN1_STRING_TABLE> item into the
-local ASN1 string table based on the B<nid> along with other parameters.
+local ASN1 string table based on the I<nid> along with other parameters.
If the item is already in the table, fields of B<ASN1_STRING_TABLE> are
-updated (depending on the values of those parameters, e.g., B<minsize>
-and B<maxsize> >= 0, B<mask> and B<flags> != 0). If the B<nid> is standard,
+updated (depending on the values of those parameters, e.g., I<minsize>
+and I<maxsize> >= 0, I<mask> and I<flags> != 0). If the I<nid> is standard,
a copy of the standard B<ASN1_STRING_TABLE> is created and updated with
other parameters.
ASN1_STRING_TABLE_get() searches for an B<ASN1_STRING_TABLE> item based
-on B<nid>. It will search the local table first, then the standard one.
+on I<nid>. It will search the local table first, then the standard one.
ASN1_STRING_TABLE_cleanup() frees all B<ASN1_STRING_TABLE> items added
by ASN1_STRING_TABLE_add().
ASN1_STRING_TABLE_add() returns 1 on success, 0 if an error occurred.
ASN1_STRING_TABLE_get() returns a valid B<ASN1_STRING_TABLE> structure
-or B<NULL> if nothing is found.
+or NULL if nothing is found.
ASN1_STRING_TABLE_cleanup() does not return a value.
These functions allow an B<ASN1_STRING> structure to be manipulated.
-ASN1_STRING_length() returns the length of the content of B<x>.
+ASN1_STRING_length() returns the length of the content of I<x>.
-ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>.
+ASN1_STRING_get0_data() returns an internal pointer to the data of I<x>.
Since this is an internal pointer it should B<not> be freed or
modified in any way.
returned value is not constant. This function is deprecated:
applications should use ASN1_STRING_get0_data() instead.
-ASN1_STRING_dup() returns a copy of the structure B<a>.
+ASN1_STRING_dup() returns a copy of the structure I<a>.
-ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
+ASN1_STRING_cmp() compares I<a> and I<b> returning 0 if the two
are identical. The string types and content are compared.
-ASN1_STRING_set() sets the data of string B<str> to the buffer
-B<data> or length B<len>. The supplied data is copied. If B<len>
+ASN1_STRING_set() sets the data of string I<str> to the buffer
+I<data> or length I<len>. The supplied data is copied. If I<len>
is -1 then the length is determined by strlen(data).
-ASN1_STRING_type() returns the type of B<x>, using standard constants
+ASN1_STRING_type() returns the type of I<x>, using standard constants
such as B<V_ASN1_OCTET_STRING>.
-ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
-converted data is allocated in a buffer in B<*out>. The length of
-B<out> is returned or a negative error code. The buffer B<*out>
+ASN1_STRING_to_UTF8() converts the string I<in> to UTF8 format, the
+converted data is allocated in a buffer in I<*out>. The length of
+I<out> is returned or a negative error code. The buffer I<*out>
should be freed using OPENSSL_free().
=head1 NOTES
=head1 RETURN VALUES
-ASN1_STRING_length() returns the length of the content of B<x>.
+ASN1_STRING_length() returns the length of the content of I<x>.
ASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to
-the data of B<x>.
+the data of I<x>.
-ASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or B<NULL> if an
+ASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or NULL if an
error occurred.
ASN1_STRING_cmp() returns an integer greater than, equal to, or less than 0,
-according to whether B<a> is greater than, equal to, or less than B<b>.
+according to whether I<a> is greater than, equal to, or less than I<b>.
ASN1_STRING_set() returns 1 on success or 0 on error.
-ASN1_STRING_type() returns the type of B<x>.
+ASN1_STRING_type() returns the type of I<x>.
-ASN1_STRING_to_UTF8() returns the number of bytes in output string B<out> or a
+ASN1_STRING_to_UTF8() returns the number of bytes in output string I<out> or a
negative value if an error occurred.
=head1 SEE ALSO
is undefined.
ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
-type B<type>.
+type I<type>.
-ASN1_STRING_free() frees up B<a>.
-If B<a> is NULL nothing is done.
+ASN1_STRING_free() frees up I<a>.
+If I<a> is NULL nothing is done.
=head1 NOTES
=head1 RETURN VALUES
ASN1_STRING_new() and ASN1_STRING_type_new() return a valid
-ASN1_STRING structure or B<NULL> if an error occurred.
+B<ASN1_STRING> structure or NULL if an error occurred.
ASN1_STRING_free() does not return a value.
These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to
represent all the ASN1 string types.
-ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by
-the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
-to B<fp> instead.
+ASN1_STRING_print_ex() outputs I<str> to I<out>, the format is determined by
+the options I<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
+to I<fp> instead.
-ASN1_STRING_print() prints B<str> to B<out> but using a different format to
+ASN1_STRING_print() prints I<str> to I<out> but using a different format to
ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)
with '.'.
-ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
+ASN1_tag2str() returns a human-readable name of the specified ASN.1 I<tag>.
=head1 NOTES
Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
-The complete set of supported options for B<flags> is listed below.
+The complete set of supported options for I<flags> is listed below.
Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters
determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control
ASN1_STRING_print() returns 1 on success or 0 on error.
-ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
+ASN1_tag2str() returns a human-readable name of the specified ASN.1 I<tag>.
=head1 SEE ALSO
=head1 DESCRIPTION
The ASN1_TIME_set(), ASN1_UTCTIME_set() and ASN1_GENERALIZEDTIME_set()
-functions set the structure B<s> to the time represented by the time_t
-value B<t>. If B<s> is NULL a new time structure is allocated and returned.
+functions set the structure I<s> to the time represented by the time_t
+value I<t>. If I<s> is NULL a new time structure is allocated and returned.
The ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_adj()
-functions set the time structure B<s> to the time represented
-by the time B<offset_day> and B<offset_sec> after the time_t value B<t>.
-The values of B<offset_day> or B<offset_sec> can be negative to set a
-time before B<t>. The B<offset_sec> value can also exceed the number of
-seconds in a day. If B<s> is NULL a new structure is allocated
+functions set the time structure I<s> to the time represented
+by the time I<offset_day> and I<offset_sec> after the time_t value I<t>.
+The values of I<offset_day> or I<offset_sec> can be negative to set a
+time before I<t>. The I<offset_sec> value can also exceed the number of
+seconds in a day. If I<s> is NULL a new structure is allocated
and returned.
The ASN1_TIME_set_string(), ASN1_UTCTIME_set_string() and
-ASN1_GENERALIZEDTIME_set_string() functions set the time structure B<s>
-to the time represented by string B<str> which must be in appropriate ASN.1
-time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If B<s> is NULL
-this function performs a format check on B<str> only. The string B<str>
-is copied into B<s>.
-
-ASN1_TIME_set_string_X509() sets ASN1_TIME structure B<s> to the time
-represented by string B<str> which must be in appropriate time format
+ASN1_GENERALIZEDTIME_set_string() functions set the time structure I<s>
+to the time represented by string I<str> which must be in appropriate ASN.1
+time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If I<s> is NULL
+this function performs a format check on I<str> only. The string I<str>
+is copied into I<s>.
+
+ASN1_TIME_set_string_X509() sets B<ASN1_TIME> structure I<s> to the time
+represented by string I<str> which must be in appropriate time format
that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and
YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format
-are not allowed. If B<s> is NULL this function performs a format check
-on B<str> only.
+are not allowed. If I<s> is NULL this function performs a format check
+on I<str> only.
-The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or
-ASN1_UTCTIME into a time value that can be used in a certificate. It
+The ASN1_TIME_normalize() function converts an B<ASN1_GENERALIZEDTIME> or
+B<ASN1_UTCTIME> into a time value that can be used in a certificate. It
should be used after the ASN1_TIME_set_string() functions and before
ASN1_TIME_print() functions to get consistent (i.e. GMT) results.
The ASN1_TIME_check(), ASN1_UTCTIME_check() and ASN1_GENERALIZEDTIME_check()
-functions check the syntax of the time structure B<s>.
+functions check the syntax of the time structure I<s>.
The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print()
-functions print the time structure B<s> to BIO B<b> in human readable
+functions print the time structure I<s> to BIO I<b> in human readable
format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example
"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time
structure has invalid format it prints out "Bad time value" and returns
an error. The output for generalized time may include a fractional part
following the second.
-ASN1_TIME_to_tm() converts the time B<s> to the standard B<tm> structure.
-If B<s> is NULL, then the current time is converted. The output time is GMT.
-The B<tm_sec>, B<tm_min>, B<tm_hour>, B<tm_mday>, B<tm_wday>, B<tm_yday>,
-B<tm_mon> and B<tm_year> fields of B<tm> structure are set to proper values,
-whereas all other fields are set to 0. If B<tm> is NULL this function performs
-a format check on B<s> only. If B<s> is in Generalized format with fractional
+ASN1_TIME_to_tm() converts the time I<s> to the standard I<tm> structure.
+If I<s> is NULL, then the current time is converted. The output time is GMT.
+The I<tm_sec>, I<tm_min>, I<tm_hour>, I<tm_mday>, I<tm_wday>, I<tm_yday>,
+I<tm_mon> and I<tm_year> fields of I<tm> structure are set to proper values,
+whereas all other fields are set to 0. If I<tm> is NULL this function performs
+a format check on I<s> only. If I<s> is in Generalized format with fractional
seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while
-converting B<s> to B<tm> structure.
-
-ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
-B<from> and B<to>. If B<to> represents a time later than B<from> then
-one or both (depending on the time difference) of B<*pday> and B<*psec>
-will be positive. If B<to> represents a time earlier than B<from> then
-one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from>
-represent the same time then B<*pday> and B<*psec> will both be zero.
-If both B<*pday> and B<*psec> are non-zero they will always have the same
-sign. The value of B<*psec> will always be less than the number of seconds
-in a day. If B<from> or B<to> is NULL the current time is used.
+converting I<s> to I<tm> structure.
+
+ASN1_TIME_diff() sets I<*pday> and I<*psec> to the time difference between
+I<from> and I<to>. If I<to> represents a time later than I<from> then
+one or both (depending on the time difference) of I<*pday> and I<*psec>
+will be positive. If I<to> represents a time earlier than I<from> then
+one or both of I<*pday> and I<*psec> will be negative. If I<to> and I<from>
+represent the same time then I<*pday> and I<*psec> will both be zero.
+If both I<*pday> and I<*psec> are non-zero they will always have the same
+sign. The value of I<*psec> will always be less than the number of seconds
+in a day. If I<from> or I<to> is NULL the current time is used.
The ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() functions compare
-the two times represented by the time structure B<s> and the time_t B<t>.
+the two times represented by the time structure I<s> and the time_t I<t>.
The ASN1_TIME_compare() function compares the two times represented by the
-time structures B<a> and B<b>.
+time structures I<a> and I<b>.
-The ASN1_TIME_to_generalizedtime() function converts an ASN1_TIME to an
-ASN1_GENERALIZEDTIME, regardless of year. If either B<out> or
-B<*out> are NULL, then a new object is allocated and must be freed after use.
+The ASN1_TIME_to_generalizedtime() function converts an B<ASN1_TIME> to an
+B<ASN1_GENERALIZEDTIME>, regardless of year. If either I<out> or
+I<*out> are NULL, then a new object is allocated and must be freed after use.
=head1 NOTES
-The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
+The B<ASN1_TIME> structure corresponds to the ASN.1 structure B<Time>
defined in RFC5280 et al. The time setting functions obey the rules outlined
in RFC5280: if the date can be represented by UTCTime it is used, else
GeneralizedTime is used.
-The ASN1_TIME, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented
-as an ASN1_STRING internally and can be freed up using ASN1_STRING_free().
+The B<ASN1_TIME>, B<ASN1_UTCTIME> and B<ASN1_GENERALIZEDTIME> structures are
+represented as an B<ASN1_STRING> internally and can be freed up using
+ASN1_STRING_free().
-The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt
+The B<ASN1_TIME> structure can represent years from 0000 to 9999 but no attempt
is made to correct ancient calendar changes (for example from Julian to
Gregorian calendars).
-ASN1_UTCTIME is limited to a year range of 1950 through 2049.
+B<ASN1_UTCTIME> is limited to a year range of 1950 through 2049.
Some applications add offset times directly to a time_t value and pass the
results to ASN1_TIME_set() (or equivalent). This can cause problems as the
time_t value can overflow on some systems resulting in unexpected results.
New applications should use ASN1_TIME_adj() instead and pass the offset value
-in the B<offset_sec> and B<offset_day> parameters instead of directly
+in the I<offset_sec> and I<offset_day> parameters instead of directly
manipulating a time_t value.
-ASN1_TIME_adj() may change the type from ASN1_GENERALIZEDTIME to ASN1_UTCTIME,
-or vice versa, based on the resulting year. The ASN1_GENERALIZEDTIME_adj() and
-ASN1_UTCTIME_adj() functions will not modify the type of the return structure.
+ASN1_TIME_adj() may change the type from B<ASN1_GENERALIZEDTIME> to
+B<ASN1_UTCTIME>, or vice versa, based on the resulting year.
+ASN1_GENERALIZEDTIME_adj() and ASN1_UTCTIME_adj() will not modify the type
+of the return structure.
-It is recommended that functions starting with ASN1_TIME be used instead of
-those starting with ASN1_UTCTIME or ASN1_GENERALIZEDTIME. The functions
-starting with ASN1_UTCTIME and ASN1_GENERALIZEDTIME act only on that specific
-time format. The functions starting with ASN1_TIME will operate on either
-format.
+It is recommended that functions starting with B<ASN1_TIME> be used instead of
+those starting with B<ASN1_UTCTIME> or B<ASN1_GENERALIZEDTIME>. The functions
+starting with B<ASN1_UTCTIME> and B<ASN1_GENERALIZEDTIME> act only on that
+specific time format. The functions starting with B<ASN1_TIME> will operate on
+either format.
=head1 BUGS
=head1 RETURN VALUES
-ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(),
-ASN1_UTCTIME_adj and ASN1_GENERALIZEDTIME_set return a pointer to a time structure
-or NULL if an error occurred.
+ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(),
+ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_set() return
+a pointer to a time structure or NULL if an error occurred.
-ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), ASN1_GENERALIZEDTIME_set_string()
-ASN1_TIME_set_string_X509() return 1 if the time value is successfully set and 0 otherwise.
+ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(),
+ASN1_GENERALIZEDTIME_set_string() and ASN1_TIME_set_string_X509() return
+1 if the time value is successfully set and 0 otherwise.
ASN1_TIME_normalize() returns 1 on success, and 0 on error.
ASN1_TIME_check(), ASN1_UTCTIME_check and ASN1_GENERALIZEDTIME_check() return 1
if the structure is syntactically correct and 0 otherwise.
-ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return 1
-if the time is successfully printed out and 0 if an error occurred (I/O error or
-invalid time format).
+ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return
+1 if the time is successfully printed out and 0 if an error occurred (I/O error
+or invalid time format).
ASN1_TIME_to_tm() returns 1 if the time is successfully parsed and 0 if an
error occurred (invalid time format).
ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
passed-in time structure has invalid syntax, for example.
-ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if B<s> is
-before B<t>, 0 if B<s> equals B<t>, or 1 if B<s> is after B<t>. -2 is returned
+ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if I<s> is
+before I<t>, 0 if I<s> equals I<t>, or 1 if I<s> is after I<t>. -2 is returned
on error.
-ASN1_TIME_compare() returns -1 if B<a> is before B<b>, 0 if B<a> equals B<b>, or 1 if B<a> is after B<b>. -2 is returned on error.
+ASN1_TIME_compare() returns -1 if I<a> is before I<b>, 0 if I<a> equals I<b>,
+or 1 if I<a> is after I<b>. -2 is returned on error.
-ASN1_TIME_to_generalizedtime() returns a pointer to
-the appropriate time structure on success or NULL if an error occurred.
+ASN1_TIME_to_generalizedtime() returns a pointer to the appropriate time
+structure on success or NULL if an error occurred.
=head1 EXAMPLES
=head1 DESCRIPTION
-These functions allow an ASN1_TYPE structure to be manipulated. The
-ASN1_TYPE structure can contain any ASN.1 type or constructed type
+These functions allow an B<ASN1_TYPE> structure to be manipulated. The
+B<ASN1_TYPE> structure can contain any ASN.1 type or constructed type
such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type.
-ASN1_TYPE_get() returns the type of B<a>.
+ASN1_TYPE_get() returns the type of I<a>.
-ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This
-function uses the pointer B<value> internally so it must B<not> be freed
+ASN1_TYPE_set() sets the value of I<a> to I<type> and I<value>. This
+function uses the pointer I<value> internally so it must B<not> be freed
up after the call.
-ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>.
+ASN1_TYPE_set1() sets the value of I<a> to I<type> a copy of I<value>.
-ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if
+ASN1_TYPE_cmp() compares ASN.1 types I<a> and I<b> and returns 0 if
they are identical and non-zero otherwise.
ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in
-B<t> using the ASN.1 structure B<it>. If successful it returns a pointer
-to the ASN.1 structure corresponding to B<it> which must be freed by the
+I<t> using the ASN.1 structure I<it>. If successful it returns a pointer
+to the ASN.1 structure corresponding to I<it> which must be freed by the
caller. If it fails it return NULL.
-ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s>
-corresponding to B<it> into an ASN1_TYPE. If successful the encoded
-ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type
-is written to B<t> overwriting any existing data. If B<t> is not NULL
-but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>.
+ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure I<s>
+corresponding to I<it> into an B<ASN1_TYPE>. If successful the encoded
+B<ASN1_TYPE> is returned. If I<t> and I<*t> are not NULL the encoded type
+is written to I<t> overwriting any existing data. If I<t> is not NULL
+but I<*t> is NULL the returned B<ASN1_TYPE> is written to I<*t>.
=head1 NOTES
-The type and meaning of the B<value> parameter for ASN1_TYPE_set() and
-ASN1_TYPE_set1() is determined by the B<type> parameter.
-If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN
-then the boolean is set to TRUE if B<value> is not NULL. If B<type> is
-V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type>
-is and ASN1_STRING structure. If B<type> corresponds to a primitive type
-(or a string type) then the contents of the ASN1_STRING contain the content
-octets of the type. If B<type> corresponds to a constructed type or
-a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the
-ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and
+The type and meaning of the I<value> parameter for ASN1_TYPE_set() and
+ASN1_TYPE_set1() is determined by the I<type> parameter.
+If I<type> is B<V_ASN1_NULL> I<value> is ignored. If I<type> is
+B<V_ASN1_BOOLEAN>
+then the boolean is set to TRUE if I<value> is not NULL. If I<type> is
+B<V_ASN1_OBJECT> then value is an B<ASN1_OBJECT> structure. Otherwise I<type>
+is and B<ASN1_STRING> structure. If I<type> corresponds to a primitive type
+(or a string type) then the contents of the B<ASN1_STRING> contain the content
+octets of the type. If I<type> corresponds to a constructed type or
+a tagged type (B<V_ASN1_SEQUENCE>, B<V_ASN1_SET> or B<V_ASN1_OTHER>) then the
+B<ASN1_STRING> contains the entire ASN.1 encoding verbatim (including tag and
length octets).
ASN1_TYPE_cmp() may not return zero if two types are equivalent but have
=head1 RETURN VALUES
-ASN1_TYPE_get() returns the type of the ASN1_TYPE argument.
+ASN1_TYPE_get() returns the type of the B<ASN1_TYPE> argument.
ASN1_TYPE_set() does not return a value.
ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or
NULL on failure.
-ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or
+ASN1_TYPE_pack_sequence() return an B<ASN1_TYPE> structure if it succeeds or
NULL on failure.
=head1 COPYRIGHT
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
=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.
+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)>.