From f94737840074fd8ffc91b5fab36f3cf6b8c42327 Mon Sep 17 00:00:00 2001 From: tb Date: Sun, 12 May 2024 11:49:47 +0000 Subject: [PATCH] Add minimal manpage documenting the misnamed X509V3_EXT_get_nid() This avoids a dangling reference in i2s_ASN1_ENUMERATED_TABLE. To complete this manual, someone will need to document X509V3_EXT_METHOD, but that's for a much more rainy day than today. --- lib/libcrypto/man/X509V3_EXT_get_nid.3 | 89 +++++++++++++++++++ lib/libcrypto/man/X509_EXTENSION_set_object.3 | 5 +- 2 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 lib/libcrypto/man/X509V3_EXT_get_nid.3 diff --git a/lib/libcrypto/man/X509V3_EXT_get_nid.3 b/lib/libcrypto/man/X509V3_EXT_get_nid.3 new file mode 100644 index 00000000000..657db0e61e0 --- /dev/null +++ b/lib/libcrypto/man/X509V3_EXT_get_nid.3 @@ -0,0 +1,89 @@ +.\" $OpenBSD: X509V3_EXT_get_nid.3,v 1.1 2024/05/12 11:49:47 tb Exp $ +.\" +.\" Copyright (c) 2024 Theo Buehler +.\" +.\" 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: May 12 2024 $ +.Dt X509V3_EXT_GET_NID 3 +.Os +.Sh NAME +.Nm X509V3_EXT_get_nid , +.Nm X509V3_EXT_get +.Nd retrieve X.509v3 certificate extension methods +.Sh SYNOPSIS +.In openssl/x509v3.h +.Ft const X509V3_EXT_METHOD * +.Fo X509V3_EXT_get_nid +.Fa "int nid" +.Fc +.Ft const X509V3_EXT_METHOD * +.Fo X509V3_EXT_get +.Fa "X509_EXTENSION *ext" +.Fc +.Sh DESCRIPTION +An X.509v3 certificate extension contains an Object Identifier (OID), +a boolean criticality indicator, and an opaque extension value +.Vt ASN1_OCTET_STRING +whose meaning is determined by the OID. +The library's +.Vt X509V3_EXT_METHOD +type, +which is not yet documented in detail, +contains a numeric identifier to represent the OID and various +handlers for encoding, decoding, printing, and configuring the +extension's value. +Criticality is handled separately, for example as an argument to +.Xr X509V3_add1_i2d 3 . +.Sh RETURN VALUES +.Fn X509V3_EXT_get_nid +returns the +.Vt X509V3_EXT_METHOD +corresponding to the numeric identifier +.Fa nid , +or +.Dv NULL +if there is none. +.Pp +.Fn X509V3_EXT_get +returns the built-in +.Vt X509V3_EXT_METHOD +associated with the extension type of +.Fa ext , +or +.Dv NULL +if there is none. +.Sh SEE ALSO +.Xr i2s_ASN1_ENUMERATED_TABLE 3 , +.Xr OBJ_create 3 , +.Xr X509_EXTENSION_get_object 3 , +.Xr X509V3_get_d2i 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate and +Certificate Revocation List (CRL) Profile +.Bl -dash -compact +.It +section 4.2: Certificate Extensions +.El +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.2b and +have been available since +.Ox 2.6 . +.Sh CAVEATS +LibreSSL only supports built-in extension methods. +Other implementations have incomplete support for custom extension methods, +whose API is not threadsafe, does not affect the behavior of +.Xr X509_verify_cert 3 , +and has various other surprising quirks. +If custom extensions were added, both functions will prefer them +over built-in methods. diff --git a/lib/libcrypto/man/X509_EXTENSION_set_object.3 b/lib/libcrypto/man/X509_EXTENSION_set_object.3 index dcfe075ebdd..3f6c7709a5c 100644 --- a/lib/libcrypto/man/X509_EXTENSION_set_object.3 +++ b/lib/libcrypto/man/X509_EXTENSION_set_object.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_EXTENSION_set_object.3,v 1.17 2023/04/30 19:40:23 tb Exp $ +.\" $OpenBSD: X509_EXTENSION_set_object.3,v 1.18 2024/05/12 11:49:47 tb Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 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: April 30 2023 $ +.Dd $Mdocdate: May 12 2024 $ .Dt X509_EXTENSION_SET_OBJECT 3 .Os .Sh NAME @@ -297,6 +297,7 @@ pointer. .Xr X509_check_issued 3 , .Xr X509_get_extension_flags 3 , .Xr X509_REQ_add_extensions 3 , +.Xr X509V3_EXT_get_nid 3 , .Xr X509V3_EXT_print 3 , .Xr X509V3_extensions_print 3 , .Xr X509V3_get_d2i 3 , -- 2.20.1