Deprecate idp_cert_fingerprint in code

CHANGELOG.md

@@ -8,6 +8,7 @@
 * [#692](https://github.com/SAML-Toolkits/ruby-saml/pull/692) Remove `XMLSecurity` namespace and replace with `RubySaml::XML`.
 * [#686](https://github.com/SAML-Toolkits/ruby-saml/pull/686) Use SHA-256 as the default hashing algorithm everywhere instead of SHA-1, including signatures, fingerprints, and digests.
 * [#695](https://github.com/SAML-Toolkits/ruby-saml/pull/695) Deprecate `settings.compress_request` and `settings.compess_response` parameters.
+* [#701](https://github.com/SAML-Toolkits/ruby-saml/pull/695) Deprecate `settings.idp_cert_fingerprint` and `settings.idp_cert_fingerprint_algorithm` parameters.
 * [#690](https://github.com/SAML-Toolkits/ruby-saml/pull/690) Remove deprecated `settings.security[:embed_sign]` parameter.
 * [#697](https://github.com/SAML-Toolkits/ruby-saml/pull/697) Add deprecation for various parameters in `RubySaml::Settings`.
 * [#709](https://github.com/SAML-Toolkits/ruby-saml/pull/709) Allow passing in `Net::HTTP` `:open_timeout`, `:read_timeout`, and `:max_retries` settings to `IdpMetadataParser#parse_remote`.

README.md

@@ -248,12 +248,13 @@ In addition, you may pass the option `:relax_signature_validation` to `SloLogout
 `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.
+removed in Ruby SAML version 2.1.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.)
+3. It has been removed already from several other SAML libraries in other languages.
 
 ## Handling Multiple IdP Certificates
 

UPGRADING.md

@@ -113,6 +113,13 @@ The SAML SP request/response message compression behavior is now controlled auto
 "compression" is used to make redirect URLs which contain SAML messages be shorter. For POST messages,
 compression may be achieved by enabling `Content-Encoding: gzip` on your webserver.
 
+### Deprecation of IdP certificate fingerprint settings
+
+The `settings.idp_cert_fingerprint` and `settings.idp_cert_fingerprint_algorithm` are deprecated
+and will be removed in RubySaml 2.1.0. Please use `settings.idp_cert` or `settings.idp_cert_multi` instead.
+The reasons for this deprecation are that (1) fingerprint cannot be used with HTTP-Redirect binding,
+and (2) fingerprint is theoretically susceptible to collision attacks.
+
 ### Other settings deprecations
 
 The following parameters in `RubySaml::Settings` are deprecated and will be removed in RubySaml 2.1.0:

lib/ruby_saml/settings.rb

@@ -36,8 +36,8 @@ def initialize(overrides = {}, keep_security_attributes = false)
     attr_accessor :idp_slo_service_url
     attr_accessor :idp_slo_response_service_url
     attr_accessor :idp_cert
-    attr_accessor :idp_cert_fingerprint
-    attr_accessor :idp_cert_fingerprint_algorithm
+    attr_reader   :idp_cert_fingerprint
+    attr_reader   :idp_cert_fingerprint_algorithm
     attr_accessor :idp_cert_multi
     attr_accessor :idp_attribute_names
     attr_accessor :idp_name_qualifier
@@ -305,6 +305,18 @@ def get_sp_digest_method
       end
     end
 
+    # @deprecated Will be removed in v2.1.0
+    def idp_cert_fingerprint=(value)
+      idp_cert_fingerprint_deprecation
+      @idp_cert_fingerprint = value
+    end
+
+    # @deprecated Will be removed in v2.1.0
+    def idp_cert_fingerprint_algorithm=(value)
+      idp_cert_fingerprint_deprecation
+      @idp_cert_fingerprint_algorithm = value
+    end
+
     # @deprecated Will be removed in v2.1.0
     def certificate_new
       certificate_new_deprecation
@@ -349,6 +361,13 @@ def replaced_deprecation(old_param, new_param)
                         "Please set the same value to `RubySaml::Settings##{new_param}` instead."
     end
 
+    # @deprecated Will be removed in v2.1.0
+    def idp_cert_fingerprint_deprecation
+      Logging.deprecate '`RubySaml::Settings#idp_cert_fingerprint` and `#idp_cert_fingerprint_algorithm` are ' \
+                        'deprecated and will be removed in RubySaml v2.1.0. Please provide the full IdP certificate in ' \
+                        '`RubySaml::Settings#idp_cert` instead.'
+    end
+
     # @deprecated Will be removed in v2.1.0
     def certificate_new_deprecation
       Logging.deprecate '`RubySaml::Settings#certificate_new` is deprecated and will be removed in RubySaml v2.1.0. ' \