some cleanup:

* avoid repetitions and jumping back and forth between the functions
* more precision regarding which ASN.1 types and fields are involved
* mark up the ASN.1 type and field names
* explain CMS_REUSE_DIGEST more precisely
* move the discussion of attributes to CMS_NOATTR where it belongs
* GOST does not need an ENGINE in LibreSSL, so don't use it as an example
* add the missing STANDARDS section
* and minor wording improvements

1 files changed, 96 insertions, 58 deletions

diff --git a/lib/libcrypto/man/CMS_add1_signer.3 b/lib/libcrypto/man/CMS_add1_signer.3
index 8f08dac6d6a..ea7d0a6dc31 100644
--- a/lib/libcrypto/man/CMS_add1_signer.3
+++ b/lib/libcrypto/man/CMS_add1_signer.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: CMS_add1_signer.3,v 1.4 2019/08/11 12:46:38 schwarze Exp $
+.\" $OpenBSD: CMS_add1_signer.3,v 1.5 2019/08/14 11:54:23 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>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2008 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,13 +65,13 @@
 .\" 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 14 2019 $
 .Dt CMS_ADD1_SIGNER 3
 .Os
 .Sh NAME
 .Nm CMS_add1_signer ,
 .Nm CMS_SignerInfo_sign
-.Nd add a signer to a CMS_ContentInfo signed data structure
+.Nd add a signer to a CMS SignedData structure
 .Sh SYNOPSIS
 .In openssl/cms.h
 .Ft CMS_SignerInfo *
@@ -78,49 +95,40 @@ and private key
 using message digest
 .Fa md
 to the
-.Vt CMS_ContentInfo
-SignedData structure
-.Fa cms .
-.Pp
-The
-.Vt CMS_ContentInfo
-structure should be obtained from an initial call to
+.Fa signerInfos
+field of the
+.Vt SignedData
+structure
+.Fa cms ,
+which should have been obtained from an initial call to
 .Xr CMS_sign 3
 with the flag
 .Dv CMS_PARTIAL
-set or in the case or re-signing a valid
-.Vt CMS_ContentInfo
-SignedData structure.
+set, or which can be a valid
+.Vt SignedData
+structure in the case of re-signing.
 .Pp
-If the
+If
 .Fa md
-parameter is
+is
 .Dv NULL ,
-then the default digest for the public key algorithm will be used.
+the default digest for the public key algorithm of
+.Fa pkey
+is used.
 .Pp
 Unless the
 .Dv CMS_REUSE_DIGEST
-flag is set, the returned
-.Vt CMS_ContentInfo
-structure is not complete and must be finalized either by streaming
-(if applicable) or a call to
+flag is set, the
+.Fa cms
+structure remains incomplete and must be finalized either by streaming
+(if applicable) or by a call to
 .Xr CMS_final 3 .
 .Pp
-The
-.Fn CMS_SignerInfo_sign
-function will explicitly sign a
-.Vt CMS_SignerInfo
-structure.
-Its main use is when the
-.Dv CMS_REUSE_DIGEST
-and
-.Dv CMS_PARTIAL
-flags are both set.
-.Pp
 The main purpose of
 .Fn CMS_add1_signer
-is to provide finer control over a CMS signed data structure where the
-simpler
+is to provide finer control over a CMS
+.Vt SignedData
+structure where the simpler
 .Xr CMS_sign 3
 function defaults are not appropriate, for example if multiple signers
 or non default digest algorithms are needed.
@@ -134,39 +142,50 @@ Any of the following flags (OR'ed together) can be passed in the
 parameter:
 .Bl -tag -width Ds
 .It Dv CMS_REUSE_DIGEST
-Attempt to copy the content digest value from the
-.Vt CMS_ContentInfo
-structure to add a signer to an existing structure.
+Attempt to copy the content digest value from one of the existing
+.Vt CMS_SignerInfo
+structures in
+.Fa cms
+while adding another signer.
 An error occurs if a matching digest value cannot be found to copy.
-The returned
-.Vt CMS_ContentInfo
+The
+.Fa cms
 structure will be valid and finalized when this flag is set.
 .It Dv CMS_PARTIAL
 If this flag is set in addition to
 .Dv CMS_REUSE_DIGEST ,
-then the
+the returned
 .Vt CMS_SignerInfo
 structure will not be finalized so additional attributes can be added.
 In this case an explicit call to
 .Fn CMS_SignerInfo_sign
 is needed to finalize it.
 .It Dv CMS_NOCERTS
-Do not include the signer's certificate in the
-.Vt CMS_ContentInfo
-structure.
+Do not add the signer's certificate to the
+.Fa certificates
+field of
+.Fa cms .
 The signer's certificate must still be supplied in the
 .Fa signcert
 parameter though.
-This can reduce the size of the signature if the signer's certificate can
+This flag 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.
-.Pp
-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.
 .It Dv CMS_NOATTR
-Use no signedAttributes.
+Leave the
+.Fa signedAttrs
+field of the returned
+.Vt CMS_SignedData
+structure empty.
+By default, several CMS
+.Vt SignedAttributes
+are added, 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
+attribute.
 .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
@@ -174,22 +193,30 @@ identifier extension.
 By default, issuer name and serial number are used instead.
 .El
 .Pp
-If present, the SMIMECapabilities attribute indicates support for the
+If present, the
+.Vt 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.
 .Pp
+The
+.Fn CMS_SignerInfo_sign
+function explicitly signs
+.Fa si .
+Its main use is when the
+.Dv CMS_REUSE_DIGEST
+and
+.Dv CMS_PARTIAL
+flags were both set in the call to
 .Fn CMS_add1_signer
-returns an internal pointer to the
-.Vt CMS_SignerInfo
-structure just added.
-This can be used to set additional attributes before it is finalized.
+that created
+.Fa si .
 .Sh RETURN VALUES
 .Fn CMS_add1_signer
-returns an internal pointer to the
+returns an internal pointer to the new
 .Vt CMS_SignerInfo
 structure just added or
 .Dv NULL
@@ -198,6 +225,17 @@ if an error occurs.
 .Xr CMS_final 3 ,
 .Xr CMS_sign 3 ,
 .Xr ERR_get_error 3
+.Sh STANDARDS
+RFC 5652: Cryptographic Message Syntax, section 5.1: SignedData Type
+.Pp
+RFC 8551: Secure/Multipurpose Internet Mail Extensions (S/MIME)
+Version\ 4.0 Message Specification
+.Bl -dash -compact -offset indent
+.It
+section 2.5: Attributes and the SignerInfo Type
+.It
+section 2.5.2: SMIMECapabilities Attribute
+.El
 .Sh HISTORY
 .Fn CMS_add1_signer
 and