1.\" $OpenBSD: a2i_ipadd.3,v 1.1 2024/12/27 15:30:17 schwarze Exp $ 2.\" 3.\" Copyright (c) 2024 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: December 27 2024 $ 18.Dt A2I_IPADD 3 19.Os 20.Sh NAME 21.Nm a2i_ipadd , 22.Nm a2i_IPADDRESS , 23.Nm a2i_IPADDRESS_NC 24.Nd parse Internet Protocol addresses into ASN.1 OCTET STRINGs for X.509 25.Sh SYNOPSIS 26.In openssl/x509v3.h 27.Ft int 28.Fo a2i_ipadd 29.Fa "unsigned char *ipout" 30.Fa "const char *ipasc" 31.Fc 32.Ft ASN1_OCTET_STRING * 33.Fo a2i_IPADDRESS 34.Fa "const char *ipasc" 35.Fc 36.Ft ASN1_OCTET_STRING * 37.Fo a2i_IPADDRESS_NC 38.Fa "const char *ipasc" 39.Fc 40.Sh DESCRIPTION 41.Fn a2i_ipadd 42and 43.Fn a2i_IPADDRESS 44parse the string 45.Fa ipasc 46containing an IPv4 or IPv6 address 47in one of the following formats: 48.Bd -literal -offset indent 49d.d.d.d 50x:x:x:x:x:x:x:x (exactly 8 words) 51(x:)*x::x(:x)* (less than 8 words) 52(x:)*x:: (less than 8 words) 53::x(:x)* (less than 8 words) 54:: 55(x:)*d.d.d.d (up to 6 hexadecimal words, :: can be used) 56.Ed 57.Pp 58where each 59.Ar d 60represents a non-negative decimal number less than 256 61with one, two or three digits and each 62.Ar x 63represents a non-negative hexadecimal number 64with one, two, three, or four digits. 65Both the lower case letters a-f and the upper case letters A-F can be used. 66.Pp 67.Fn a2i_ipadd 68stores the bytes of the address in network byte order (big endian) starting at 69.Fa ipout . 70The caller is responsible for providing sufficient space; 71always providing a buffer of at least 16 bytes is recommended, 72even if an IPv4 address is expected, to avoid buffer overruns in case 73.Fa ipasc 74is malformed. 75.Pp 76.Fn a2i_IPADDRESS 77stores the address in a newly allocated ASN.1 78.Vt OCTET STRING . 79.Pp 80.Fn a2i_IPADDRESS_NC 81expects 82.Fa ipasc 83to contain two addresses of the same address family in the above form, 84separated by a slash 85.Pq Sq / 86character, and stores the concatenation of both addresses 87in a newly allocated ASN.1 88.Vt OCTET STRING , 89which is typically used for address/mask pairs 90in name constraint extensions of CA certificates. 91.Sh RETURN VALUES 92.Fn a2i_ipadd 93returns the number of bytes written to 94.Fa ipout 95in case of success, i.e. 4 for an IPv4 or 16 for an IPv6 address, 96or 0 if parsing failed. 97.Pp 98.Fn a2i_IPADDRESS 99and 100.Fn a2i_IPADDRESS_NC 101return the new object or 102.Dv NULL 103if parsing or memory allocation failed. 104.Sh SEE ALSO 105.Xr a2i_ASN1_STRING 3 , 106.Xr ASN1_OCTET_STRING_new 3 , 107.Xr ASN1_OCTET_STRING_set 3 , 108.Xr GENERAL_NAME_new 3 , 109.Xr IPAddressRange_new 3 , 110.Xr NAME_CONSTRAINTS_new 3 , 111.Xr s2i_ASN1_OCTET_STRING 3 , 112.Xr X509_EXTENSION_new 3 113.Sh STANDARDS 114RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 115Certificate Revocation List (CRL) Profile 116.Bl -dash -width 1n -compact 117.It 118section 4.2.1.6: Subject Alternative Name 119.It 120section 4.2.1.10: Name Constraints 121.El 122.Sh HISTORY 123.Fn a2i_IPADDRESS 124and 125.Fn a2i_IPADDRESS_NC 126first appeared in OpenSSL 0.9.8 and 127.Fn a2i_ipadd 128in OpenSSL 0.9.8e. 129They have been available since 130.Ox 4.5 . 131.Sh CAVEATS 132While some syntax errors are caught, only minimal validation takes place, 133and these functions often return objects that make no sense, in particular 134in the context of IPv6. 135For example, the trailing :d.d.d.d syntax can be appended 136to a hexadecimal part that results in twelve arbitrary bytes. 137