CryptoShibHandle

An alternative implementation of a Shibboleth handle is called CryptoShibHandle. Like SharedMemoryShibHandle, a CryptoShibHandle is an opaque reference to a SAML subject. Unlike SharedMemoryShibHandle, however, a CryptoShibHandle introduces no state at the IdentityProvider. Consequently, CryptoShibHandle is well suited for load balanced environments.

A CryptoShibHandle avoids state at the IdentityProvider by encrypting the local principal name and its associated time-to-live (TTL) into the handle itself. Configuration is more involved, however, since the key used to encrypt/decrypt the handle must be created, packaged, and secured.

To enable CryptoShibHandle, perform the following steps:

1. Create a Java keystore. If you're using the default Java cryptography engine you can do this with the keytool command as follows:
   > keytool -genkey -keyalg RSA -keystore cryptohandle.jks -storepass KeyStorePassword -keypasswd KeyStoreKeyPassword -alias KeyStoreKeyAlias
2. Place the cryptohandle.jks file in the etc/ directory of your Shibboleth !IdP home directory.
3. Insert a NameMapping element into the !IdP config file (see below).
4. In the !IdP config file, set one or more /IdPConfig/RelyingParty/NameID/@nameMapping attributes equal to the value of /IdPConfig/NameMapping/@id (see below).
5. Restart the !IdP (probably means restarting Tomcat+Apache)

To configure an !IdP to use CryptoShibHandle, a NameMapping element similar to the following is inserted into the !IdP config file (idp.xml):

<!-- CryptoShibHandle configuration -->
<NameMapping
  xmlns="urn:mace:shibboleth:namemapper:1.0"
  id="..."
  format="urn:mace:shibboleth:1.0:nameIdentifier"
  handleTTL="1800"
  type="CryptoHandleGenerator">
  <!-- the absolute path to a Java keystore -->
  <KeyStorePath>...</KeyStorePath>
  <!-- the keystore password -->
  <KeyStorePassword>...</KeyStorePassword>
  <!-- the alias of the private key in the keystore -->
  <KeyStoreKeyAlias>...</KeyStoreKeyAlias>
  <!-- the password of the private key in the keystore -->
  <KeyStoreKeyPassword>...</KeyStoreKeyPassword>
  <!-- the keystore type (default: JCEKS) -->
  <KeyStoreType>JCEKS</KeyStoreType>
  <!-- the crypto cipher (default: DESede/CBC/PKCS5Padding) -->
  <Cipher>DESede/CBC/PKCS5Padding</Cipher>
  <!-- the MAC (default: HmacSHA1) -->
  <MAC>HmacSHA1</MAC>
</NameMapping>

where the attributes of the NameMapping element are the same as SharedMemoryShibHandle (except for the value of the type attribute). The nested elements are summarized in the following table:

Class CryptoShibHandle:


Element Name
Required
Default


KeyStorePath
Yes
none


KeyStorePassword
Yes
none


KeyStoreKeyAlias
Yes
none


KeyStoreKeyPassword
Yes
none


KeyStoreType
No
JCEKS


Cipher
No
DESede/CBC/PKCS5Padding


MAC
No
HmacSHA1

Note: If you are using a standard Java keystore, the KeyStoreType element may be omitted. Otherwise, set the KeyStoreType element to the appropriate type identifier. Also, unless you know what you're doing, use the default values of Cipher and MAC by omitting the child elements from the NameMapping element.

See the Shibboleth Identity Provider Deployment Guide for more detail regarding CryptoShibHandle configuration. See http://java.sun.com/j2se/1.5.0/docs/guide/security/CryptoSpec.html for general information about cryptographic implementations, conventions and syntax.