Fix RSA-PSS documentation.

-2 is really weird. On sign, it's maximal length. On verify, it actually
accepts all lengths. This sounds somewhat questionable to me, but just
document the state of the world for now. Also add a recommendation to
use -1 (match digest length) to align with TLS 1.3, tokbind, and QUIC
Crypto. Hopefully the first two is sufficient that the IETF will forever
use this option and stop the proliferation of RSA-PSS parameters.

Change-Id: Ie0ad7ad451089df0e18d6413d1b21c5aaad9d0f2
Reviewed-on: https://boringssl-review.googlesource.com/12823
Commit-Queue: David Benjamin <davidben@google.com>
Reviewed-by: Adam Langley <agl@google.com>

include/openssl/evp.h

@@ -577,7 +577,10 @@ OPENSSL_EXPORT int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx,
 /* EVP_PKEY_CTX_set_rsa_pss_saltlen sets the length of the salt in a PSS-padded
  * signature. A value of -1 cause the salt to be the same length as the digest
  * in the signature. A value of -2 causes the salt to be the maximum length
- * that will fit. Otherwise the value gives the size of the salt in bytes.
+ * that will fit when signing and recovered from the signature when verifying.
+ * Otherwise the value gives the size of the salt in bytes.
+ *
+ * If unsure, use -1.
  *
  * Returns one on success or zero on error. */
 OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx,

include/openssl/rsa.h

@@ -322,7 +322,9 @@ OPENSSL_EXPORT int RSA_recover_crt_params(RSA *rsa);
  * hash function for generating the mask. If NULL, |Hash| is used. The |sLen|
  * argument specifies the expected salt length in bytes. If |sLen| is -1 then
  * the salt length is the same as the hash length. If -2, then the salt length
- * is maximal and is taken from the size of |EM|.
+ * is recovered and all values accepted.
+ *
+ * If unsure, use -1.
  *
  * It returns one on success or zero on error. */
 OPENSSL_EXPORT int RSA_verify_PKCS1_PSS_mgf1(RSA *rsa, const uint8_t *mHash,