The OpenSAML V2 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.
OSTwoUserManCPPDSIG
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.
- Create a
Signature
object using theSignatureBuilder
(this is found in the XMLTooling library) - Attach the
Signature
to the XMLObject tree - Create a
ContentReference
object with the appropriate behavior and attach it with theSignature#setContentReference()
method - Set the key that will be used to sign with the
Signature#setSigningKey()
method - Supply any relevant
KeyInfo
information with theSignature#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:
- 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 - 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.