From 348900774c14dd79c9cf762d59554f38d8c77120 Mon Sep 17 00:00:00 2001 From: Dmitry Belyavskiy Date: Tue, 21 Jan 2020 15:04:42 +0300 Subject: [PATCH] Documenting newly added CMS modification Documented CMS-related API functions. Documented flags added to openssl-cms command Reviewed-by: Shane Lontis Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/10904) --- doc/man1/openssl-cms.pod.in | 13 +++++++++++++ doc/man3/CMS_add1_recipient_cert.pod | 18 ++++++++++++++++-- doc/man3/CMS_decrypt.pod | 19 +++++++++++++++++-- doc/man3/CMS_get0_RecipientInfos.pod | 20 ++++++++++++++++++-- util/missingcrypto.txt | 2 -- 5 files changed, 64 insertions(+), 8 deletions(-) diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in index 1965a952be..161408fdcb 100644 --- a/doc/man1/openssl-cms.pod.in +++ b/doc/man1/openssl-cms.pod.in @@ -46,6 +46,7 @@ B B [B<-print>] [B<-md> I] [B<-I>] +[B<-wrap> I] [B<-nointern>] [B<-noverify>] [B<-nocerts>] @@ -58,6 +59,7 @@ B B [B<-certfile> I] [B<-certsout> I] [B<-signer> I] +[B<-originator> I] [B<-recip> I] [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 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 + +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 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 b68183d109..34d1e0ee36 100644 --- 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 + 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 and provides the originator pkey +B and originator certificate B 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 to CMS_ContentInfo enveloped data structure B as a KeyTransRecipientInfo structure. @@ -60,9 +69,14 @@ occurs. L, L, L, +=head1 HISTORY + +B and B 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 0c5834c549..3124fa8394 100644 --- 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 is an optional set of flags. The B 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, the +corresponding certificate B and the originator certificate B with +the CMS_ContentInfo structure B. + +CMS_decrypt_set1_pkey() associates the private key B, corresponding +certificate B with the CMS_ContentInfo structure B. + =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, L +=head1 HISTORY + +B 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 5d19e3d178..c6354381fc 100644 --- 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 with the CMS_RecipientInfo structure B, which must be of type CMS_RECIPINFO_TRANS. +CMS_RecipientInfo_kari_set0_pkey_and_peer() associates the private key B +and peer certificate B with the CMS_RecipientInfo structure B, which +must be of type CMS_RECIPINFO_AGREE. + +CMS_RecipientInfo_kari_set0_pkey() associates the private key B with the +CMS_RecipientInfo structure B, which must be of type CMS_RECIPINFO_AGREE. + CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the CMS_RecipientInfo structure B 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. L, L +=head1 HISTORY + +B and B +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 be5535b87d..99c2883bd0 100644 --- 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) -- 2.25.1