From eb9d62d3efc9d950f259707d96c9bcea080916de Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 27 Dec 2024 15:30:17 +0000 Subject: new manual page a2i_ipadd(3) written from scratch --- src/lib/libcrypto/man/ASN1_STRING_length.3 | 9 +- src/lib/libcrypto/man/ASN1_STRING_new.3 | 6 +- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/a2i_ipadd.3 | 136 +++++++++++++++++++++++++++++ src/lib/libcrypto/man/i2a_ASN1_STRING.3 | 8 +- src/lib/libcrypto/man/s2i_ASN1_INTEGER.3 | 6 +- 6 files changed, 157 insertions(+), 11 deletions(-) create mode 100644 src/lib/libcrypto/man/a2i_ipadd.3 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 @@ -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 @@ -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 +.\" +.\" 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 .\" @@ -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 .\" @@ -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 , -- cgit v1.2.3-55-g6feb