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

1 files changed, 33 insertions, 16 deletions

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