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 the
SignatureBuilder (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 the
- Set the key that will be used to sign with the
- Supply any relevant
KeyInfo information with the
Step 3 is done for you when signing SAML objects, inside the
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
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.