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 carrier return character 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.

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.