A2I_IPADD(3)               Library Functions Manual               A2I_IPADD(3)

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.

Linux 6.13.7-arch1-1           December 27, 2024          Linux 6.13.7-arch1-1