Documenting newly added CMS modification

Documented CMS-related API functions.
Documented flags added to openssl-cms command

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10904)

diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in
index 1965a952bef84e547ad65ae17cc3c357e8f814d0..161408fdcbaf18782b1c5bfbf1836b9e66d4e2c3 100644 (file)
--- a/doc/man1/openssl-cms.pod.in
+++ b/doc/man1/openssl-cms.pod.in
@@ -46,6 +46,7 @@ B<openssl> B<cms>
 [B<-print>]
 [B<-md> I<digest>]
 [B<-I<cipher>>]
+[B<-wrap> I<cipher>]
 [B<-nointern>]
 [B<-noverify>]
 [B<-nocerts>]
@@ -58,6 +59,7 @@ B<openssl> B<cms>
 [B<-certfile> I<file>]
 [B<-certsout> I<file>]
 [B<-signer> I<file>]
+[B<-originator> I<file>]
 [B<-recip> I<file>]
 [B<-keyid>]
 [B<-receipt_request_all>]
@@ -300,6 +302,12 @@ supported by your version of OpenSSL.
 If not specified triple DES is used. Only used with B<-encrypt> and
 B<-EncryptedData_create> commands.
 
+=item B<-wrap> I<cipher>
+
+Cipher algorithm to use for key wrap when encrypting the message using Key
+Agreement for key transport. The algorithm specified should be suitable for key
+wrap.
+
 =item B<-nointern>
 
 When verifying a message normally certificates (if any) included in
@@ -374,6 +382,11 @@ used multiple times if more than one signer is required. If a message is being
 verified then the signers certificates will be written to this file if the
 verification was successful.
 
+=item B<-originator> I<file>
+
+A certificate of the originator of the encrypted message. Necessary for
+decryption when Key Agreement is in use for a shared key.
+
 =item B<-recip> I<file>
 
 When decrypting a message this specifies the recipients certificate. The

diff --git a/doc/man3/CMS_add1_recipient_cert.pod b/doc/man3/CMS_add1_recipient_cert.pod
index b68183d109b6d67ba8d9bc7e16d28b413b575a29..34d1e0ee3651dd4611ccb235698bcfe4e7d5fac3 100644 (file)
--- a/doc/man3/CMS_add1_recipient_cert.pod
+++ b/doc/man3/CMS_add1_recipient_cert.pod
@@ -2,12 +2,16 @@
 
 =head1 NAME
 
-CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
+CMS_add1_recipient, CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
 
 =head1 SYNOPSIS
 
  #include <openssl/cms.h>
 
+ CMS_RecipientInfo *CMS_add1_recipient(CMS_ContentInfo *cms, X509 *recip,
+                                       EVP_PKEY *originatorPrivKey, 
+                                       X509 *originator, unsigned int flags);
+
  CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms,
                                             X509 *recip, unsigned int flags);
 
@@ -20,6 +24,11 @@ CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS envelo
 
 =head1 DESCRIPTION
 
+CMS_add1_recipient() adds recipient B<recip> and provides the originator pkey
+B<originatorPrivKey> and originator certificate B<originator> to CMS_ContentInfo.
+The originator-related fields are relevant only in case when the keyAgreement
+method of providing of the shared key is in use.
+
 CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped
 data structure B<cms> as a KeyTransRecipientInfo structure.
 
@@ -60,9 +69,14 @@ occurs.
 L<ERR_get_error(3)>, L<CMS_decrypt(3)>,
 L<CMS_final(3)>,
 
+=head1 HISTORY
+
+B<CMS_add1_recipient_cert> and B<CMS_add0_recipient_key> were added in
+OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

diff --git a/doc/man3/CMS_decrypt.pod b/doc/man3/CMS_decrypt.pod
index 0c5834c54943fe820cab70fe2007cc789e57b846..3124fa8394b92b8f64665ff6663cf539db1614ba 100644 (file)
--- a/doc/man3/CMS_decrypt.pod
+++ b/doc/man3/CMS_decrypt.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-CMS_decrypt - decrypt content from a CMS envelopedData structure
+CMS_decrypt, CMS_decrypt_set1_pkey_and_peer, CMS_decrypt_set1_pkey - decrypt
+content from a CMS envelopedData structure
 
 =head1 SYNOPSIS
 
@@ -10,6 +11,9 @@ CMS_decrypt - decrypt content from a CMS envelopedData structure
 
  int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert,
                  BIO *dcont, BIO *out, unsigned int flags);
+ int CMS_decrypt_set1_pkey_and_peer(CMS_ContentInfo *cms,
+                 EVP_PKEY *pk, X509 *cert, X509 *peer);
+ int CMS_decrypt_set1_pkey(CMS_ContentInfo *cms, EVP_PKEY *pk, X509 *cert);
 
 =head1 DESCRIPTION
 
@@ -21,6 +25,13 @@ B<flags> is an optional set of flags.
 The B<dcont> parameter is used in the rare case where the encrypted content
 is detached. It will normally be set to NULL.
 
+CMS_decrypt_set1_pkey_and_peer() associates the private key B<pkey>, the
+corresponding certificate B<cert> and the originator certificate B<peer> with
+the CMS_ContentInfo structure B<cms>.
+
+CMS_decrypt_set1_pkey() associates the private key B<pkey>, corresponding
+certificate B<cert> with the CMS_ContentInfo structure B<cms>.
+
 =head1 NOTES
 
 Although the recipients certificate is not needed to decrypt the data it is
@@ -70,9 +81,13 @@ mentioned in CMS_verify() also applies to CMS_decrypt().
 
 L<ERR_get_error(3)>, L<CMS_encrypt(3)>
 
+=head1 HISTORY
+
+B<CMS_decrypt_set1_pkey_and_peer> was added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

diff --git a/doc/man3/CMS_get0_RecipientInfos.pod b/doc/man3/CMS_get0_RecipientInfos.pod
index 5d19e3d1780433d95b2b1663bbb5e94e4de88550..c6354381fc2305c8b7d06a4d82280843a8ab0726 100644 (file)
--- a/doc/man3/CMS_get0_RecipientInfos.pod
+++ b/doc/man3/CMS_get0_RecipientInfos.pod
@@ -5,6 +5,8 @@
 CMS_get0_RecipientInfos, CMS_RecipientInfo_type,
 CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp,
 CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id,
+CMS_RecipientInfo_kari_set0_pkey_and_peer,
+CMS_RecipientInfo_kari_set0_pkey,
 CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key,
 CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt
 - CMS envelopedData RecipientInfo routines
@@ -22,7 +24,9 @@ CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt
                                            ASN1_INTEGER **sno);
  int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
  int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
-
+ int CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri,
+                                               EVP_PKEY *pk, X509 *peer);
+ int CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
  int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg,
                                      ASN1_OCTET_STRING **pid,
                                      ASN1_GENERALIZEDTIME **pdate,
@@ -58,6 +62,13 @@ CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with
 the CMS_RecipientInfo structure B<ri>, which must be of type
 CMS_RECIPINFO_TRANS.
 
+CMS_RecipientInfo_kari_set0_pkey_and_peer() associates the private key B<pkey>
+and peer certificate B<peer> with the CMS_RecipientInfo structure B<ri>, which
+must be of type CMS_RECIPINFO_AGREE.
+
+CMS_RecipientInfo_kari_set0_pkey() associates the private key B<pkey> with the
+CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_AGREE.
+
 CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the
 CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK.  Any
 of the remaining parameters can be NULL if the application is not interested in
@@ -127,9 +138,14 @@ Any error can be obtained from L<ERR_get_error(3)>.
 
 L<ERR_get_error(3)>, L<CMS_decrypt(3)>
 
+=head1 HISTORY
+
+B<CMS_RecipientInfo_kari_set0_pkey_and_peer> and B<CMS_RecipientInfo_kari_set0_pkey> 
+were added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index be5535b87d70710403ba149cfbffc0ba77fa7007..99c2883bd0e4ffb4e26ea656b549ebd76cca8b11 100644 (file)
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -325,7 +325,6 @@ CMS_RecipientInfo_kari_get0_ctx(3)
 CMS_RecipientInfo_kari_get0_orig_id(3)
 CMS_RecipientInfo_kari_get0_reks(3)
 CMS_RecipientInfo_kari_orig_id_cmp(3)
-CMS_RecipientInfo_kari_set0_pkey(3)
 CMS_RecipientInfo_ktri_get0_algs(3)
 CMS_RecipientInfo_set0_password(3)
 CMS_SharedInfo_encode(3)
@@ -347,7 +346,6 @@ CMS_dataInit(3)
 CMS_data_create(3)
 CMS_decrypt_set1_key(3)
 CMS_decrypt_set1_password(3)
-CMS_decrypt_set1_pkey(3)
 CMS_digest_create(3)
 CMS_digest_verify(3)
 CMS_is_detached(3)