I2A_ASN1_STRING(3) | 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

library “libcrypto”
`#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.

June 8, 2025 | Debian