From ef065493fb463fe122ab7b535932b871830b6de3 Mon Sep 17 00:00:00 2001 From: tb Date: Tue, 10 Oct 2023 13:59:47 +0000 Subject: [PATCH] Improve X509_ALGOR_new(3) documentation The previous wording was misleading since the result of X509_ALGOR_new() is not actually an empty X509_ALGOR object. Rather, it contains the undefined ASN1_OBJECT returned by OBJ_nid2obj(NID_undef). Therefore using X509_ALGOR_get0(3) for error checking X509_ALGOR_set_md() is not trivial. So: change the initial paragraph into a general intro referring to the OpenSSL API needed to interface with X509_ALGOR and write a new paragraph documenting X509_ALGOR_new(3) and drop the incorrect suggestion of an error check. Notably there's now a reference to the OBJ_nid2obj() family without which one cannot really use X509_ALGOR_* for anything at all. With and ok schwarze --- lib/libcrypto/man/X509_ALGOR_dup.3 | 47 +++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 14 deletions(-) diff --git a/lib/libcrypto/man/X509_ALGOR_dup.3 b/lib/libcrypto/man/X509_ALGOR_dup.3 index 56d9674c7c0..0b878b7a86d 100644 --- a/lib/libcrypto/man/X509_ALGOR_dup.3 +++ b/lib/libcrypto/man/X509_ALGOR_dup.3 @@ -1,9 +1,10 @@ -.\" $OpenBSD: X509_ALGOR_dup.3,v 1.18 2023/10/09 16:59:55 tb Exp $ +.\" $OpenBSD: X509_ALGOR_dup.3,v 1.19 2023/10/10 13:59:47 tb Exp $ .\" OpenSSL 4692340e Jun 7 15:49:08 2016 -0400 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: .\" +.\" Copyright (c) 2023 Theo Buehler .\" Copyright (c) 2016 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -65,7 +66,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: October 9 2023 $ +.Dd $Mdocdate: October 10 2023 $ .Dt X509_ALGOR_DUP 3 .Os .Sh NAME @@ -112,17 +113,39 @@ .Fa "const X509_ALGOR *b" .Fc .Sh DESCRIPTION -.Fn X509_ALGOR_new -allocates and initializes an empty +An .Vt X509_ALGOR -object, representing an ASN.1 +object represents an ASN.1 .Vt AlgorithmIdentifier structure defined in RFC 5280 section 4.1.1.2. -Such objects can specify a cryptographic algorithm together -with algorithm-specific parameters. -They are used by many other objects, for example certificates, +It specifies a cryptographic +.Fa algorithm +by an ASN.1 object identifier (OID) that can be obtained from +.Xr OBJ_nid2obj 3 , +together with optional algorithm-specific +.Fa parameters +of the type +.Vt ASN1_TYPE , +see +.Xr ASN1_TYPE_set 3 . +.Vt X509_ALGOR +objects are used by many other objects, for example certificates, certificate revocation lists, and certificate requests. .Pp +.Fn X509_ALGOR_new +allocates a new +.Vt X509_ALGOR +object containing the object that +.Xr OBJ_nid2obj 3 +returns for +.Dv NID_undef +as the +.Fa algorithm +and a +.Dv NULL +pointer as the +.Fa parameters . +.Pp .Fn X509_ALGOR_free frees .Fa alg @@ -210,12 +233,7 @@ can leave .Fa alg in a corrupted state due to memory allocation failure. This problem can be avoided by preallocating with an error-checked call to -.Fn X509_ALGOR_set0 alg NULL 0 NULL , -or the failure can be identified by -.Fn X509_ALGOR_get0 &aobj NULL NULL alg -returning a -.Dv NULL -.Fa aobj . +.Fn X509_ALGOR_set0 alg NULL 0 NULL . .Pp .Fn X509_ALGOR_cmp compares @@ -249,6 +267,7 @@ have identical encodings or non-zero otherwise. .Xr ASN1_TYPE_set 3 , .Xr d2i_X509_ALGOR 3 , .Xr EVP_DigestInit 3 , +.Xr OBJ_nid2obj 3 , .Xr X509_get0_signature 3 , .Xr X509_new 3 , .Xr X509_PUBKEY_get0_param 3 , -- 2.20.1