From: Matt Caswell <matt@openssl.org>
Date: Tue, 17 Apr 2018 14:33:17 +0000 (+0100)
Subject: Update EVP_DigestSignInit() docs
X-Git-Tag: OpenSSL_1_1_1-pre6~94
X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=be93b0e8638287bfaa8239ef64ee1c4a7cd818cb

Update EVP_DigestSignInit() docs

Explicitly state which digests can be used with which algorithms.

Fixes #5854

Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5992)
---

diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod
index 0c339fea38..fc19c015dd 100644
--- a/doc/man3/EVP_DigestSignInit.pod
+++ b/doc/man3/EVP_DigestSignInit.pod
@@ -26,7 +26,54 @@ EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
 ENGINE B<e> and private key B<pkey>. B<ctx> must be created with
 EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the
 EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
-be used to set alternative signing options.
+be used to set alternative signing options. The digest B<type> may be NULL if
+the signing algorithm supports it.
+
+Only EVP_PKEY types that support signing can be used with these functions. This
+includes MAC algorithms where the MAC generation is considered as a form of
+"signing." Built-in EVP_PKEY types supported by these functions are CMAC,
+Poly1305, DSA, HMAC, RSA, SipHash, Ed25519 and Ed448.
+
+Not all digests can be used for all key types. The following combinations apply.
+
+=over 4
+
+=item DSA
+
+Supports SHA1, SHA224, SHA256, SHA384 and SHA512
+
+=item ECDSA
+
+Supports SHA1, SHA224, SHA256, SHA384, SHA512 and SM3
+
+=item RSA with no padding
+
+Supports no digests (the digest B<type> must be NULL)
+
+=item RSA with X931 padding
+
+Supports SHA1, SHA256, SHA384 and SHA512
+
+=item All other RSA padding types
+
+Support SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2,
+SHA3-224, SHA3-256, SHA3-384, SHA3-512
+
+=item Ed25519 and Ed448
+
+Support no digests (the digest B<type> must be NULL)
+
+=item HMAC
+
+Supports any digest
+
+=item CMAC, Poly1305 and SipHash
+
+Will ignore any digest provided.
+
+=back
+
+If RSA-PSS is used and restrictions apply then the digest must match.
 
 EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
 signature context B<ctx>. This function can be called several times on the