From c78bdb9132b8c1c5b0a096c33874552a071fcb9d Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 15 Dec 2021 20:07:51 +0000 Subject: [PATCH] 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. --- lib/libcrypto/man/ASN1_OBJECT_new.3 | 5 +- lib/libcrypto/man/ASN1_STRING_TABLE_add.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/OBJ_create.3 | 140 ++++++++++++++++++++++ lib/libcrypto/man/OBJ_nid2obj.3 | 67 ++--------- 5 files changed, 157 insertions(+), 63 deletions(-) create mode 100644 lib/libcrypto/man/OBJ_create.3 diff --git a/lib/libcrypto/man/ASN1_OBJECT_new.3 b/lib/libcrypto/man/ASN1_OBJECT_new.3 index 24e9767f3d6..6aa4723c7fc 100644 --- a/lib/libcrypto/man/ASN1_OBJECT_new.3 +++ b/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/lib/libcrypto/man/ASN1_STRING_TABLE_add.3 b/lib/libcrypto/man/ASN1_STRING_TABLE_add.3 index 85120de270c..482faa0f53b 100644 --- a/lib/libcrypto/man/ASN1_STRING_TABLE_add.3 +++ b/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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 2986652b794..9a516403311 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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/lib/libcrypto/man/OBJ_create.3 b/lib/libcrypto/man/OBJ_create.3 new file mode 100644 index 00000000000..37a39071936 --- /dev/null +++ b/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 +.\" +.\" 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 . +.\" 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/lib/libcrypto/man/OBJ_nid2obj.3 b/lib/libcrypto/man/OBJ_nid2obj.3 index db9cd05c26d..a43fe962e1e 100644 --- a/lib/libcrypto/man/OBJ_nid2obj.3 +++ b/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 . -.\" 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 -- 2.20.1