some cleanup:

* state the common, general purpose up front
* more precision regarding which ASN.1 types and fields are involved
* mark up the ASN.1 type and field names
* add the missing STANDARDS section
* and minor wording improvements

1 files changed, 62 insertions, 29 deletions

diff --git a/lib/libcrypto/man/CMS_add1_recipient_cert.3 b/lib/libcrypto/man/CMS_add1_recipient_cert.3
index d8aacb203c5..4ba15c41c05 100644
--- a/lib/libcrypto/man/CMS_add1_recipient_cert.3
+++ b/lib/libcrypto/man/CMS_add1_recipient_cert.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: CMS_add1_recipient_cert.3,v 1.4 2019/08/11 12:46:38 schwarze Exp $
+.\" $OpenBSD: CMS_add1_recipient_cert.3,v 1.5 2019/08/13 23:54:16 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,19 +65,19 @@
 .\" 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 13 2019 $
 .Dt CMS_ADD1_RECIPIENT_CERT 3
 .Os
 .Sh NAME
 .Nm CMS_add1_recipient_cert ,
 .Nm CMS_add0_recipient_key
-.Nd add recipients to a CMS enveloped data structure
+.Nd add recipients to a CMS EnvelopedData structure
 .Sh SYNOPSIS
 .In openssl/cms.h
 .Ft CMS_RecipientInfo *
 .Fo CMS_add1_recipient_cert
 .Fa "CMS_ContentInfo *cms"
-.Fa "X509 *recip"
+.Fa "X509 *certificate"
 .Fa "unsigned int flags"
 .Fc
 .Ft CMS_RecipientInfo *
@@ -76,17 +93,29 @@
 .Fa "ASN1_TYPE *otherType"
 .Fc
 .Sh DESCRIPTION
+These functions add a new
+.Vt RecipientInfo
+structure to the
+.Fa recipientInfos
+field of the
+.Vt EnvelopedData
+structure
+.Fa cms ,
+which should have been obtained from an initial call to
+.Xr CMS_encrypt 3
+with the flag
+.Dv CMS_PARTIAL
+set.
+.Pp
 .Fn CMS_add1_recipient_cert
 adds the recipient
-.Fa recip
-to the
-.Vt CMS_ContentInfo
-enveloped data structure
-.Fa cms
-as a KeyTransRecipientInfo structure.
+.Fa certificate
+as a
+.Vt KeyTransRecipientInfo
+structure.
 .Pp
 .Fn CMS_add0_recipient_key
-adds the symmetric key
+adds the symmetric
 .Fa key
 of length
 .Fa keylen
@@ -101,25 +130,18 @@ and the optional values
 .Fa otherTypeId
 and
 .Fa otherType
-to the
-.Vt CMS_ContentInfo
-enveloped data structure
-.Fa cms
-as a KEKRecipientInfo structure.
-.Pp
-The
-.Vt CMS_ContentInfo
-structure should be obtained from an initial call to
-.Xr CMS_encrypt 3
-with the flag
-.Dv CMS_PARTIAL
-set.
+as a
+.Vt KEKRecipientInfo
+structure.
 .Pp
-The main purpose of this function is to provide finer control over a CMS
-enveloped data structure where the simpler
+The main purpose of these functions is to provide finer control over a CMS
+.Vt EnvelopedData
+structure where the simpler
 .Xr CMS_encrypt 3
 function defaults are not appropriate,
-for example if one or more KEKRecipientInfo structures need to be added.
+for example if one or more
+.Vt KEKRecipientInfo
+structures need to be added.
 New attributes can also be added using the returned
 .Vt CMS_RecipientInfo
 structure and the CMS attribute utility functions.
@@ -128,7 +150,7 @@ By default, recipient certificates are identified using issuer
 name and serial number.
 If the flag
 .Dv CMS_USE_KEYID
-is set, it will use the subject key identifier value instead.
+is set, the subject key identifier value is used instead.
 An error occurs if all recipient certificates do not have a subject key
 identifier extension.
 .Pp
@@ -156,8 +178,19 @@ structure just added or
 if an error occurs.
 .Sh SEE ALSO
 .Xr CMS_decrypt 3 ,
+.Xr CMS_encrypt 3 ,
 .Xr CMS_final 3 ,
 .Xr ERR_get_error 3
+.Sh STANDARDS
+RFC 5652: Cryptographic Message Syntax
+.Bl -dash -compact -offset indent
+.It
+section 6.1: EnvelopedData Type
+.It
+section 6.2.1: KeyTransRecipientInfo Type
+.It
+section 6.2.3: KEKRecipientInfo Type
+.El
 .Sh HISTORY
 .Fn CMS_add1_recipient_cert
 and