Deprecate the certFingerprint option.

Issue a notice when the option is used nonetheless.

Closes: #432

docs/simplesamlphp-reference-idp-remote.md

@@ -31,9 +31,7 @@ The following options are common between both the SAML 2.0 protocol and Shibbole
 :   The base64 encoded certificate for this IdP. This is an alternative to storing the certificate in a file on disk and specifying the filename in the `certificate`-option.
 
 `certFingerprint`
-:   If you only need to validate signatures received from this IdP, you can specify the certificate fingerprint instead of storing the full certificate. To obtain this, you can enter a bogus value, and attempt to log in. You will then receive an error message with the correct fingerprint.
-
-:   It is also possible to add an array of valid fingerprints, where any fingerprints in that array is accepted as valid. This can be used to update the certificate of the IdP without having to update every SP at that exact time. Instead, one can update the SPs with the new fingerprint, and only update the certificate after every SP is updated.
+:   If you only need to validate signatures received from this IdP, you can specify the certificate fingerprint instead of storing the full certificate. *Deprecated:* please use `certData` or `certificate` options. This option will be removed in a future version of simpleSAMLphp.
 
 `certificate`
 :   The file with the certificate for this IdP. The path is relative to the `cert`-directory.
@@ -211,13 +209,3 @@ Shibboleth 1.3 options
 
 :   *Note*: This option only works with the `saml:SP` authentication source.
 
-
-Calculating the fingerprint of a certificate
---------------------------------------------
-
-If you have obtained a certificate file, and want to calculate the fingerprint of the file, you can use the `openssl` command:
-
-    $ openssl x509 -noout -fingerprint -in "example.org.crt"
-    SHA1 Fingerprint=AF:E7:1C:28:EF:74:0B:C8:74:25:BE:13:A2:26:3D:37:97:1D:A1:F9
-
-In this case, the certFingerprint option should be set to `AF:E7:1C:28:EF:74:0B:C8:74:25:BE:13:A2:26:3D:37:97:1D:A1:F9`.

docs/simplesamlphp-sp.md

@@ -72,9 +72,11 @@ This is a minimal example of a `metadata/saml20-idp-remote.php` metadata file:
     $metadata['https://example.com'] = array(
         'SingleSignOnService'  => 'https://example.com/simplesaml/saml2/idp/SSOService.php',
         'SingleLogoutService'  => 'https://example.com/simplesaml/saml2/idp/SingleLogoutService.php',
-        'certFingerprint'      => 'c9ed4dfb07caf13fc21e0fec1572047eb8a7a4cb',
+        'certificate'          => 'example.pem',
     );
 
+`example.pem` under your `cert/` directory contains the certificate the identity provider uses for signing assertions.
+
 For more information about available options in the idp-remote metadata files, see the [IdP remote reference](simplesamlphp-reference-idp-remote).
 
 If you have the metadata of the remote IdP as an XML file, you can use the built-in XML to SimpleSAMLphp metadata converter, which by default is available as `/admin/metadata-converter.php` in your SimpleSAMLphp installation.

lib/SimpleSAML/Metadata/SAMLParser.php

@@ -604,7 +604,7 @@ public function getMetadata1xSP()
      * - 'SingleSignOnService': String with the URL of the SSO service which supports the redirect binding.
      * - 'SingleLogoutService': String with the URL where we should send logout requests/responses.
      * - 'certData': X509Certificate for entity (if present).
-     * - 'certFingerprint': Fingerprint of the X509Certificate from the metadata.
+     * - 'certFingerprint': Fingerprint of the X509Certificate from the metadata. (deprecated)
      *
      * Metadata must be loaded with one of the parse functions before this function can be called.
      *
@@ -757,7 +757,7 @@ public function getMetadata20SP()
      *   the 'SingleLogoutService' endpoint.
      * - 'NameIDFormats': The name ID formats this IdP supports.
      * - 'certData': X509Certificate for entity (if present).
-     * - 'certFingerprint': Fingerprint of the X509Certificate from the metadata.
+     * - 'certFingerprint': Fingerprint of the X509Certificate from the metadata. (deprecated)
      *
      * Metadata must be loaded with one of the parse functions before this function can be called.
      *

lib/SimpleSAML/Utils/Crypto.php

@@ -178,12 +178,12 @@ public static function loadPrivateKey(\SimpleSAML_Configuration $metadata, $requ
      * - 'certData': The certificate as a base64-encoded string.
      * - 'certificate': A file with a certificate or public key in PEM-format.
      * - 'certFingerprint': The fingerprint of the certificate. Can be a single fingerprint, or an array of multiple
-     * valid fingerprints.
+     * valid fingerprints. (deprecated)
      *
      * This function will return an array with these elements:
      * - 'PEM': The public key/certificate in PEM-encoding.
      * - 'certData': The certificate data, base64 encoded, on a single line. (Only present if this is a certificate.)
-     * - 'certFingerprint': Array of valid certificate fingerprints. (Only present if this is a certificate.)
+     * - 'certFingerprint': Array of valid certificate fingerprints. (Deprecated. Only present if this is a certificate.)
      *
      * @param \SimpleSAML_Configuration $metadata The metadata.
      * @param bool                      $required Whether the private key is required. If this is TRUE, a missing key

metadata-templates/shib13-idp-remote.php

@@ -10,6 +10,6 @@
 /*
 $metadata['theproviderid-of-the-idp'] = array(
 	'SingleSignOnService'  => 'https://idp.example.org/shibboleth-idp/SSO',
-	'certFingerprint'      => 'c7279a9f28f11380509e072441e3dc55fb9ab864',
+	'certificate'          => 'example.pem',
 );
 */

modules/saml/lib/Message.php

@@ -159,6 +159,11 @@ public static function checkSign(SimpleSAML_Configuration $srcMetadata, \SAML2\S
 			}
 
 		} elseif ($srcMetadata->hasValue('certFingerprint')) {
+			SimpleSAML\Logger::notice(
+			    "Validating certificates by fingerprint is deprecated. Please use " .
+			    "certData or certificate options in your remote metadata configuration."
+			);
+
 			$certFingerprint = $srcMetadata->getArrayizeString('certFingerprint');
 			foreach ($certFingerprint as &$fp) {
 				$fp = strtolower(str_replace(':', '', $fp));