new manual page ASN1_NULL_new(3), also documenting ASN1_NULL_free(3)

4 files changed, 70 insertions, 5 deletions

diff --git a/src/lib/libcrypto/man/ASN1_NULL_new.3 b/src/lib/libcrypto/man/ASN1_NULL_new.3
new file mode 100644
index 0000000000..dc9f00b0a0
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_NULL_new.3
@@ -0,0 +1,62 @@
+.\" $OpenBSD: ASN1_NULL_new.3,v 1.1 2021/11/22 16:19:54 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 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: November 22 2021 $
+.Dt ASN1_NULL_NEW 3
+.Os
+.Sh NAME
+.Nm ASN1_NULL_new ,
+.Nm ASN1_NULL_free
+.Nd ASN.1 NULL value
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft ASN1_NULL *
+.Fn ASN1_NULL_new void
+.Ft void
+.Fn ASN1_NULL_free "ASN1_NULL *val_in"
+.Sh DESCRIPTION
+.Fn ASN1_NULL_new
+returns a specific invalid pointer that represents the ASN.1 NULL value,
+which is the only possible value of the ASN.1 NULL type.
+That pointer is different from a
+.Dv NULL
+pointer.
+Dereferencing it almost certainly results in a segmentation fault.
+This function does not allocate memory and cannot fail.
+.Pp
+.Fn ASN1_NULL_free
+has no effect whatsoever.
+In particular, i ignores the
+.Fa val_in
+argument and does not free any memory.
+In normal use, application programs only pass the invalid pointer
+obtained from
+.Fn ASN1_NULL_new
+to this function.
+But even if a valid pointer is passed, that pointer does not become invalid.
+.Sh SEE ALSO
+.Xr ASN1_item_new 3 ,
+.Xr d2i_ASN1_NULL 3
+.Sh STANDARDS
+ITU-T Recommendation X.208, also known as ISO/IEC 8824-1:
+Specification of Abstract Syntax Notation One (ASN.1),
+section 19: Notation for the null type
+.Sh HISTORY
+.Fn ASN1_NULL_new
+and
+.Fn ASN1_NULL_free
+first appeared in OpenSSL 0.9.5 and have been available since
+.Ox 2.7 .
diff --git a/src/lib/libcrypto/man/ASN1_item_new.3 b/src/lib/libcrypto/man/ASN1_item_new.3
index 6e36e86c6d..7fd3405e1f 100644
--- a/src/lib/libcrypto/man/ASN1_item_new.3
+++ b/src/lib/libcrypto/man/ASN1_item_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_item_new.3,v 1.9 2021/11/21 15:11:01 schwarze Exp $
+.\" $OpenBSD: ASN1_item_new.3,v 1.10 2021/11/22 16:19:54 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2018 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: November 21 2021 $
+.Dd $Mdocdate: November 22 2021 $
 .Dt ASN1_ITEM_NEW 3
 .Os
 .Sh NAME
@@ -111,6 +111,7 @@ is returned and an error code can be retrieved with
 .Xr ASN1_item_pack 3 ,
 .Xr ASN1_item_sign 3 ,
 .Xr ASN1_item_verify 3 ,
+.Xr ASN1_NULL_new 3 ,
 .Xr ASN1_TYPE_new 3 ,
 .Xr d2i_ASN1_BOOLEAN 3 ,
 .Xr d2i_ASN1_NULL 3 ,
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 4a8536747f..6a0d65cb85 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.219 2021/11/22 14:00:27 schwarze Exp $
+# $OpenBSD: Makefile,v 1.220 2021/11/22 16:19:54 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -8,6 +8,7 @@ MAN=	\
         ASN1_BIT_STRING_num_asc.3 \
         ASN1_BIT_STRING_set.3 \
         ASN1_INTEGER_get.3 \
+        ASN1_NULL_new.3 \
         ASN1_OBJECT_new.3 \
         ASN1_PRINTABLE_type.3 \
         ASN1_STRING_TABLE_add.3 \
diff --git a/src/lib/libcrypto/man/d2i_ASN1_NULL.3 b/src/lib/libcrypto/man/d2i_ASN1_NULL.3
index 7d10f1ba10..bc7c85e71e 100644
--- a/src/lib/libcrypto/man/d2i_ASN1_NULL.3
+++ b/src/lib/libcrypto/man/d2i_ASN1_NULL.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: d2i_ASN1_NULL.3,v 1.3 2019/06/06 01:06:59 schwarze Exp $
+.\"     $OpenBSD: d2i_ASN1_NULL.3,v 1.4 2021/11/22 16:19:54 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 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: June 6 2019 $
+.Dd $Mdocdate: November 22 2021 $
 .Dt D2I_ASN1_NULL 3
 .Os
 .Sh NAME
@@ -76,6 +76,7 @@ returns 2 if successful or 0 if an error occurs.
 .Sh SEE ALSO
 .Xr ASN1_item_d2i 3 ,
 .Xr ASN1_item_new 3 ,
+.Xr ASN1_NULL_new 3 ,
 .Xr ASN1_TYPE_get 3
 .Sh STANDARDS
 ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: