libressl-i2a_ASN1_STRING3
Hexadecimal dump of an asn.1 string
Usage
Crypto Library (libcrypto, -lcrypto)
#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);
Overview
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.