Child pages
  • CryptoShibHandle

The Shibboleth 1.x software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.

Skip to end of metadata
Go to start of metadata

This page didn't survive the conversion process and is no longer very usable.

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:

Unknown macro: {html}

<table>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<td align="left" colspan="4">

Unknown macro: {html}

<strong>

_Class

Unknown macro: {html}

<tt>

CryptoShibHandle

Unknown macro: {html}

</tt>

:_

Unknown macro: {html}

</strong>

Unknown macro: {html}

</td>

Unknown macro: {html}

</tr>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<th align="left">

Element Name

Unknown macro: {html}

</th>

Unknown macro: {html}

<th align="center">

Required

Unknown macro: {html}

</th>

Unknown macro: {html}

<th align="left">

Default

Unknown macro: {html}

</th>

Unknown macro: {html}

</tr>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

KeyStorePath

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="center">

Yes

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="left">

none

Unknown macro: {html}

</td>

Unknown macro: {html}

</tr>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

KeyStorePassword

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="center">

Yes

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="left">

none

Unknown macro: {html}

</td>

Unknown macro: {html}

</tr>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

KeyStoreKeyAlias

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="center">

Yes

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="left">

none

Unknown macro: {html}

</td>

Unknown macro: {html}

</tr>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

KeyStoreKeyPassword

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="center">

Yes

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="left">

none

Unknown macro: {html}

</td>

Unknown macro: {html}

</tr>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

KeyStoreType

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="center">

No

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

JCEKS

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

</tr>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

Cipher

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="center">

No

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

DESede/CBC/PKCS5Padding

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

</tr>

Unknown macro: {html}

<tr>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

MAC

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="center">

No

Unknown macro: {html}

</td>

Unknown macro: {html}

<td align="left">

Unknown macro: {html}

<tt>

HmacSHA1

Unknown macro: {html}

</tt>

Unknown macro: {html}

</td>

Unknown macro: {html}

</tr>

Unknown macro: {html}

</table>

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.

  • No labels