NAME

a2i_ipadd, a2i_IPADDRESS, a2i_IPADDRESS_NC — parse Internet Protocol addresses into ASN.1 OCTET STRINGs for X.509

SYNOPSIS

#include <openssl/x509v3.h>

int
a2i_ipadd(unsigned char *ipout, const char *ipasc);

ASN1_OCTET_STRING *
a2i_IPADDRESS(const char *ipasc);

ASN1_OCTET_STRING *
a2i_IPADDRESS_NC(const char *ipasc);

DESCRIPTION

a2i_ipadd() and a2i_IPADDRESS() parse the string ipasc containing an IPv4 or IPv6 address in one of the following formats:

d.d.d.d
x:x:x:x:x:x:x:x (exactly 8 words)
(x:)*x::x(:x)* (less than 8 words)
(x:)*x:: (less than 8 words)
::x(:x)* (less than 8 words)
::
(x:)*d.d.d.d (up to 6 hexadecimal words, :: can be used)

where each d represents a non-negative decimal number less than 256 with one, two or three digits and each x represents a non-negative hexadecimal number with one, two, three, or four digits. Both the lower case letters a-f and the upper case letters A-F can be used.

a2i_ipadd() stores the bytes of the address in network byte order (big endian) starting at ipout. The caller is responsible for providing sufficient space; always providing a buffer of at least 16 bytes is recommended, even if an IPv4 address is expected, to avoid buffer overruns in case ipasc is malformed.

a2i_IPADDRESS() stores the address in a newly allocated ASN.1 OCTET STRING.

a2i_IPADDRESS_NC() expects ipasc to contain two addresses of the same address family in the above form, separated by a slash (‘/’) character, and stores the concatenation of both addresses in a newly allocated ASN.1 OCTET STRING, which is typically used for address/mask pairs in name constraint extensions of CA certificates.

RETURN VALUES

a2i_ipadd() returns the number of bytes written to ipout in case of success, i.e. 4 for an IPv4 or 16 for an IPv6 address, or 0 if parsing failed.

a2i_IPADDRESS() and a2i_IPADDRESS_NC() return the new object or NULL if parsing or memory allocation failed.

SEE ALSO

a2i_ASN1_STRING(3), ASN1_OCTET_STRING_new(3), ASN1_OCTET_STRING_set(3), GENERAL_NAME_new(3), IPAddressRange_new(3), NAME_CONSTRAINTS_new(3), s2i_ASN1_OCTET_STRING(3), X509_EXTENSION_new(3)

STANDARDS

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

• section 4.2.1.6: Subject Alternative Name
• section 4.2.1.10: Name Constraints

HISTORY

a2i_IPADDRESS() and a2i_IPADDRESS_NC() first appeared in OpenSSL 0.9.8 and a2i_ipadd() in OpenSSL 0.9.8e. They have been available since OpenBSD 4.5.

CAVEATS

While some syntax errors are caught, only minimal validation takes place, and these functions often return objects that make no sense, in particular in the context of IPv6. For example, the trailing :d.d.d.d syntax can be appended to a hexadecimal part that results in twelve arbitrary bytes.