Java XML Security Tool

xmlsectool is a Java command line tool that can download, check well-formedness, schema validity, and signature of an XML document. It can also create enveloped signatures of an XML document.

V2.0.0 End of Life Warning

As of December 31, 2020, all security maintenance for XMLSecTool V2.0.0 has ceased. V3.0.0 is the supported release.

All software, including archived releases, is available from http://shibboleth.net/downloads/tools/xmlsectool/. Each release is accompanied by a detached PGP signature using one of the keys listed in the project's PGP_KEYS file.

The Maven site for the project can be found here.

Obtaining and Using `xmlsectool`

Download the latest xmlsectool-#.#.#-bin.zip
Unzip archive (you can use jar -x file if your system does not happen to come with unzip).
Establish a JAVA_HOME environmental variable in the usual way.
Run the xmlsectool.sh command for available options.

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 the SignedInfo 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 in xmlsectool 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

Using `xmlsectool` With PKCS#11 Tokens

You can use xmlsectool to sign documents using keys stored in PKCS#11 tokens such as cryptographic smart cards in three different ways.

Using `--pkcs11Config` with `--keystoreProvider`

The most general way to access PKCS#11 tokens is to use the --pkcs11Config signing credential option to specify the location of a PKCS#11 configuration file, and use --keystoreProvider to specify the Java PKCS#11 provider class name.

Using --keystoreProvider in combination with --pkcs11Config is only available in XmlSecTool version 1.2.0 or later. A bug in earlier versions (see XSTJ-19) prevents you from using this option with older versions of XmlSecTool. Instead you must use one of the alternative signing methods shown in the subsections below.

If you use --keystoreProvider to load a provider dynamically, you must not also load that provider statically through the java.security configuration file as this will cause two copies of the provider to be loaded. This will result in hard to debug errors, such as "Private keys must be instance of RSAPrivate(Crt)Key or have PKCS#8 encoding" or "No installed provider supports this key".

Here is an example command line fragment:

...xmlsectool.sh --sign --pkcs11Config /path/to/config.cfg --keystoreProvider provider.class.name ...

For example, to use the Sun-supplied PKCS#11 bridge provider:

...xmlsectool.sh --sign --pkcs11Config /path/to/config.cfg --keystoreProvider sun.security.pkcs11.SunPKCS11 ...

The sun.security.pkcs11.SunPKCS11 provider is not available for use in this way in Java 9 or later. You will instead receive the following error:

ERROR CredentialHelper - Keystore provider class does not provide a String-argument constructor

The configuration file's contents might look like this:

library=/path/to/library.so
name=acs
description=ACOS5 token

Using `--pkcs11Config` without `--keystoreProvider`

Using --pkcs11Config with --keystoreProvider as described above loads the PKCS#11 provider dynamically. It is also possible to load the provider statically by modifying your JRE's lib/security/java.security file as described in section 2.2 of the Java PKCS#11 Reference Guide. This provides both the class name of the provider and the location of the PKCS#11 configuration file for that provider by adding a line to the end of the sequence of security.provider specifications. For example:

security.provider.1=sun.security.provider.Sun
...
security.provider.9=sun.security.mscapi.SunMSCAPI
security.provider.10=sun.security.pkcs11.SunPKCS11 /path/to/config.cfg

If you have loaded the PKCS#11 provider statically in this way, you can reference it from XmlSecTool by using the --pkcs11Config option with a dummy value, and omitting --keystoreProvider altogether:

...xmlsectool.sh --sign --pkcs11Config DUMMY ...

If you modify the java.security file to statically load a provider, you must not also use the –keystoreProvider option to load it dynamically as this will cause two copies of the provider to be loaded. This will result in hard to debug errors, such as "Private keys must be instance of RSAPrivate(Crt)Key or have PKCS#8 encoding" or "No installed provider supports this key".

Using `--keystore` instead of `--pkcs11Config`

You can also use the --keystore signing credential option to make use of PKCS#11 tokens. In this case, you must configure the PKCS#11 provider and configuration file statically in lib/security/java.security as described above, supply a --keystoreType option with value PKCS11, and supply the null device for your system as the value of --keystore:

...xmlsectool.sh --sign --keystore /dev/null --keystoreType PKCS11 ...

Tips

When signing a document to be sent via email or some other text-based mechanism, consider using the output option --base64EncodeOutput. This will Base64 encode the signed document, which will eliminate errors caused by unintentional XML reformatting (the most common cause of signature problems).
Be wary of XML attributes with default values defined in the document schema (such as the regexp XML attribute on the Shibboleth <Scope> extension element). If such an attribute is omitted from an otherwise schema-valid XML document, this may result in verification failures for verifiers that perform schema validation. To mitigate this issue, ensure that all such attributes have explicit values in the document to be signed.

Project details

Git Repository: https://git.shibboleth.net/git/xmlsectool

Issue Tracking: https://issues.shibboleth.net/jira/browse/XSTJ

Obtaining and Using xmlsectool