document ASN1_OBJECT_create(3)

1 files changed, 61 insertions, 10 deletions

diff --git a/src/lib/libcrypto/man/ASN1_OBJECT_new.3 b/src/lib/libcrypto/man/ASN1_OBJECT_new.3
index cf48cccef9..671631094b 100644
--- a/src/lib/libcrypto/man/ASN1_OBJECT_new.3
+++ b/src/lib/libcrypto/man/ASN1_OBJECT_new.3
@@ -1,10 +1,10 @@
-.\"     $OpenBSD: ASN1_OBJECT_new.3,v 1.11 2019/06/06 01:06:58 schwarze Exp $
-.\"     OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400
+.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.12 2021/11/22 12:06:51 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 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2017, 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
@@ -65,11 +65,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: November 22 2021 $
 .Dt ASN1_OBJECT_NEW 3
 .Os
 .Sh NAME
 .Nm ASN1_OBJECT_new ,
+.Nm ASN1_OBJECT_create ,
 .Nm ASN1_OBJECT_free
 .Nd ASN.1 object identifiers
 .Sh SYNOPSIS
@@ -78,6 +79,14 @@
 .Fo ASN1_OBJECT_new
 .Fa void
 .Fc
+.Ft ASN1_OBJECT *
+.Fo ASN1_OBJECT_create
+.Fa "int nid"
+.Fa "unsigned char *content"
+.Fa "int len"
+.Fa "const char *short_name"
+.Fa "const char *long_name"
+.Fc
 .Ft void
 .Fo ASN1_OBJECT_free
 .Fa "ASN1_OBJECT *a"
@@ -92,10 +101,28 @@ and a sequence of integers identifying a node in the International
 Object Identifier tree as specified in ITU-T recommendation X.660.
 The new object is marked as dynamically allocated.
 .Pp
+.Fn ASN1_OBJECT_create
+allocates a new
+.Vt ASN1_OBJECT
+with the given
+.Fa nid ,
+copies the
+.Fa len
+DER
+.Fa content
+octets, the
+.Fa short_name ,
+and the
+.Fa long_name
+into it, and marks the new object and all data contained in it
+as dynamically allocated.
+.Pp
 Application programs normally use utility functions like
 .Xr OBJ_nid2obj 3
 rather than using
 .Fn ASN1_OBJECT_new
+or
+.Fn ASN1_OBJECT_create
 directly.
 .Pp
 .Fn ASN1_OBJECT_free
@@ -123,13 +150,34 @@ is a
 pointer or if neither the object itself nor any of its content
 is marked as dynamically allocated, no action occurs.
 .Sh RETURN VALUES
-If the allocation fails,
 .Fn ASN1_OBJECT_new
-returns
+and
+.Fn ASN1_OBJECT_create
+return a pointer to the new object or
 .Dv NULL
-and sets an error code that can be obtained by
-.Xr ERR_get_error 3 .
-Otherwise it returns a pointer to the new object.
+if memory allocation fails,
+.Sh ERRORS
+After failure of
+.Fn ASN1_OBJECT_new
+or
+.Fn ASN1_OBJECT_create ,
+the following diagnostic can be retrieved with
+.Xr ERR_get_error 3 ,
+.Xr ERR_GET_REASON 3 ,
+and
+.Xr ERR_reason_error_string 3 :
+.Bl -tag -width Ds
+.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure"
+Memory allocation failed.
+.El
+.Pp
+After some cases of failure of
+.Fn ASN1_OBJECT_create ,
+the following diagnostic can be retrieved in addition to the above:
+.Bl -tag -width Ds
+.It Dv ERR_R_ASN1_LIB Qq "ASN1 lib"
+Memory allocation failed.
+.El
 .Sh SEE ALSO
 .Xr ASN1_TYPE_get 3 ,
 .Xr d2i_ASN1_OBJECT 3 ,
@@ -138,5 +186,8 @@ Otherwise it returns a pointer to the new object.
 .Fn ASN1_OBJECT_new
 and
 .Fn ASN1_OBJECT_free
-first appeared in SSLeay 0.5.1 and have been available since
+first appeared in SSLeay 0.5.1 and
+.Fn ASN1_OBJECT_create
+in SSLeay 0.8.0.
+These functions have been available since
 .Ox 2.4 .