Signing SAML Metadata
To sign SAML 2.0 metadata, you should first ensure that the document element (the outermost EntitiesDescriptor
or EntityDescriptor
element) has an appropriate ID
attribute. This must contain a valid XML ID value that is not being used as an ID elsewhere in the document. Note that XML ID values may not start with a digit.
One common pattern is to give the document element an ID
attribute containing a value based on the date and time of signing:
<EntitiesDescriptor Name="http://fed.example.org" ID="myfed20130320082100" xmlns="...">
Signing the metadata document will involve the following options, as well as options specifying the signing credential:
...xmlsectool.sh --sign --inFile in.xml --outFile out.xml --referenceIdAttributeName ID ...
Signing Using Specific Digest and Signature Algorithms
The XML Digital Signature standard operates as a two-part process:
- The document to be signed is processed to generate a
SignedInfo
element. This processing involves using a cryptographic hash function to reduce the final result to a shorter message digest. We will refer to the selected hash function as the digest algorithm. - The
SignedInfo
element is digitally signed using a signature algorithm appropriate for the type of credential used. For example, in the case of an RSA credential the signature algorithm used combines the RSA private key operation with a second cryptographic hash function used to produce a second message digest of theSignedInfo
element.
By default, XmlSecTool selects the following digest and signature algorithms for each of the credential types:
Credential | Digest | Signature |
---|---|---|
RSA | SHA-256 | RSA + SHA-256 |
EC | SHA-256 | ECDSA + SHA-256 |
DSA | SHA-256 | DSA + SHA-1 |
To select a different hash function, XmlSecTool provides the --digest
option, which takes the name of a hash function as parameter. For example:
...xmlsectool.sh --sign --digest SHA-512 ...
Allowable values for the --digest
option are SHA-1
(not recommended), SHA-256
(the default), SHA-384
and SHA-512
. You may use the hash function's name with or without the hyphen in each case, so that SHA512
is a synonym for SHA-512
.
Selecting a value for the --digest
option changes both the digest algorithm and, for RSA and Elliptic Curve credentials, the appropriate component of the signature algorithm. For example, selecting –digest SHA-512
would result in the following algorithms being selected for each credential type:
Credential | Digest | Signature |
---|---|---|
RSA | SHA-512 | RSA + SHA-512 |
EC | SHA-512 | ECDSA + SHA-512 |
DSA | SHA-512 | DSA + SHA-1 |
In some situations, this simplified selection process does not allow you to use the digest and signature algorithms you need for a particular application. For example, hash functions such as MD5 are not included because they are regarded as being too weak for regular use. In these cases, you can override the digest algorithm and signature algorithms selected based on the --digest
option using the --digestAlgorithm
and --signatureAlgorithm
options. These each take as parameter the full URI identifier of the algorithm to use, so that any algorithm supported by the Apache Santuario cryptographic library in use can be specified. You can mix these fine-grained options with --digest
, as in the following example:
...xmlsectool.sh --sign --digest SHA-512 --signatureAlgorithm http://www.w3.org/2001/04/xmldsig-more#rsa-md5 ...
You should use the --digestAlgorithm
and --signatureAlgorithm
options, either together or individually, only if you understand the full implications of using non-standard algorithm combinations.
Signature Verification Algorithm Blacklist
As the state of the art in cryptanalysis progresses, algorithms that were once acceptable for use in digital signatures become first deprecated and then disallowed. For example, the SHA-1 cryptographic hash function is now regarded as weak. NIST deprecated the use of SHA-1 in digital signatures from 2011, and disallows its use entirely from 2014. In order to guard against attacks on algorithms once regarded as strong but since determined to be weak, xmlsectool
provides a signature verification algorithm blacklist mechanism; a signature being verified will be rejected if it makes use of an algorithm on the blacklist.
xmlsectool
ships with a built-in default blacklist. In version 2.0.0, this blacklist contains only algorithms related to the MD5 and SHA-1 message digest functions. This may be extended in future releases to include additional algorithms when appropriate.
If the default blacklist is not suitable, whether because it includes an algorithm you need xmlsectool
to accept or because it does not include algorithms you regard as too weak, you can manipulate it using the following command-line options:
--clearBlacklist
removes the default blacklist. Do this only if you are sure that you need to use one of the algorithms in the default blacklist, and therefore need complete control over the blacklist contents.--blacklistDigest
adds algorithms related to the given digest function to the blacklist. For example,--blacklistDigest SHA256
would add algorithms related to the SHA-256 digest function to the blacklist. This option may appear any number of times.--whitelistDigest
(added inxmlsectool
V2.0.0) removes algorithms related to the given digest function to the blacklist. For example,--whitelistDigest SHA1
would remove algorithms related to the SHA-1 digest function from the blacklist. This option may appear any number of times.--listBlacklist
is an action option you can use to display the resulting contents of the blacklist. See the examples below.
These options can appear on the command line in any order, but will always be processed in the order given above. Note also that these options only change the behaviour of xmlsectool
for a single invocation; you must include them in the command line every time you want to override the default blacklist.
Example: viewing the default blacklist.
$ ./xmlsectool.sh --listBlacklist Digest algorithm blacklist: http://www.w3.org/2000/09/xmldsig#sha1 http://www.w3.org/2001/04/xmldsig-more#md5 Signature algorithm blacklist: http://www.w3.org/2000/09/xmldsig#rsa-sha1 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1 http://www.w3.org/2001/04/xmldsig-more#rsa-md5
Example: extending the default blacklist.
$ ./xmlsectool.sh --blacklistDigest SHA256 --listBlacklist Digest algorithm blacklist: http://www.w3.org/2000/09/xmldsig#sha1 http://www.w3.org/2001/04/xmldsig-more#md5 http://www.w3.org/2001/04/xmlenc#sha256 Signature algorithm blacklist: http://www.w3.org/2000/09/xmldsig#rsa-sha1 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256 http://www.w3.org/2001/04/xmldsig-more#rsa-md5 http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
Example: removing algorithms from the default blacklist.
$ ./xmlsectool.sh --whitelistDigest SHA1 --listBlacklist Digest algorithm blacklist: http://www.w3.org/2001/04/xmldsig-more#md5 Signature algorithm blacklist: http://www.w3.org/2001/04/xmldsig-more#rsa-md5
Example: full control (NOT RECOMMENDED).
$ ./xmlsectool.sh --clearBlacklist --blacklistDigest SHA1 --listBlacklist Digest algorithm blacklist: http://www.w3.org/2000/09/xmldsig#sha1 Signature algorithm blacklist: http://www.w3.org/2000/09/xmldsig#rsa-sha1 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1