From 0fc04f9f313a0675c6689b0b146c615e2005c6d8 Mon Sep 17 00:00:00 2001
From: schwarze <>
Date: Sun, 18 Aug 2019 12:06:51 +0000
Subject: minor cleanup: * add the missing STANDARDS sections * mark up ASN.1
 type names * GOST does not need an ENGINE in LibreSSL, so don't use it as an
 example * and minor wording improvements and typo fixes

---
 src/lib/libcrypto/man/CMS_sign.3           | 49 ++++++++++++++++++++----------
 src/lib/libcrypto/man/CMS_sign_receipt.3   | 21 ++++++++-----
 src/lib/libcrypto/man/CMS_verify.3         | 38 +++++++++++------------
 src/lib/libcrypto/man/CMS_verify_receipt.3 | 20 ++++++------
 4 files changed, 74 insertions(+), 54 deletions(-)

(limited to 'src/lib')

diff --git a/src/lib/libcrypto/man/CMS_sign.3 b/src/lib/libcrypto/man/CMS_sign.3
index 1ef0f2d48a..1dfd153ee2 100644
--- a/src/lib/libcrypto/man/CMS_sign.3
+++ b/src/lib/libcrypto/man/CMS_sign.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: CMS_sign.3,v 1.5 2019/08/12 16:17:50 schwarze Exp $
+.\" $OpenBSD: CMS_sign.3,v 1.6 2019/08/18 12:06:51 schwarze Exp $
 .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 12 2019 $
+.Dd $Mdocdate: August 18 2019 $
 .Dt CMS_SIGN 3
 .Os
 .Sh NAME
@@ -66,7 +66,9 @@
 .Fc
 .Sh DESCRIPTION
 .Fn CMS_sign
-creates and returns a CMS SignedData structure.
+creates and returns a CMS
+.Vt SignedData
+structure.
 .Fa signcert
 is the certificate to sign with,
 .Fa pkey
@@ -80,12 +82,9 @@ Any or all of these parameters can be
 The data to be signed is read from
 .Fa data .
 .Pp
-.Fa flags
-is an optional set of flags.
-.Pp
 Any of the following flags (OR'ed together) can be passed in the
 .Fa flags
-parameter:
+argument:
 .Bl -tag -width Ds
 .It Dv CMS_TEXT
 Prepend MIME headers for the type text/plain to the data.
@@ -98,8 +97,8 @@ structure.
 The signer's certificate must still be supplied in the
 .Fa signcert
 parameter though.
-This can reduce the size of the signature if the signers certificate can
-be obtained by other means: for example a previously signed message.
+This can reduce the size of the signature if the signer's certificate can
+be obtained by other means, for example from a previously signed message.
 .It Dv CMS_DETACHED
 Omit the data being signed from the
 .Vt CMS_ContentInfo
@@ -114,19 +113,25 @@ even though that is required by the S/MIME specifications.
 This option should be used if the supplied data is in binary format.
 Otherwise the translation will corrupt it.
 .It Dv CMS_NOATTR
-Do not use any signedAttributes.
-By default, the SignedData structure includes several CMS
-signedAttributes including the signing time, the CMS content type,
-and the supported list of ciphers in an SMIMECapabilities attribute.
+Do not add any
+.Vt SignedAttributes .
+By default, the
+.Fa signerInfos
+field includes several CMS
+.Vt SignedAttributes
+including the signing time, the CMS content type,
+and the supported list of ciphers in an
+.Vt SMIMECapabilities
+attribute.
 .It Dv CMS_NOSMIMECAP
-Omit just the SMIMECapabilities.
+Omit just the
+.Vt SMIMECapabilities .
 If present, the SMIMECapabilities attribute indicates support for the
 following algorithms in preference order: 256 bit AES, Gost R3411-94,
 Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit
 RC2, DES and 40 bit RC2.
 If any of these algorithms is not available, then it will not be
-included: for example the GOST algorithms will not be included if
-the GOST ENGINE is not loaded.
+included.
 .It Dv CMS_USE_KEYID
 Use the subject key identifier value to identify signing certificates.
 An error occurs if the signing certificate does not have a subject key
@@ -212,6 +217,18 @@ The error can be obtained from
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr CMS_verify 3
+.Sh STANDARDS
+RFC 5652: Cryptographic Message Syntax (CMS)
+.Bl -dash -compact -offset indent
+.It
+section 5.1: SignedData Type
+.It
+section 5.3: SignerInfo Type
+.El
+.Pp
+RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME)
+Version\ 4.0 Message Specification,
+section 2.5.2: SMIMECapabilities Attribute
 .Sh HISTORY
 .Fn CMS_sign
 first appeared in OpenSSL 0.9.8h
diff --git a/src/lib/libcrypto/man/CMS_sign_receipt.3 b/src/lib/libcrypto/man/CMS_sign_receipt.3
index 88d03d79db..e827900a84 100644
--- a/src/lib/libcrypto/man/CMS_sign_receipt.3
+++ b/src/lib/libcrypto/man/CMS_sign_receipt.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: CMS_sign_receipt.3,v 1.4 2019/08/11 12:46:38 schwarze Exp $
+.\" $OpenBSD: CMS_sign_receipt.3,v 1.5 2019/08/18 12:06:51 schwarze Exp $
 .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 11 2019 $
+.Dd $Mdocdate: August 18 2019 $
 .Dt CMS_SIGN_RECEIPT 3
 .Os
 .Sh NAME
@@ -66,10 +66,14 @@
 .Fc
 .Sh DESCRIPTION
 .Fn CMS_sign_receipt
-creates and returns a CMS signed receipt structure.
+creates a new CMS
+.Vt SignedData
+structure containing a signed
+.Vt Receipt
+as its embedded content.
 .Fa si
 is the
-.Vt CMS_SignerInfo
+.Vt SignerInfo
 structure containing the signed receipt request.
 .Fa signcert
 is the certificate to sign with,
@@ -79,12 +83,11 @@ is the corresponding private key.
 is an optional additional set of certificates to include in the CMS
 structure (for example any intermediate CAs in the chain).
 .Pp
-.Fa flags
-is an optional set of flags.
-.Pp
 This functions behaves in a similar way to
 .Xr CMS_sign 3
-except the flag values
+except that the
+.Fa flags
+values
 .Dv CMS_DETACHED ,
 .Dv CMS_BINARY ,
 .Dv CMS_NOATTR ,
@@ -105,6 +108,8 @@ The error can be obtained from
 .Sh SEE ALSO
 .Xr CMS_sign 3 ,
 .Xr CMS_verify_receipt 3
+.Sh STANDARDS
+RFC 2634: Enhanced Security Services for S/MIME, section 2.8: Receipt Syntax
 .Sh HISTORY
 .Fn CMS_sign_receipt
 first appeared in OpenSSL 0.9.8h
diff --git a/src/lib/libcrypto/man/CMS_verify.3 b/src/lib/libcrypto/man/CMS_verify.3
index 5b17a75ca0..ae489933de 100644
--- a/src/lib/libcrypto/man/CMS_verify.3
+++ b/src/lib/libcrypto/man/CMS_verify.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: CMS_verify.3,v 1.4 2019/08/11 12:46:38 schwarze Exp $
+.\" $OpenBSD: CMS_verify.3,v 1.5 2019/08/18 12:06:51 schwarze Exp $
 .\" full merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 11 2019 $
+.Dd $Mdocdate: August 18 2019 $
 .Dt CMS_VERIFY 3
 .Os
 .Sh NAME
@@ -72,11 +72,10 @@
 .Fc
 .Sh DESCRIPTION
 .Fn CMS_verify
-verifies a CMS SignedData structure.
-.Fa cms
-is the
-.Vt CMS_ContentInfo
-structure to verify.
+verifies the CMS
+.Vt SignedData
+structure
+.Fa cms .
 .Fa certs
 is a set of certificates in which to search for the signing
 certificate(s).
@@ -90,10 +89,6 @@ The content is written to
 if it is not
 .Dv NULL .
 .Pp
-.Fa flags
-is an optional set of flags, which can be used to modify the verify
-operation.
-.Pp
 .Fn CMS_get0_signers
 retrieves the signing certificate(s) from
 .Fa cms .
@@ -105,11 +100,8 @@ Normally the verify process proceeds as follows.
 .Pp
 Initially some sanity checks are performed on
 .Fa cms .
-The type of
-.Fa cms
-must be SignedData.
-There must be at least one signature on the data and if the content is
-detached;
+There must be at least one signature on the data.
+If the content is detached,
 .Fa indata
 cannot be
 .Dv NULL .
@@ -126,7 +118,8 @@ If any signing certificate cannot be located, the operation fails.
 .Pp
 Each signing certificate is chain verified using the
 .Sy smimesign
-purpose and the supplied trusted certificate store.
+purpose and the supplied trusted certificate
+.Fa store .
 Any internal certificates in the message are used as untrusted CAs.
 If CRL checking is enabled in
 .Fa store ,
@@ -142,9 +135,9 @@ and the signature is checked.
 .Pp
 If all signatures verify correctly, then the function is successful.
 .Pp
-Any of the following flags (OR'ed together) can be passed in the
+Any of the following
 .Fa flags
-parameter to change the default verify behaviour:
+(OR'ed together) can be passed to change the default verify behaviour:
 .Bl -tag -width Ds
 .It Dv CMS_NOINTERN
 Do not use the certificates in the message itself when
@@ -156,7 +149,7 @@ parameter.
 If CRL checking is enabled in
 .Fa store ,
 then any CRLs in the message itself are ignored.
-It Dv CMS_TEXT
+.It Dv CMS_TEXT
 MIME headers for type text/plain are deleted from the content.
 If the content is not of type text/plain, an error is returned.
 .It Dv CMS_NO_SIGNER_CERT_VERIFY
@@ -199,7 +192,7 @@ However since the signing time is supplied by the signer it cannot be
 trusted without additional evidence (such as a trusted timestamp).
 .Sh RETURN VALUES
 .Fn CMS_verify
-returns 1 for a successful verification or zero if an error occurred.
+returns 1 for a successful verification or 0 if an error occurred.
 .Pp
 .Fn CMS_get0_signers
 returns all signers or
@@ -210,6 +203,9 @@ The error can be obtained from
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr CMS_sign 3
+.Sh STANDARDS
+RFC 5652: Cryptographic Message Syntax (CMS),
+section 5.1: SignedData Type
 .Sh HISTORY
 These functions first appeared in OpenSSL 0.9.8h
 and have been available since
diff --git a/src/lib/libcrypto/man/CMS_verify_receipt.3 b/src/lib/libcrypto/man/CMS_verify_receipt.3
index 7e74faa3e2..8f9a86f128 100644
--- a/src/lib/libcrypto/man/CMS_verify_receipt.3
+++ b/src/lib/libcrypto/man/CMS_verify_receipt.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: CMS_verify_receipt.3,v 1.4 2019/08/11 12:46:38 schwarze Exp $
+.\" $OpenBSD: CMS_verify_receipt.3,v 1.5 2019/08/18 12:06:51 schwarze Exp $
 .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 11 2019 $
+.Dd $Mdocdate: August 18 2019 $
 .Dt CMS_VERIFY_RECEIPT 3
 .Os
 .Sh NAME
@@ -70,19 +70,19 @@ verifies a CMS signed receipt.
 .Fa rcms
 is the signed receipt to verify.
 .Fa ocms
-is the original SignedData structure containing the receipt request.
+is the original
+.Vt SignedData
+structure containing the receipt request.
 .Fa certs
 is a set of certificates in which to search for the signing certificate.
 .Fa store
 is a trusted certificate store (used for chain verification).
 .Pp
-.Fa flags
-is an optional set of flags, which can be used to modify the verify
-operation.
-.Pp
 This functions behaves in a similar way to
 .Xr CMS_verify 3
-except the flag values
+except that the
+.Fa flags
+values
 .Dv CMS_DETACHED ,
 .Dv CMS_BINARY ,
 .Dv CMS_TEXT ,
@@ -92,13 +92,15 @@ are not supported since they do not make sense in the context of signed
 receipts.
 .Sh RETURN VALUES
 .Fn CMS_verify_receipt
-returns 1 for a successful verification or zero if an error occurred.
+returns 1 for a successful verification or 0 if an error occurred.
 .Pp
 The error can be obtained from
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr CMS_sign_receipt 3 ,
 .Xr CMS_verify 3
+.Sh STANDARDS
+RFC 2634: Enhanced Security Services for S/MIME, section 2.8: Receipt Syntax
 .Sh HISTORY
 .Fn CMS_verify_receipt
 first appeared in OpenSSL 0.9.8h
-- 
cgit v1.2.3-55-g6feb