The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

Changing IdP Signature Method Algorithm

 

In a typical XML Signature, when a private key is used for signing, the data being signed is bulk-digested using a hashing algorithm recorded in the signature's <DigestMethod> element. In addition, the <SignedInfo> element is then signed using an asymmetric signing algorithm that involves a separate, independent digest step. This is reflected by the designation of the digest algorithm used within the overall signature algorithm identifier, for example "rsa-sha1" or "rsa-sha256". Thus there are two types of algorithms one must specify when signing, the bulk digest method, and the signing algorithm itself. Both involve a digest algorithm, and these algorithms can be independent of each other, though they are typically chosen in tandem.

The default digest method used by the IdP for XML Signatures in both contexts is SHA-1. These algorithms (and many other related algorithms and settings) can be changed by injecting an IdP extension Spring bean into the IdP configuration. This entails deploying an updated WAR file with the extension jar, and then making a small configuration change to load the new bean.

Changing the IdP signature/digest algorithm and related settings is currently a global operation. The algorithm will be changed for all relying parties it interacts with. Do not make this change until you have verified that all your relying parties can handle responses using the new algorithm(s) you choose.

Interoperability issues

Whether the Shibboleth SP can consume a message signed with an algorithm other than SHA-1 depends on the underlying OpenSSL library. On Red Hat Enterprise Linux version 4 (a very old, unsupported version) the OpenSSL version (0.9.7) is old enough that it cannot consume messages signed, for example, with any of the digest algorithms collectively known as SHA-2 (SHA-224, SHA-256, SHA-384 or SHA-512). SHA-2 support was introduced into OpenSSL with version 0.9.8 in July 2005, but this was too late for inclusion in RHEL 4.  RHEL 5.x and 6.x do include OpenSSL version 0.9.8 or later.

A particularly difficult platform to assess is Solaris, and a lot of commercial vendors use it. Many different versions of OpenSSL may be in use depending on how open source software is managed in a particular Solaris environment. Heavy testing is recommended.

The Shibboleth Native SP versions 2.4.3 and 2.5.x, if the underlying OpenSSL library is recent enough, do not require any configuration changes to consume messages or assertions signed with a digest method other than SHA-1.

No statement can be made at this time about other SAML service provider (SP) software, though in the case of commercial options, we believe that most recent versions released since 2010 or so are likely to support at least SHA-256. The only sensible approach is to thoroughly and completely test with each SP that might receive an assertion from the IdP.

Obtaining the software

Download the latest version of the extension from http://shibboleth.net/downloads/identity-provider/extensions/security-config/.

Detailed installation instructions may be found in the INSTALL.txt within the distribution archive.

Deploy new WAR file with new jar

To deploy the new jar file with the new bean:

  1. Copy the jar file from the target directory to the lib directory of your IdP source distribution.
  2. Redeploy:

    ./install.sh

Edit IdP configuration

To activate the new bean or extension for SHA-256, edit the IdP configuration file internal.xml by adding the following element:

Example switching to SHA-256
<bean id="shibboleth.idp.ext.OpensamlCustomSecurityConfig"
    class="edu.internet2.middleware.shibboleth.idp.ext.securityconfig.OpensamlCustomSecurityConfigBean"
    depends-on="shibboleth.OpensamlConfig">

    <!-- primary algorithms for use with RSA signing keys -->
    <property name="signatureAlgorithmRSA" value="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
    <property name="signatureReferenceDigestMethod" value="http://www.w3.org/2001/04/xmlenc#sha256"/>

    <!-- other signature algorithms for use with other signing keys -->
    <property name="signatureAlgorithmDSA" value="http://www.w3.org/2009/xmldsig11#dsa-sha256"/>
    <property name="signatureAlgorithmEC" value="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"/>
    <property name="signatureAlgorithmAES" value="http://www.w3.org/2001/04/xmldsig-more#hmac-sha256"/>
    <property name="signatureAlgorithmDESede" value="http://www.w3.org/2001/04/xmldsig-more#hmac-sha256"/>

 </bean>

See this important document for a complete list of algorithms and their uses: http://www.w3.org/TR/2013/NOTE-xmlsec-algorithms-20130411/

Restart and test

Restart the IdP and use a tool like the SAML tracer for Firefox to capture a response sent from the IdP to an SP. Note that depending on the configuration for the relying party, the SAML assertion may be encrypted and therefore the signature (if present) will not visible, so you will want to test using a relying party that is configured for signing only with no encryption, or alternatively sign the response with or without a signed assertion. You will see the following pair of elements in the SAML message, wherever an RSA key is used to sign:

<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
...
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>

In any case, you can always turn up IdP logging for more information.