CMS sign digest

CLI changes: New parameter -digest to CLI command openssl cms, to
provide pre-computed digest for use with -sign.

API changes: New function CMS_final_digest(), like CMS_final() but
uses a pre-computed digest instead of computing it from the data.

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
Reviewed-by: Todd Short <todd.short@me.com>
(Merged from https://github.com/openssl/openssl/pull/15348)

2 files changed, 32 insertions, 4 deletions

diff --git a/doc/man1/openssl-cms.pod.in b/doc/man1/openssl-cms.pod.in
index c63a7f330b..632d7fe857 100644
--- a/doc/man1/openssl-cms.pod.in
+++ b/doc/man1/openssl-cms.pod.in
@@ -25,6 +25,7 @@ Operation options:
 [B<-resign>]
 [B<-sign_receipt>]
 [B<-verify_receipt> I<receipt>]
+[B<-digest> I<digest>]
 [B<-digest_create>]
 [B<-digest_verify>]
 [B<-compress>]
@@ -207,6 +208,16 @@ Verify a signed receipt in filename B<receipt>. The input message B<must>
 contain the original receipt request. Functionality is otherwise similar
 to the B<-verify> operation.
 
+=item B<-digest> I<digest>
+
+When used with B<-sign>, provides the digest in hexadecimal form instead of
+computing it from the original message content. Cannot be combined with B<-in>
+or B<-nodetach>.
+
+This operation is the CMS equivalent of L<openssl-pkeyutl(1)> signing.
+When signing a pre-computed digest, the security relies on the digest and its
+computation from the original message being trusted.
+
 =item B<-digest_create>
 
 Create a CMS B<DigestedData> type.
@@ -900,6 +911,8 @@ The B<-nameopt> option was added in OpenSSL 3.0.0.
 
 The B<-engine> option was deprecated in OpenSSL 3.0.
 
+The B<-digest> option was added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
 Copyright 2008-2021 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/CMS_final.pod b/doc/man3/CMS_final.pod
index 8270d53bc7..1ca1d8b092 100644
--- a/doc/man3/CMS_final.pod
+++ b/doc/man3/CMS_final.pod
@@ -2,13 +2,15 @@
 
 =head1 NAME
 
-CMS_final - finalise a CMS_ContentInfo structure
+CMS_final, CMS_final_digest - finalise a CMS_ContentInfo structure
 
 =head1 SYNOPSIS
 
  #include <openssl/cms.h>
 
  int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags);
+ int CMS_final_digest(CMS_ContentInfo *cms, const unsigned char *md,
+                      unsigned int mdlen, BIO *dcont, unsigned int flags);
 
 =head1 DESCRIPTION
 
@@ -19,24 +21,37 @@ processed. The B<dcont> parameter contains a BIO to write content to after
 processing: this is only used with detached data and will usually be set to
 NULL.
 
+CMS_final_digest() finalises the structure B<cms> using a pre-computed digest,
+rather than computing the digest from the original data.
+
 =head1 NOTES
 
-This function will normally be called when the B<CMS_PARTIAL> flag is used. It
+These functions will normally be called when the B<CMS_PARTIAL> flag is used. It
 should only be used when streaming is not performed because the streaming
 I/O functions perform finalisation operations internally.
 
+To sign a pre-computed digest, L<CMS_sign(3)> or CMS_sign_ex() is called
+with the B<data> parameter set to NULL before the CMS structure is finalised
+with the digest provided to CMS_final_digest() in binary form.
+When signing a pre-computed digest, the security relies on the digest and its
+computation from the original message being trusted.
+
 =head1 RETURN VALUES
 
-CMS_final() returns 1 for success or 0 for failure.
+CMS_final() and CMS_final_digest() return 1 for success or 0 for failure.
 
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>, L<CMS_sign(3)>,
 L<CMS_encrypt(3)>
 
+=head1 HISTORY
+
+CMS_final_digest() was added in OpenSSL 3.1.
+
 =head1 COPYRIGHT
 
-Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2008-2021 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