From 350c92351705aa5916ffdf07fd7b81c1cbcb178b Mon Sep 17 00:00:00 2001
From: Matt Caswell <matt@openssl.org>
Date: Mon, 11 Nov 2019 16:33:24 +0000
Subject: [PATCH] Add documentation for the newly added
 RSA_PKCS1_WITH_TLS_PADDING

Documentation for RSA_PKCS1_WITH_TLS_PADDING padding mode as per the
previous commits, as well as the associated parameters for this mode.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10411)
---
 doc/man3/EVP_PKEY_CTX_ctrl.pod   | 23 ++++++++++++++++++++++-
 doc/man7/provider-asymcipher.pod | 17 +++++++++++++++++
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index 06151d4a5c..306b20b603 100644
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -258,7 +258,9 @@ The B<pad> parameter can take the value B<RSA_PKCS1_PADDING> for PKCS#1
 padding, B<RSA_SSLV23_PADDING> for SSLv23 padding, B<RSA_NO_PADDING> for
 no padding, B<RSA_PKCS1_OAEP_PADDING> for OAEP padding (encrypt and
 decrypt only), B<RSA_X931_PADDING> for X9.31 padding (signature operations
-only) and B<RSA_PKCS1_PSS_PADDING> (sign and verify only).
+only), B<RSA_PKCS1_PSS_PADDING> (sign and verify only) and
+B<RSA_PKCS1_WITH_TLS_PADDING> for TLS RSA ClientKeyExchange message padding
+(decryption only).
 
 Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md()
 is used. If this macro is called for PKCS#1 padding the plaintext buffer is
@@ -352,6 +354,25 @@ B<label>. The return value is the label length. The padding mode
 must have been set to B<RSA_PKCS1_OAEP_PADDING>. The resulting pointer is owned
 by the library and should not be freed by the caller.
 
+B<RSA_PKCS1_WITH_TLS_PADDING> is used when decrypting an RSA encrypted TLS
+pre-master secret in a TLS ClientKeyExchange message. It is the same as
+RSA_PKCS1_PADDING except that it additionally verifies that the result is the
+correct length and the first two bytes are the protocol version initially
+requested by the client. If the encrypted content is publicly invalid then the
+decryption will fail. However, if the padding checks fail then decryption will
+still appear to succeed but a random TLS premaster secret will be returned
+instead. This padding mode accepts two parameters which can be set using the
+L<EVP_PKEY_CTX_set_params(3)> function. These are
+OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION and
+OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION, both of which are expected to be
+unsigned integers. Normally only the first of these will be set and represents
+the TLS protocol version that was first requested by the client (e.g. 0x0303 for
+TLSv1.2, 0x0302 for TLSv1.1 etc). Historically some buggy clients would use the
+negotiated protocol version instead of the protocol version first requested. If
+this behaviour should be tolerated then
+OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION should be set to the actual
+negotiated protocol version. Otherwise it should be left unset.
+
 =head2 DSA parameters
 
 The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used
diff --git a/doc/man7/provider-asymcipher.pod b/doc/man7/provider-asymcipher.pod
index d0effa89b1..de615c463f 100644
--- a/doc/man7/provider-asymcipher.pod
+++ b/doc/man7/provider-asymcipher.pod
@@ -181,6 +181,13 @@ algorithms:
 
 =item "pad-mode" (B<OSSL_ASYM_CIPHER_PARAM_PAD_MODE>) <integer>
 
+The type of padding to be used. The interpretation of this value will depend
+on the algorithm in use. The default provider understands these RSA padding
+modes: 1 (RSA_PKCS1_PADDING), 2 (RSA_SSLV23_PADDING), 3 (RSA_NO_PADDING),
+4 (RSA_PKCS1_OAEP_PADDING), 5 (RSA_X931_PADDING), 6 (RSA_PKCS1_PSS_PADDING) and
+7 (RSA_PKCS1_WITH_TLS_PADDING). See L<EVP_PKEY_CTX_set_rsa_padding(3)> for
+further details.
+
 =item "digest" (B<OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST>) <UTF8 string>
 
 Gets or sets the name of the OAEP digest algorithm used when OAEP padding is in
@@ -207,6 +214,16 @@ Gets or sets the OAEP label used when OAEP padding is in use.
 
 Gets the length of an OAEP label when OAEP padding is in use.
 
+=item "tls-client-version" (B<OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION>) <unsigned integer>
+
+The TLS protocol version first requested by the client. See
+B<RSA_PKCS1_WITH_TLS_PADDING> on the page L<EVP_PKEY_CTX_set_rsa_padding(3)>.
+
+=item "tls-negotiated-version" (B<OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION>) <unsigned integer>
+
+The negotiated TLS protocol version. See
+B<RSA_PKCS1_WITH_TLS_PADDING> on the page L<EVP_PKEY_CTX_set_rsa_padding(3)>.
+
 =back
 
 OP_asym_cipher_gettable_ctx_params() and OP_asym_cipher_settable_ctx_params()
-- 
2.25.1