add a BUGS section warning about the creation of incomplete objects

diff --git a/lib/libcrypto/man/ASN1_OBJECT_new.3 b/lib/libcrypto/man/ASN1_OBJECT_new.3
index 6aa4723..3e2eac0 100644 (file)
--- a/lib/libcrypto/man/ASN1_OBJECT_new.3
+++ b/lib/libcrypto/man/ASN1_OBJECT_new.3
@@ -1,10 +1,10 @@
-.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.15 2021/12/15 20:07:51 schwarze Exp $
+.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.16 2023/09/05 15:01:39 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2017, 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2017, 2021, 2023 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
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 15 2021 $
+.Dd $Mdocdate: September 5 2023 $
 .Dt ASN1_OBJECT_NEW 3
 .Os
 .Sh NAME
@@ -207,3 +207,22 @@ first appeared in SSLeay 0.5.1 and
 in SSLeay 0.8.0.
 These functions have been available since
 .Ox 2.4 .
+.Sh BUGS
+The function
+.Fn ASN1_OBJECT_new
+is not useful for any practical purpose because the library does not
+provide any function capable of adding data to an existing object.
+Consequently, if the application program creates an object with
+.Fn ASN1_OBJECT_new ,
+that object will always remain empty.
+.Pp
+Similarly, if an
+.Fa nid
+of
+.Dv NID_undef
+is passed to
+.Fn ASN1_OBJECT_create ,
+or if
+.Dv NULL
+is passed for any of its pointer arguments, the returned object
+will permanently remain incomplete.