new manual page a2i_ipadd(3) written from scratch

6 files changed, 157 insertions, 11 deletions

diff --git a/src/lib/libcrypto/man/ASN1_STRING_length.3 b/src/lib/libcrypto/man/ASN1_STRING_length.3
index 20834e081a..0c397607a9 100644
--- a/src/lib/libcrypto/man/ASN1_STRING_length.3
+++ b/src/lib/libcrypto/man/ASN1_STRING_length.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_STRING_length.3,v 1.29 2021/12/14 19:36:18 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_length.3,v 1.30 2024/12/27 15:30:17 schwarze Exp $
 .\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file is a derived work.
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 14 2021 $
+.Dd $Mdocdate: December 27 2024 $
 .Dt ASN1_STRING_LENGTH 3
 .Os
 .Sh NAME
@@ -401,11 +401,14 @@ and
 the reason can be determined with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr a2i_ASN1_STRING 3 ,
+.Xr a2i_ipadd 3 ,
 .Xr ASN1_BIT_STRING_set 3 ,
 .Xr ASN1_mbstring_copy 3 ,
 .Xr ASN1_PRINTABLE_type 3 ,
 .Xr ASN1_STRING_new 3 ,
-.Xr ASN1_UNIVERSALSTRING_to_string 3
+.Xr ASN1_UNIVERSALSTRING_to_string 3 ,
+.Xr s2i_ASN1_INTEGER 3
 .Sh HISTORY
 .Fn ASN1_STRING_cmp ,
 .Fn ASN1_STRING_dup ,
diff --git a/src/lib/libcrypto/man/ASN1_STRING_new.3 b/src/lib/libcrypto/man/ASN1_STRING_new.3
index 19b0ca1161..212bacd413 100644
--- a/src/lib/libcrypto/man/ASN1_STRING_new.3
+++ b/src/lib/libcrypto/man/ASN1_STRING_new.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ASN1_STRING_new.3,v 1.26 2024/03/05 18:30:40 tb Exp $
+.\"     $OpenBSD: ASN1_STRING_new.3,v 1.27 2024/12/27 15:30:17 schwarze Exp $
 .\"     OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
 .\"
 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 5 2024 $
+.Dd $Mdocdate: December 27 2024 $
 .Dt ASN1_STRING_NEW 3
 .Os
 .Sh NAME
@@ -205,6 +205,7 @@ object if successful; otherwise
 is returned and an error code can be retrieved with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr a2i_ipadd 3 ,
 .Xr ASN1_BIT_STRING_set 3 ,
 .Xr ASN1_INTEGER_get 3 ,
 .Xr ASN1_item_pack 3 ,
@@ -218,6 +219,7 @@ is returned and an error code can be retrieved with
 .Xr d2i_ASN1_OBJECT 3 ,
 .Xr d2i_ASN1_OCTET_STRING 3 ,
 .Xr i2a_ASN1_STRING 3 ,
+.Xr s2i_ASN1_INTEGER 3 ,
 .Xr X509_cmp_time 3 ,
 .Xr X509_EXTENSION_get_object 3 ,
 .Xr X509_get_ext_by_OBJ 3 ,
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 4c7c5891eb..8df75fe284 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.304 2024/12/24 09:48:56 schwarze Exp $
+# $OpenBSD: Makefile,v 1.305 2024/12/27 15:30:17 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -385,6 +385,7 @@ MAN=	\
         X509v3_asid_add_id_or_range.3 \
         X509v3_get_ext_by_NID.3 \
         a2d_ASN1_OBJECT.3 \
+        a2i_ipadd.3 \
         crypto.3 \
         d2i_ASN1_NULL.3 \
         d2i_ASN1_OBJECT.3 \
diff --git a/src/lib/libcrypto/man/a2i_ipadd.3 b/src/lib/libcrypto/man/a2i_ipadd.3
new file mode 100644
index 0000000000..1372b2acfd
--- /dev/null
+++ b/src/lib/libcrypto/man/a2i_ipadd.3
@@ -0,0 +1,136 @@
+.\" $OpenBSD: a2i_ipadd.3,v 1.1 2024/12/27 15:30:17 schwarze Exp $
+.\"
+.\" Copyright (c) 2024 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 27 2024 $
+.Dt A2I_IPADD 3
+.Os
+.Sh NAME
+.Nm a2i_ipadd ,
+.Nm a2i_IPADDRESS ,
+.Nm a2i_IPADDRESS_NC
+.Nd parse Internet Protocol addresses into ASN.1 OCTET STRINGs for X.509
+.Sh SYNOPSIS
+.In openssl/x509v3.h
+.Ft int
+.Fo a2i_ipadd
+.Fa "unsigned char *ipout"
+.Fa "const char *ipasc"
+.Fc
+.Ft ASN1_OCTET_STRING *
+.Fo a2i_IPADDRESS
+.Fa "const char *ipasc"
+.Fc
+.Ft ASN1_OCTET_STRING *
+.Fo a2i_IPADDRESS_NC
+.Fa "const char *ipasc"
+.Fc
+.Sh DESCRIPTION
+.Fn a2i_ipadd
+and
+.Fn a2i_IPADDRESS
+parse the string
+.Fa ipasc
+containing an IPv4 or IPv6 address
+in one of the following formats:
+.Bd -literal -offset indent
+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)
+.Ed
+.Pp
+where each
+.Ar d
+represents a non-negative decimal number less than 256
+with one, two or three digits and each
+.Ar 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.
+.Pp
+.Fn a2i_ipadd
+stores the bytes of the address in network byte order (big endian) starting at
+.Fa 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
+.Fa ipasc
+is malformed.
+.Pp
+.Fn a2i_IPADDRESS
+stores the address in a newly allocated ASN.1
+.Vt OCTET STRING .
+.Pp
+.Fn a2i_IPADDRESS_NC
+expects
+.Fa ipasc
+to contain two addresses of the same address family in the above form,
+separated by a slash
+.Pq Sq /
+character, and stores the concatenation of both addresses
+in a newly allocated ASN.1
+.Vt OCTET STRING ,
+which is typically used for address/mask pairs
+in name constraint extensions of CA certificates.
+.Sh RETURN VALUES
+.Fn a2i_ipadd
+returns the number of bytes written to
+.Fa ipout
+in case of success, i.e. 4 for an IPv4 or 16 for an IPv6 address,
+or 0 if parsing failed.
+.Pp
+.Fn a2i_IPADDRESS
+and
+.Fn a2i_IPADDRESS_NC
+return the new object or
+.Dv NULL
+if parsing or memory allocation failed.
+.Sh SEE ALSO
+.Xr a2i_ASN1_STRING 3 ,
+.Xr ASN1_OCTET_STRING_new 3 ,
+.Xr ASN1_OCTET_STRING_set 3 ,
+.Xr GENERAL_NAME_new 3 ,
+.Xr IPAddressRange_new 3 ,
+.Xr NAME_CONSTRAINTS_new 3 ,
+.Xr s2i_ASN1_OCTET_STRING 3 ,
+.Xr X509_EXTENSION_new 3
+.Sh STANDARDS
+RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
+Certificate Revocation List (CRL) Profile
+.Bl -dash -width 1n -compact
+.It
+section 4.2.1.6: Subject Alternative Name
+.It
+section 4.2.1.10: Name Constraints
+.El
+.Sh HISTORY
+.Fn a2i_IPADDRESS
+and
+.Fn a2i_IPADDRESS_NC
+first appeared in OpenSSL 0.9.8 and
+.Fn a2i_ipadd
+in OpenSSL 0.9.8e.
+They have been available since
+.Ox 4.5 .
+.Sh 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.
diff --git a/src/lib/libcrypto/man/i2a_ASN1_STRING.3 b/src/lib/libcrypto/man/i2a_ASN1_STRING.3
index daa74ca641..7d46474775 100644
--- a/src/lib/libcrypto/man/i2a_ASN1_STRING.3
+++ b/src/lib/libcrypto/man/i2a_ASN1_STRING.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: i2a_ASN1_STRING.3,v 1.4 2022/09/10 12:36:18 jsg Exp $
+.\" $OpenBSD: i2a_ASN1_STRING.3,v 1.5 2024/12/27 15:30:17 schwarze Exp $
 .\"
 .\" Copyright (c) 2019, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: September 10 2022 $
+.Dd $Mdocdate: December 27 2024 $
 .Dt I2A_ASN1_STRING 3
 .Os
 .Sh NAME
@@ -189,10 +189,12 @@ are intended to return 1 for success or 0 for failure, but see the
 .Sx BUGS
 section for a number of traps.
 .Sh SEE ALSO
+.Xr a2i_ipadd 3 ,
 .Xr ASN1_STRING_length 3 ,
 .Xr ASN1_STRING_new 3 ,
 .Xr ASN1_STRING_print_ex 3 ,
-.Xr i2a_ASN1_OBJECT 3
+.Xr i2a_ASN1_OBJECT 3 ,
+.Xr i2s_ASN1_INTEGER 3
 .Sh HISTORY
 .Fn i2a_ASN1_INTEGER
 and
diff --git a/src/lib/libcrypto/man/s2i_ASN1_INTEGER.3 b/src/lib/libcrypto/man/s2i_ASN1_INTEGER.3
index 0aae94e07d..a2105bc4bc 100644
--- a/src/lib/libcrypto/man/s2i_ASN1_INTEGER.3
+++ b/src/lib/libcrypto/man/s2i_ASN1_INTEGER.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: s2i_ASN1_INTEGER.3,v 1.8 2024/12/24 09:48:56 schwarze Exp $
+.\" $OpenBSD: s2i_ASN1_INTEGER.3,v 1.9 2024/12/27 15:30:17 schwarze Exp $
 .\"
 .\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: December 24 2024 $
+.Dd $Mdocdate: December 27 2024 $
 .Dt S2I_ASN1_INTEGER 3
 .Os
 .Sh NAME
@@ -196,6 +196,8 @@ colons at the start, the end or between pairs of hexadecimal digits.
 Error codes can sometimes be obtained by
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr a2i_ASN1_INTEGER 3 ,
+.Xr a2i_ipadd 3 ,
 .Xr ASN1_INTEGER_new 3 ,
 .Xr ASN1_INTEGER_to_BN 3 ,
 .Xr ASN1_OCTET_STRING_new 3 ,