From 22579cec9c6c42696fc6daa92caf386caf1227e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jaime=20P=C3=A9rez=20Crespo?= <jaime.perez@uninett.no>
Date: Tue, 19 Nov 2013 16:06:54 +0000
Subject: [PATCH] Properly document the signature.algorithm option. Also add
configuration examples showing how to start using SHA-256, and warning about
SHA-1 being disallowed starting in 2014.
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@3297 44740490-163a-0410-bde0-09ae8108e29a
---
config-templates/authsources.php | 20 ++++++++++++++++++++
docs/simplesamlphp-reference-idp-hosted.txt | 10 ++++++++++
docs/simplesamlphp-reference-idp-remote.txt | 12 ++++++++++++
docs/simplesamlphp-reference-sp-remote.txt | 12 ++++++++++++
metadata-templates/saml20-idp-hosted.php | 20 ++++++++++++++++++++
modules/saml/docs/sp.txt | 10 ++++++++++
modules/saml/lib/Message.php | 10 ++++++++++
7 files changed, 94 insertions(+)
diff --git a/config-templates/authsources.php b/config-templates/authsources.php
index 2eedc80fc..95376b17b 100644
--- a/config-templates/authsources.php
+++ b/config-templates/authsources.php
@@ -27,6 +27,26 @@ $config = array(
// The URL to the discovery service.
// Can be NULL/unset, in which case a builtin discovery service will be used.
'discoURL' => NULL,
+
+ /*
+ * WARNING: SHA-1 is disallowed starting January the 1st, 2014.
+ *
+ * Uncomment the following option to start using SHA-256 for your signatures.
+ * Currently, simpleSAMLphp defaults to SHA-1, which has been deprecated since
+ * 2011, and will be disallowed by NIST as of 2014. Please refer to the following
+ * document for more information:
+ *
+ * http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf
+ *
+ * If you are uncertain about identity providers supporting SHA-256 or other
+ * algorithms of the SHA-2 family, you can configure it individually in the
+ * IdP-remote metadata set for those that support it. Once you are certain that
+ * all your configured IdPs support SHA-2, you can safely remove the configuration
+ * options in the IdP-remote metadata set and uncomment the following option.
+ *
+ * Please refer to the hosted SP configuration reference for more information.
+ */
+ //'signature.algorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
),
diff --git a/docs/simplesamlphp-reference-idp-hosted.txt b/docs/simplesamlphp-reference-idp-hosted.txt
index 3fa8b5f40..ae5a9b3bb 100644
--- a/docs/simplesamlphp-reference-idp-hosted.txt
+++ b/docs/simplesamlphp-reference-idp-hosted.txt
@@ -258,6 +258,16 @@ The following SAML 2.0 options are available:
specified will be kept in the metadata, making the first binding
the default one.
+`signature.algorithm`
+: The algorithm to use when signing any message generated by this identity provider. Defaults to RSA-SHA1.
+: Possible values:
+
+ * `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
+ *Note*: the use of SHA1 is **deprecated** and will be disallowed in the future.
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
+
`validate.authnrequest`
: Whether we require signatures on authentication requests sent to this IdP.
diff --git a/docs/simplesamlphp-reference-idp-remote.txt b/docs/simplesamlphp-reference-idp-remote.txt
index e8af4109a..2bc9242e3 100644
--- a/docs/simplesamlphp-reference-idp-remote.txt
+++ b/docs/simplesamlphp-reference-idp-remote.txt
@@ -142,6 +142,18 @@ The following SAML 2.0 options are available:
`SingleLogoutServiceResponse`
: Endpoint URL for logout responses. Overrides the `SingleLogoutService`-option for responses.
+`signature.algorithm`
+: The algorithm to use when signing any message sent to this specific identity provider. Defaults to RSA-SHA1.
+: Note that this option also exists in the SP configuration.
+ This value in the IdP remote metadata overrides the value in the SP configuration.
+: Possible values:
+
+ * `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
+ *Note*: the use of SHA1 is **deprecated** and will be disallowed in the future.
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
+
`SPNameQualifier`
: This corresponds to the SPNameQualifier in the SAML 2.0 specification. It allows to give subjects a SP specific namespace. This option is rarely used, so if you don't need it, leave it out. When left out, simpleSAMLphp assumes the entityID of your SP as the SPNameQualifier.
diff --git a/docs/simplesamlphp-reference-sp-remote.txt b/docs/simplesamlphp-reference-sp-remote.txt
index 9fbdcef60..4d891bb18 100644
--- a/docs/simplesamlphp-reference-sp-remote.txt
+++ b/docs/simplesamlphp-reference-sp-remote.txt
@@ -231,6 +231,18 @@ The following SAML 2.0 options are available:
: Note that this option also exists in the IdP-hosted metadata.
The value in the SP-remote metadata overrides the value in the IdP-hosted metadata.
+`signature.algorithm`
+: The algorithm to use when signing any message sent to this specific service provider. Defaults to RSA-SHA1.
+: Note that this option also exists in the IdP-hosted metadata.
+ The value in the SP-remote metadata overrides the value in the IdP-hosted metadata.
+: Possible values:
+
+ * `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
+ *Note*: the use of SHA1 is **deprecated** and will be disallowed in the future.
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
+
`simplesaml.nameidattribute`
: When the value of the `NameIDFormat`-option is set to either
`email` or `persistent`, this is the name of the attribute which
diff --git a/metadata-templates/saml20-idp-hosted.php b/metadata-templates/saml20-idp-hosted.php
index d470e9805..56b1c66e4 100644
--- a/metadata-templates/saml20-idp-hosted.php
+++ b/metadata-templates/saml20-idp-hosted.php
@@ -23,6 +23,26 @@ $metadata['__DYNAMIC:1__'] = array(
*/
'auth' => 'example-userpass',
+ /*
+ * WARNING: SHA-1 is disallowed starting January the 1st, 2014.
+ *
+ * Uncomment the following option to start using SHA-256 for your signatures.
+ * Currently, simpleSAMLphp defaults to SHA-1, which has been deprecated since
+ * 2011, and will be disallowed by NIST as of 2014. Please refer to the following
+ * document for more information:
+ *
+ * http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf
+ *
+ * If you are uncertain about service providers supporting SHA-256 or other
+ * algorithms of the SHA-2 family, you can configure it individually in the
+ * SP-remote metadata set for those that support it. Once you are certain that
+ * all your configured SPs support SHA-2, you can safely remove the configuration
+ * options in the SP-remote metadata set and uncomment the following option.
+ *
+ * Please refer to the IdP hosted reference for more information.
+ */
+ //'signature.algorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
+
/* Uncomment the following to use the uri NameFormat on attributes. */
/*
'attributes.NameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
diff --git a/modules/saml/docs/sp.txt b/modules/saml/docs/sp.txt
index e77b32d4c..4cc32330d 100644
--- a/modules/saml/docs/sp.txt
+++ b/modules/saml/docs/sp.txt
@@ -388,6 +388,16 @@ Options
: *Note*: SAML 2 specific.
+`signature.algorithm`
+: The algorithm to use when signing any message generated by this service provider. Defaults to RSA-SHA1.
+: Possible values:
+
+ * `http://www.w3.org/2000/09/xmldsig#rsa-sha1`
+ *Note*: the use of SHA1 is **deprecated** and will be disallowed in the future.
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha384`
+ * `http://www.w3.org/2001/04/xmldsig-more#rsa-sha512`
+
`SingleLogoutServiceBinding`
: List of SingleLogoutService bindings the IdP will claim support for.
: Possible values:
diff --git a/modules/saml/lib/Message.php b/modules/saml/lib/Message.php
index 4ffcfcacc..30cce2491 100644
--- a/modules/saml/lib/Message.php
+++ b/modules/saml/lib/Message.php
@@ -24,6 +24,16 @@ class sspmod_saml_Message {
$algo = $dstMetadata->getString('signature.algorithm', NULL);
if ($algo === NULL) {
+ /*
+ * In the NIST Special Publication 800-131A, SHA-1 became deprecated for generating
+ * new digital signatures in 2011, and will be explicitly disallowed starting the 1st
+ * of January, 2014. We'll keep this as a default for the next release and mark it
+ * as deprecated, as part of the transition to SHA-256.
+ *
+ * See http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf for more info.
+ *
+ * TODO: change default to XMLSecurityKey::RSA_SHA256.
+ */
$algo = $srcMetadata->getString('signature.algorithm', XMLSecurityKey::RSA_SHA1);
}
--
GitLab