XML Digital Signatures

The XMLTooling layer has a generalized model for creating XML Signatures, which is refined in OpenSAML to hide most of the relevant details from the programmer. Generality is achieved with the ContentReference interface, which allows highly customized signature and KeyInfo content to be created as part of the signing process. The SAML profile for using XML Signature is implemented as a special case of this interface that is automatically managed for you.

Digitially signing is a two step process.

Attaching a Signature

The first step in signing is to create a Signature object and attach it to the XMLObject being signed. In SAML, this is always directly attached to the object being signed.

1. Create a Signature object using the SignatureBuilder (this is found in the XMLTooling library)
2. Attach the Signature to the XMLObject tree
3. Create a ContentReference object with the appropriate behavior and attach it with the Signature#setContentReference() method
4. Set the key that will be used to sign with the Signature#setSigningKey() method
5. Supply any relevant KeyInfo information with the Signature#setKeyInfo() method

Step 3 is done for you when signing SAML objects, inside the setSignature() method.

Creating the Signature Value

It's possible to use the Signature#sign() method directly, but because the signing process must take place after marshalling, the standard way to sign is to:

1. Create a vector and push in pointers to the Signature object(s) you want to sign, in the order you need them to be signed
2. Pass a pointer to the vector to the XMLObject#marshall() method

Verifying a Signature

At the lowest level, signature verification is handled with a SignatureValidator object. There are several ways to supply a verification key to the validator, including directly setting one or supplying a KeyResolver interface. This interface will be given access to the KeyInfo information inside the signature and could do a variety of complicated work to decide on a key to try.

If an exception is thrown by the SignatureValidator , the signature failed to validate and the exception will include the reason. If no exception is thrown, then the signature was valid.

Obviously, your application is wholly responsible for determining whether the resolved or supplied key is "correct" for your application.

For more advanced ways to evaluate signatures or certificates, including some SAML-specific approaches, you may want to look at the OSTwoUserManCPPTrust topic.