Deprecate idp_cert_fingerprint and idp_cert_fingerprint_algorithm

Author: johnnyshields

README.md

@@ -239,20 +239,21 @@ end
 
 ## Signature Validation
 
-Ruby SAML allows different ways to validate the signature of the SAMLResponse:
-- You can provide the IdP X.509 public certificate at the `idp_cert` setting.
-- You can provide the IdP X.509 public certificate in fingerprint format using the
- `idp_cert_fingerprint` setting parameter and additionally the `idp_cert_fingerprint_algorithm` parameter.
-
-When validating the signature of redirect binding, the fingerprint is useless and the certificate
-of the IdP is required in order to execute the validation. You can pass the option
-`:relax_signature_validation` to `SloLogoutrequest` and `Logoutresponse` if want to avoid signature
-validation if no certificate of the IdP is provided.
-
-In production also we highly recommend to register on the settings the IdP certificate instead
-of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision
-attack that can end on a signature validation bypass. Other SAML toolkits deprecated that mechanism,
-we maintain it for compatibility and also to be used on test environment.
+Ruby SAML allows different ways to validate the signature of the SAML Response:
+- You may provide the IdP X.509 public certificate at the `idp_cert` setting.
+- (Deprecated) You may provide the IdP X.509 public certificate in fingerprint format using the
+  `idp_cert_fingerprint` and `idp_cert_fingerprint_algorithm` parameters.
+
+In addition, you may pass the option `:relax_signature_validation` to `SloLogoutrequest` and
+`Logoutresponse` if want to skip signature validation on logout.
+
+The `idp_cert_fingerprint` option is deprecated for the following reasons. It will be
+removed in Ruby SAML version 3.0.
+1. It only works with HTTP-POST binding, not HTTP-Redirect, since the full certificate
+   is not sent in the Redirect URL parameters.
+2. It is theoretically be susceptible to collision attacks, by which a malicious
+   actor could impersonate the IdP. (However, as of January 2025, such attacks have not
+   been publicly demonstrated for SHA-256.)
 
 ## Handling Multiple IdP Certificates
 

UPGRADING.md

@@ -97,7 +97,7 @@ request.uuid #=> "my_id_a1b3c5d7-9f1e-3d5c-7b1a-9f1e3d5c7b1a"
 ```
 
 A side-effect of this change is that the `uuid` of the `Authrequest`, `Logoutrequest`, and `Logoutresponse`
-classes now is `nil` until the `#create` method is called (previously, it was set in the constructor.)
+classes now is `nil` until the `#create` method is called (previously, it was set in the initializer.)
 After calling `#create` for the first time the `uuid` will not change, even if a `Settings` object with
 a different `sp_uuid_prefix` is passed-in on subsequent calls.
 
@@ -215,7 +215,7 @@ the [CVE-2017-11428](https://www.cvedetails.com/cve/CVE-2017-11428/) vulnerabili
 
 Version `1.6.0` changes the preferred way to construct instances of `Logoutresponse` and
 `SloLogoutrequest`. Previously the _SAMLResponse_, _RelayState_, and _SigAlg_ parameters
-of these message types were provided via the constructor's `options[:get_params]` parameter.
+of these message types were provided via the initializer's `options[:get_params]` parameter.
 Unfortunately this can result in incompatibility with other SAML implementations; signatures
 are specified to be computed based on the _sender's_ URI-encoding of the message, which can
 differ from that of Ruby SAML. In particular, Ruby SAML's URI-encoding does not match that