Manual Page Result
0
Command: i2a_ASN1_STRING | Section: 3 | Source: OpenBSD | File: i2a_ASN1_STRING.3
I2A_ASN1_STRING(3) FreeBSD Library Functions Manual I2A_ASN1_STRING(3)
NAME
i2a_ASN1_STRING, i2a_ASN1_INTEGER, i2a_ASN1_ENUMERATED, a2i_ASN1_STRING,
a2i_ASN1_INTEGER, a2i_ASN1_ENUMERATED - hexadecimal dump of an ASN.1
string
SYNOPSIS
#include <openssl/asn1.h>
int
i2a_ASN1_STRING(BIO *out_bio, const ASN1_STRING *a, int type);
int
i2a_ASN1_INTEGER(BIO *out_bio, const ASN1_INTEGER *a);
int
i2a_ASN1_ENUMERATED(BIO *out_bio, const i2a_ASN1_ENUMERATED *a);
int
a2i_ASN1_STRING(BIO *in_bio, ASN1_STRING *out_string, char *buffer,
int size);
int
a2i_ASN1_INTEGER(BIO *in_bio, ASN1_INTEGER *out_string, char *buffer,
int size);
int
a2i_ASN1_ENUMERATED(BIO *in_bio, ASN1_ENUMERATED *out_string,
char *buffer, int size);
DESCRIPTION
The functions i2a_ASN1_STRING(), i2a_ASN1_INTEGER(), and
i2a_ASN1_ENUMERATED() write a hexadecimal representation of a to out_bio.
The type argument is ignored.
Each byte of ASN1_STRING_get0_data(3) is written as a number consisting
of two upper-case hexadecimal digits. After each group of 70 digits, a
backslash and a linefeed are inserted before the next digit.
If the ASN1_STRING_length(3) of a is 0, instead a pair of zero digits
("00") is written by i2a_ASN1_INTEGER() and i2a_ASN1_ENUMERATED() and a
single zero digit ("0") by i2a_ASN1_STRING(). If a is a NULL pointer,
nothing is written.
If a represents a negative integer, i2a_ASN1_INTEGER() prepends a minus
sign to the output.
The functions a2i_ASN1_STRING(), a2i_ASN1_INTEGER(), and
a2i_ASN1_ENUMERATED() parse a hexadecimal representation of an ASN.1
string into out_string. Both lower-case and upper-case hexadecimal
digits are accepted. Every pair of input digits is converted into one
output byte.
On every input line, the trailing newline character and an optional
carriage return character preceding it are ignored. The trailing newline
need not be present on the last line. If there is a backslash character
before the newline character, parsing is continued on the next input
line.
At least one pair of input digits is required by a2i_ASN1_INTEGER() and
a2i_ASN1_ENUMERATED(), whereas a2i_ASN1_STRING() converts empty input to
an empty string.
These functions are able to parse the output of i2a_ASN1_ENUMERATED().
They can parse the output of i2a_ASN1_INTEGER() unless a was negative,
and they can parse the output of i2a_ASN1_STRING() unless the
ASN1_STRING_length(3) of a was 0.
Parsing fails if an input line contains an odd number of input digits or
if memory allocation fails.
These functions use the buffer provided by the caller and assume it is at
least size bytes long. It is unspecified what the buffer contains after
the functions return.
RETURN VALUES
The functions i2a_ASN1_STRING(), i2a_ASN1_INTEGER(), and
i2a_ASN1_ENUMERATED() return the number of bytes written or -1 if
BIO_write(3) fails. In particular, they all return 0 when a is a NULL
pointer. i2a_ASN1_STRING() returns 1 for an empty string or an even
number greater than 1 for a string that is not empty. i2a_ASN1_INTEGER()
returns an even number greater than 1 for positive input or an odd number
greater than 2 for negative input. i2a_ASN1_ENUMERATED() always returns
a non-negative even number when successful.
The functions a2i_ASN1_STRING(), a2i_ASN1_INTEGER(), and
a2i_ASN1_ENUMERATED() are intended to return 1 for success or 0 for
failure, but see the BUGS section for a number of traps.
SEE ALSO
a2i_ipadd(3), ASN1_STRING_length(3), ASN1_STRING_new(3),
ASN1_STRING_print_ex(3), i2a_ASN1_OBJECT(3), i2s_ASN1_INTEGER(3)
HISTORY
i2a_ASN1_INTEGER() and a2i_ASN1_INTEGER() first appeared in SSLeay 0.6.0.
i2a_ASN1_STRING() and a2i_ASN1_STRING() first appeared in SSLeay 0.6.5.
a2i_ASN1_STRING() has been part of the public API since SSLeay 0.6.5 and
i2a_ASN1_STRING() since SSLeay 0.8.0. These functions have been
available since OpenBSD 2.4.
i2a_ASN1_ENUMERATED() and a2i_ASN1_ENUMERATED() first appeared in OpenSSL
0.9.2 and have been available since OpenBSD 2.6.
BUGS
If the first call to BIO_gets(3) does not return any data, even if that
is caused by a fatal I/O error, if the BIO type does not support the
"gets" operation, or if it is caused by the BIO being non-blocking,
a2i_ASN1_STRING() immediately succeeds and returns an empty out_string.
If BIO_gets(3) returns a partial line, for example because the given size
is insufficient to contain one of the input lines or for reasons specific
to the BIO type, a2i_ASN1_STRING(), a2i_ASN1_INTEGER(), and
a2i_ASN1_ENUMERATED() may fail or silently return a truncated result.
The caller is responsible for providing a buffer of sufficient size to
contain the longest possible input line and for choosing a BIO of a type
that only returns complete input lines and does not perform partial
reads.
The functions a2i_ASN1_STRING(), a2i_ASN1_INTEGER(), and
a2i_ASN1_ENUMERATED() do not support non-blocking BIOs. Reading is
terminated as soon as BIO_gets(3) returns a value less than 1.
FreeBSD 14.1-RELEASE-p8 December 27, 2024 FreeBSD 14.1-RELEASE-p8