From 35ad8a26bc6b55e8c8acdcc4b463318f5b511918 Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Wed, 26 Jul 2023 19:30:43 +0000
Subject: [PATCH] Document CMS_SignerInfos_get_version and CMS_get_version
 which will be added in the upcoming bump.

---
 lib/libcrypto/man/CMS_get0_SignerInfos.3 | 25 ++++++++++++++++--
 lib/libcrypto/man/CMS_get0_type.3        | 32 ++++++++++++++++++++++--
 2 files changed, 53 insertions(+), 4 deletions(-)

diff --git a/lib/libcrypto/man/CMS_get0_SignerInfos.3 b/lib/libcrypto/man/CMS_get0_SignerInfos.3
index faf20c49d24..0be92d800fa 100644
--- a/lib/libcrypto/man/CMS_get0_SignerInfos.3
+++ b/lib/libcrypto/man/CMS_get0_SignerInfos.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: CMS_get0_SignerInfos.3,v 1.7 2019/11/02 15:39:46 schwarze Exp $
+.\" $OpenBSD: CMS_get0_SignerInfos.3,v 1.8 2023/07/26 19:30:43 tb Exp $
 .\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,11 +48,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 2 2019 $
+.Dd $Mdocdate: July 26 2023 $
 .Dt CMS_GET0_SIGNERINFOS 3
 .Os
 .Sh NAME
 .Nm CMS_get0_SignerInfos ,
+.Nm CMS_SignerInfo_get_version ,
 .Nm CMS_SignerInfo_get0_signer_id ,
 .Nm CMS_SignerInfo_get0_signature ,
 .Nm CMS_SignerInfo_cert_cmp ,
@@ -65,6 +66,11 @@
 .Fa "CMS_ContentInfo *cms"
 .Fc
 .Ft int
+.Fo CMS_SignerInfo_get_version
+.Fa "CMS_SignerInfo *si"
+.Fa "long *version"
+.Fc
+.Ft int
 .Fo CMS_SignerInfo_get0_signer_id
 .Fa "CMS_SignerInfo *si"
 .Fa "ASN1_OCTET_STRING **keyid"
@@ -94,6 +100,14 @@ structures associated with the
 structure
 .Fa cms .
 .Pp
+.Fn CMS_SignerInfo_get_version
+sets
+.Pf * Fa version
+to the syntax version number of the
+.Vt SignerInfo
+structure
+.Fa si .
+.Pp
 .Fn CMS_SignerInfo_get0_signer_id
 retrieves the certificate
 .Vt SignerIdentifier
@@ -157,6 +171,9 @@ if there are no signers or if
 is not of the type
 .Vt SignedData .
 .Pp
+.Fn CMS_SignerInfo_get_version
+always succeeds and returns 1.
+.Pp
 .Fn CMS_SignerInfo_get0_signer_id
 returns 1 for success or 0 for failure.
 .Pp
@@ -190,3 +207,7 @@ first appeared in OpenSSL 0.9.8h and
 in OpenSSL 1.0.2.
 These functions have been available since
 .Ox 6.7 .
+.Pp
+.Fn CMS_SignerInfo_get_version
+first appeared in
+.Ox 7.4 .
diff --git a/lib/libcrypto/man/CMS_get0_type.3 b/lib/libcrypto/man/CMS_get0_type.3
index 45ed3167b59..6b30fe2572a 100644
--- a/lib/libcrypto/man/CMS_get0_type.3
+++ b/lib/libcrypto/man/CMS_get0_type.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: CMS_get0_type.3,v 1.7 2019/11/02 15:39:46 schwarze Exp $
+.\" $OpenBSD: CMS_get0_type.3,v 1.8 2023/07/26 19:30:43 tb Exp $
 .\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000
 .\"
 .\" This file is a derived work.
@@ -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: November 2 2019 $
+.Dd $Mdocdate: July 26 2023 $
 .Dt CMS_GET0_TYPE 3
 .Os
 .Sh NAME
 .Nm CMS_get0_type ,
+.Nm CMS_get_version ,
 .Nm CMS_set1_eContentType ,
 .Nm CMS_get0_eContentType ,
 .Nm CMS_get0_content
@@ -81,6 +82,11 @@
 .Fa "const CMS_ContentInfo *cms"
 .Fc
 .Ft int
+.Fo CMS_get_version
+.Fa "const CMS_ContentInfo *cms"
+.Fa "long *version"
+.Fc
+.Ft int
 .Fo CMS_set1_eContentType
 .Fa "CMS_ContentInfo *cms"
 .Fa "const ASN1_OBJECT *oid"
@@ -149,6 +155,21 @@ copies the supplied
 .Fa oid ,
 so it should be freed up after use.
 .Pp
+.Fn CMS_get_version
+sets
+.Pf * Fa version
+to the syntax version number of the
+.Vt ContentType
+structure
+.Fa cms .
+The version is a number between 0 and 5 and is defined for all the
+above content types except for arbitrary data.
+For arbitrary data and unsupported content types
+.Fn CMS_get_version
+fails and the content of
+.Pf * Fa version
+is unspecified.
+.Pp
 .Fn CMS_get0_eContentType
 returns the type of the embedded content.
 .Pp
@@ -176,6 +197,9 @@ return internal pointers to
 .Vt OBJECT IDENTIFIER
 structures.
 .Pp
+.Fn CMS_get_version
+returns 1 on success and 0 on failure.
+.Pp
 .Fn CMS_get0_content
 returns an internal pointer to the storage location where the pointer
 to the embedded content is stored.
@@ -196,3 +220,7 @@ RFC 3274: Compressed Data Content Type for Cryptographic Message Syntax (CMS)
 These functions first appeared in OpenSSL 0.9.8h
 and have been available since
 .Ox 6.7 .
+.Pp
+.Fn CMS_get_version
+first appeared in
+.Ox 7.4 .
-- 
2.20.1