diff options
author | Matt Caswell <matt@openssl.org> | 2019-11-11 16:33:24 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2019-12-05 16:12:18 +0000 |
commit | 350c92351705aa5916ffdf07fd7b81c1cbcb178b (patch) | |
tree | 8241745f87dac522a42520378de7ab641c91c974 /doc | |
parent | e7db9680db57e180c525bc57c3858d8dd5637940 (diff) |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EVP_PKEY_CTX_ctrl.pod | 23 | ||||
-rw-r--r-- | doc/man7/provider-asymcipher.pod | 17 |
2 files changed, 39 insertions, 1 deletions
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() |