Move OBJ_create(3) into its own manual page

because OBJ_nid2obj(3) is already long and
more functions related to OBJ_create(3) have to be documented.

5 files changed, 157 insertions, 63 deletions

diff --git a/src/lib/libcrypto/man/ASN1_OBJECT_new.3 b/src/lib/libcrypto/man/ASN1_OBJECT_new.3
index 24e9767f3d..6aa4723c7f 100644
--- a/src/lib/libcrypto/man/ASN1_OBJECT_new.3
+++ b/src/lib/libcrypto/man/ASN1_OBJECT_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.14 2021/12/09 18:43:50 schwarze Exp $
+.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.15 2021/12/15 20:07:51 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -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 9 2021 $
+.Dd $Mdocdate: December 15 2021 $
 .Dt ASN1_OBJECT_NEW 3
 .Os
 .Sh NAME
@@ -186,6 +186,7 @@ Memory allocation failed.
 .Xr a2d_ASN1_OBJECT 3 ,
 .Xr ASN1_TYPE_get 3 ,
 .Xr d2i_ASN1_OBJECT 3 ,
+.Xr OBJ_create 3 ,
 .Xr OBJ_nid2obj 3
 .Sh STANDARDS
 ITU-T Recommendation X.208, also known as ISO/IEC 8824-1:
diff --git a/src/lib/libcrypto/man/ASN1_STRING_TABLE_add.3 b/src/lib/libcrypto/man/ASN1_STRING_TABLE_add.3
index 85120de270..482faa0f53 100644
--- a/src/lib/libcrypto/man/ASN1_STRING_TABLE_add.3
+++ b/src/lib/libcrypto/man/ASN1_STRING_TABLE_add.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_STRING_TABLE_add.3,v 1.8 2021/12/14 20:14:22 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_TABLE_add.3,v 1.9 2021/12/15 20:07:51 schwarze Exp $
 .\" checked up to:
 .\" OpenSSL ASN1_STRING_TABLE_add.pod 7b608d08 Jul 27 01:18:50 2017 +0800
 .\"
@@ -16,7 +16,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 14 2021 $
+.Dd $Mdocdate: December 15 2021 $
 .Dt ASN1_STRING_TABLE_ADD 3
 .Os
 .Sh NAME
@@ -129,6 +129,7 @@ if nothing is found.
 .Sh SEE ALSO
 .Xr ASN1_OBJECT_new 3 ,
 .Xr ASN1_STRING_set_by_NID 3 ,
+.Xr OBJ_create 3 ,
 .Xr OBJ_nid2obj 3
 .Sh HISTORY
 .Fn ASN1_STRING_TABLE_add ,
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 2986652b79..9a51640331 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.228 2021/12/14 15:22:49 schwarze Exp $
+# $OpenBSD: Makefile,v 1.229 2021/12/15 20:07:51 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -206,6 +206,7 @@ MAN=	\
         HMAC.3 \
         MD5.3 \
         NAME_CONSTRAINTS_new.3 \
+        OBJ_create.3 \
         OBJ_nid2obj.3 \
         OCSP_CRLID_new.3 \
         OCSP_REQUEST_new.3 \
diff --git a/src/lib/libcrypto/man/OBJ_create.3 b/src/lib/libcrypto/man/OBJ_create.3
new file mode 100644
index 0000000000..37a3907193
--- /dev/null
+++ b/src/lib/libcrypto/man/OBJ_create.3
@@ -0,0 +1,140 @@
+.\" $OpenBSD: OBJ_create.3,v 1.1 2021/12/15 20:07:51 schwarze Exp $
+.\" full merge up to:
+.\" OpenSSL OBJ_nid2obj.pod 9b86974e Aug 17 15:21:33 2015 -0400
+.\" selective merge up to:
+.\" OpenSSL OBJ_nid2obj.pod 35fd9953 May 28 14:49:38 2019 +0200
+.\"
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2017 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.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" Copyright (c) 2002, 2006 The OpenSSL Project.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" 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 $
+.Dt OBJ_CREATE 3
+.Os
+.Sh NAME
+.Nm OBJ_create ,
+.Nm OBJ_cleanup
+.Nd modify the table of ASN.1 object identifiers
+.Sh SYNOPSIS
+.In openssl/objects.h
+.Ft int
+.Fo OBJ_create
+.Fa "const char *oid"
+.Fa "const char *sn"
+.Fa "const char *ln"
+.Fc
+.Ft void
+.Fn OBJ_cleanup void
+.Sh DESCRIPTION
+.Fn OBJ_create
+adds a new object to the internal table.
+.Fa oid
+is the numerical form of the object,
+.Fa sn
+the short name and
+.Fa ln
+the long name.
+A new NID is returned for the created object.
+.Pp
+The new object added to the internal table and all the data
+contained in it is marked as not dynamically allocated.
+Consequently, retrieving it with
+.Xr OBJ_nid2obj 3
+or a similar function and then calling
+.Xr ASN1_OBJECT_free 3
+on the returned pointer will have no effect.
+.Pp
+.Fn OBJ_cleanup
+cleans up the internal object table: this should be called before
+an application exits if any new objects were added using
+.Fn OBJ_create .
+.Sh RETURN VALUES
+.Fn OBJ_create
+returns the new NID or
+.Dv NID_undef
+if an error occurs.
+.Pp
+In some cases of failure of
+.Fn OBJ_create ,
+the reason can be determined with
+.Xr ERR_get_error 3 .
+.Sh EXAMPLES
+Create a new NID and initialize an object from it:
+.Bd -literal -offset indent
+int new_nid;
+
+ASN1_OBJECT *obj;
+new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
+obj = OBJ_nid2obj(new_nid);
+.Ed
+.Sh SEE ALSO
+.Xr ASN1_OBJECT_new 3 ,
+.Xr OBJ_nid2obj 3
+.Sh HISTORY
+.Fn OBJ_cleanup
+first appeared in SSLeay 0.8.0 and
+.Fn OBJ_create
+in SSLeay 0.9.0.
+These functions have been available since
+.Ox 2.4 .
diff --git a/src/lib/libcrypto/man/OBJ_nid2obj.3 b/src/lib/libcrypto/man/OBJ_nid2obj.3
index db9cd05c26..a43fe962e1 100644
--- a/src/lib/libcrypto/man/OBJ_nid2obj.3
+++ b/src/lib/libcrypto/man/OBJ_nid2obj.3
@@ -1,5 +1,6 @@
-.\"     $OpenBSD: OBJ_nid2obj.3,v 1.15 2021/07/05 17:57:16 schwarze Exp $
-.\"     OpenSSL c264592d May 14 11:28:00 2006 +0000
+.\" $OpenBSD: OBJ_nid2obj.3,v 1.16 2021/12/15 20:07:51 schwarze Exp $
+.\" full merge up to: OpenSSL c264592d May 14 11:28:00 2006 +0000
+.\" selective merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
@@ -19,7 +20,7 @@
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
-.\" Copyright (c) 2002, 2006, 2015, 2016 The OpenSSL Project.
+.\" Copyright (c) 2002, 2006, 2016 The OpenSSL Project.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -66,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 5 2021 $
+.Dd $Mdocdate: December 15 2021 $
 .Dt OBJ_NID2OBJ 3
 .Os
 .Sh NAME
@@ -81,8 +82,6 @@
 .Nm OBJ_obj2txt ,
 .Nm OBJ_cmp ,
 .Nm OBJ_dup ,
-.Nm OBJ_create ,
-.Nm OBJ_cleanup ,
 .Nm i2t_ASN1_OBJECT ,
 .Nm i2a_ASN1_OBJECT
 .Nd inspect and create ASN.1 object identifiers
@@ -137,14 +136,6 @@
 .Fo OBJ_dup
 .Fa "const ASN1_OBJECT *o"
 .Fc
-.Ft int
-.Fo OBJ_create
-.Fa "const char *oid"
-.Fa "const char *sn"
-.Fa "const char *ln"
-.Fc
-.Ft void
-.Fn OBJ_cleanup void
 .In openssl/asn1.h
 .Ft int
 .Fo i2t_ASN1_OBJECT
@@ -286,29 +277,6 @@ just returns
 .Fa o
 itself.
 .Pp
-.Fn OBJ_create
-adds a new object to the internal table.
-.Fa oid
-is the numerical form of the object,
-.Fa sn
-the short name and
-.Fa ln
-the long name.
-A new NID is returned for the created object.
-.Pp
-The new object added to the internal table and all the data
-contained in it is marked as not dynamically allocated.
-Consequently, retrieving it with
-.Fn OBJ_nid2obj
-or a similar function and then calling
-.Xr ASN1_OBJECT_free 3
-on the returned pointer will have no effect.
-.Pp
-.Fn OBJ_cleanup
-cleans up the internal object table: this should be called before
-an application exits if any new objects were added using
-.Fn OBJ_create .
-.Pp
 Objects can have a short name, a long name, and a numerical
 identifier (NID) associated with them.
 A standard set of objects is represented in an internal table.
@@ -323,7 +291,7 @@ For example, the OID for commonName has the following definitions:
 .Ed
 .Pp
 New objects can be added by calling
-.Fn OBJ_create .
+.Xr OBJ_create 3 .
 .Pp
 Table objects have certain advantages over other objects: for example
 their NIDs can be used in a C language switch statement.
@@ -385,11 +353,6 @@ and
 .Fa b
 are identical, or non-zero otherwise.
 .Pp
-.Fn OBJ_create
-returns the new NID or
-.Dv NID_undef
-if an error occurs.
-.Pp
 In some cases of failure of
 .Fn OBJ_nid2obj ,
 .Fn OBJ_nid2ln ,
@@ -398,7 +361,6 @@ In some cases of failure of
 .Fn OBJ_txt2obj ,
 .Fn OBJ_obj2txt ,
 .Fn OBJ_dup ,
-.Fn OBJ_create ,
 .Fn i2t_ASN1_OBJECT ,
 and
 .Fn i2a_ASN1_OBJECT ,
@@ -419,14 +381,6 @@ if (OBJ_obj2nid(obj) == NID_commonName)
         /* Do something */
 .Ed
 .Pp
-Create a new NID and initialize an object from it:
-.Bd -literal -offset indent
-int new_nid;
-ASN1_OBJECT *obj;
-new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
-obj = OBJ_nid2obj(new_nid);
-.Ed
-.Pp
 Create a new object directly:
 .Bd -literal -offset indent
 obj = OBJ_txt2obj("1.2.3.4", 1);
@@ -434,7 +388,8 @@ obj = OBJ_txt2obj("1.2.3.4", 1);
 .Sh SEE ALSO
 .Xr ASN1_OBJECT_new 3 ,
 .Xr BIO_new 3 ,
-.Xr d2i_ASN1_OBJECT 3
+.Xr d2i_ASN1_OBJECT 3 ,
+.Xr OBJ_create 3
 .Sh HISTORY
 .Fn OBJ_nid2obj ,
 .Fn OBJ_nid2ln ,
@@ -448,11 +403,7 @@ and
 .Fn OBJ_dup
 first appeared in SSLeay 0.5.1.
 .Fn i2a_ASN1_OBJECT
-first appeared in SSLeay 0.6.0,
-.Fn OBJ_cleanup
-in SSLeay 0.8.0, and
-.Fn OBJ_create
-and
+first appeared in SSLeay 0.6.0, and
 .Fn i2t_ASN1_OBJECT
 in SSLeay 0.9.0.
 All these functions have been available since