Documenting newly added CMS modification
authorDmitry Belyavskiy <beldmit@gmail.com>
Tue, 21 Jan 2020 12:04:42 +0000 (15:04 +0300)
committerDmitry Belyavskiy <beldmit@gmail.com>
Tue, 3 Mar 2020 13:34:40 +0000 (16:34 +0300)
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)

doc/man1/openssl-cms.pod.in
doc/man3/CMS_add1_recipient_cert.pod
doc/man3/CMS_decrypt.pod
doc/man3/CMS_get0_RecipientInfos.pod
util/missingcrypto.txt

index 1965a95..161408f 100644 (file)
@@ -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
index b68183d..34d1e0e 100644 (file)
@@ -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
index 0c5834c..3124fa8 100644 (file)
@@ -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
index 5d19e3d..c635438 100644 (file)
@@ -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
index be5535b..99c2883 100644 (file)
@@ -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)