x

The verification of a digital signature involves the following steps:

1. The Signature element is retrieved and its syntax is checked.
2. For each Reference, its transforms are evaluated and the output digested into a hash. The hash is compared against that Reference DigestValue in the signature.
3. The signer certificate is retrieved and the certificate chain is validated.
4. The signature is recomputed over the SignedInfo and compared against the SignatureValue in the document.

These steps can be performed by the XDXMLDSigVerifyAgent with very little configuration because the signature contains the necessary information. This makes the service more adaptable to different signature formats it may receive. By default, the service searches the whole document for an element named Signature in the namespace http://www.w3.org/2000/09/xmldsig#.

The Reference URI instructs the service where to find the referenced data. The signature declares the algorithms used for hashing and signing. The KeyInfo element provides the hints to find the signer certificate. The only necessary configuration is the TrustStore used to validate the certificate chain. The TrustStore parameter gives the name of the KeyStore provider that declares a KeyStore file containing the certificates of the Trusted CAs. It is highly recommended to use this KeyStore exclusively as a TrustStore. It should not contain private keys or any other unrelated certificates. The JRE includes a sample TrustStore, which is located in the following directory:

<java-home>/lib/security/cacerts

This file is convenient to retrieve the certificates of some well known CAs. It is not recommended to use the JRE sample TrustStore directly. It is better to restrict the contents of the TrustStore to the small list of Trusted CAs the application is willing to trust.

In this example, the flexibility of the service is demonstrated by validating various signatures showing multiple ways the certificate chain can be completed.

The following table lists the parameter values for the XDXMLDSigVerifyAgent. Other parameters that are not listed have their default value.

Parameter	Value
TrustStore Provider	trustprov

This assumes trustprov is the name of a KeyStore provider that contains the certificates of the Trusted CAs.

The simplest case is when the Signature contains the complete certificate chain, though this produces documents that are slightly bulkier. The certificates appear in X509Certificate elements under the KeyInfo in no particular order. The verify service needs an extra hint to determine which one is the signer certificate. For example, the SubjectName can also be added to the KeyInfo.

The XDXMLDSigCreateAgent can create this signature by setting the Include Certificate Chain parameter to Complete Certificate Chain and setting the Include Subject Name parameter to true.

In this sample signature, the certificate chain contains two certificates: the signer certificate and the issuer CA. The TrustStore must contain the certificate of the issuer CA to validate the chain.

A sample input document is shown as follows (indented for display purposes only):

Since the issuer CA is already in the TrustStore, many applications choose to omit the CA certificate in the signature KeyInfo. The service is able to complete the certificate chain because it adds the TrustStore to the list of CertStores to search for certificates. The service still needs an extra hint to recognize that the certificate in the signature is the signer certificate. This example includes the certificate IssuerName/SerialNumber in the KeyInfo. In general, the IssuerName/SerialNumber is better than the Subject DN because it uniquely identifies the certificate (even if it is renewed later).

The XDXMLDSigCreateAgent can create this signature by setting the Include Certificate Chain parameter to Signer Certificate Only, the Include Issuer Serial parameter to true, and the Include Subject Name parameter to false.

A sample input document is shown as follows (indented for display purposes only):

Some web service security standards advocate that the certificate should be passed in a BinarySecurityToken within the SOAP Headers. The KeyInfo element should contain a SecurityTokenReference pointing to the BinarySecurityToken. The service is able to follow the URI in the SecurityTokenReference to retrieve the certificate in the BinarySecurityToken. It is recommended to include the BinarySecurityToken within the signed data by declaring a signature Reference that covers that element.

For more information on how to create this signature, see Example 3: WSSE SecurityTokenReference.

A sample input document is shown as follows (indented for display purposes only):

x

If the originator is sending many signed documents to the application, it might be more efficient to send the certificate chain out of band and let the application retrieve it locally. The signer certificate must be added to one of the CertStores accessible to the service. Intermediate CAs must also be added to the CertStores if the chain has a depth of 3 or more. The Trusted CA must be in the TrustStore as always. The service uses the hints in the KeyInfo to query its CertStores to find the signer certificate. The service completes the chain by querying for the parent certificates.

The Certificate Store Providers parameter accepts a comma-delimited list of Keystore, Directory CertStore, or LDAP providers. The TrustStore is implicitly used as a CertStore so the Trusted CA certificates are not required to be duplicated in one of those CertStores. A certificate can be added to a Keystore using the JDK keytool. To add a certificate to a Directory CertStore, save the certificate file in the file system directory. To add a certificate to LDAP, consult your system administrator. The LDAP database must conform to the schema described in RFC2587.

The following table lists the parameter values for the XDXMLDSigVerifyAgent. Other parameters that are not listed have their default value.

Parameter	Value
TrustStore Provider	trustprov
Certificate Store Providers	ksprov

This assumes that trustprov is the name of a KeyStore provider that contains the certificates of the Trusted CAs and that ksprov is the name of a KeyStore provider that points to a keystore file that contains the signer certificate. The Certificate Store provider could also be a Directory CertStore or an LDAP Provider.

The XDXMLDSigCreateAgent can create this signature by setting the Include Certificate Chain parameter to No Certificates, the Include Issuer Serial parameter to true, and the Include Subject Name parameter to false.

A sample input document is shown as follows (indented for display purposes only):

x

For a variety of reasons, the certificate issuer might revoke a certificate before its expiration date. For example, this can happen if the private key is compromised, an employee has left the company, and so on. The issuer publishes a Certificate Revocation List (CRL) to instruct applications that these certificates are no longer valid. The service can validate the signer certificate chain against a CRL if Certificate Revocation is enabled. The service will query its CertStores for the CRL from that issuer. If there are no revoked certificates, a CRL that contains no certificates is required. If the CRL is not found, then the service takes the conservative approach and assumes that the certificate might be invalid and rejects the signature as a result. Since a KeyStore cannot contain a CRL, the CRL must be stored in another provider, such as a Directory CertStore or LDAP. The simplest solution is to store the CRL file in the file system directory of a Directory CertStore.

The KeyInfo element may also contain X509CRL elements to include CRLs within the Signature. The service can use the CRLs in X509CRL elements if present. In practice, this is rarely used since CRLs can become quite large compared to the size of the message.

The following table lists the parameter values for the XDXMLDSigVerifyAgent. Other parameters that are not listed have their default value.

Parameter	Value
TrustStore Provider	trustprov
Certificate Store Providers	ksprov,certprov
Enable Certificate Revocation	true

This assumes that trustprov is the name of a KeyStore provider that contains the certificates of the Trusted CAs; ksprov is the name of a KeyStore provider that points to a keystore file that contains the signer certificate; and certprov is the name of a Directory CertStore provider that points to a directory that contains the issuer CRL in a file.

Any signature example you have seen so far can be validated by this service. The signature will fail if the signer certificate was revoked, and succeed otherwise.

x

A signature can be valid and still be useless. The application must also verify that all sensitive information in the document has been covered by the signature. Otherwise, the information could be modified after the fact without affecting the signature. The service can verify the signature has appropriate coverage.

The Required Signature Coverage parameter is an XPath expression that returns a NodeSet. Each node in the NodeSet must have been signed to consider the signature valid. For every sensitive node, the XPath expression should return that node or one of its ancestors. Notice that the parameter does not demand the presence of a node. If a node is missing in the document, then it does not matter whether that node has been signed or not because there is no possibility the application could use that node anyway. The application can reject the incomplete message at a later time, but that is unrelated to the signature.

For example, if the application expects a SOAP message with a BinarySecurityToken in a SOAP Header, it can specify the union of the path to the security token and the SOAP Body in the XPath expression. Since a Signature never covers itself, the Signature element should never be returned by the XPath expression.

To avoid the dual evaluation of the transforms, that feature assumes the transforms are hierarchical starting at the node pointed to by the Reference URI. The inclusive and exclusive XML canonical transforms are supported, but the XPath Filter and XSLT transforms are not.

If the application accesses the attachments, then it should ensure they have been covered by the signature. The Unsigned Attachment parameter determines what action to perform when there are unsigned attachments. The service can keep the unsigned attachments and accept the signature, remove the unsigned attachments and accept the signature, or fail validation. There is no option to demand the presence of an attachment since there is no possibility the application could use an unsigned attachment if that attachment is absent. Again, the application can reject incomplete messages at a later time.

It is assumed that the XML Namespace provider xmlnsprov defines the following prefixes:

Prefix	XML Namespace
soapenv	http://schemas.xmlsoap.org/soap/envelope/
wsse	http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd

The following table lists the parameter values for the XDXMLDSigVerifyAgent. Other parameters that are not listed have their default value.

Parameter	Value
TrustStore Provider	trustprov
XML Namespace Provider	xmlnsprov
Required Signature Coverage	/soapenv:Envelope/soapenv:Header/wsse:Security/wsse:BinarySecurityToken| /soapenv:Envelope/soapenv:Body
Unsigned Attachment	Fail Validation

The service will fail the following signature because the BinarySecurityToken in the SOAP Header is not covered by any Reference. The Signature would have been valid if the Required Signature Coverage parameter had been left blank.

x

By default, the service looks throughout the document for the Signature element. A clever attacker could add a second Signature to confuse the service. It is more secure to declare the location where the application expects to find the signature. The Signature Element Path parameter is an XPath expression that evaluates to the Signature node. For example, for a SOAP message, the XPath expression would be a path somewhere within the SOAP Headers. The XPath expression can be the union of two paths if the application is expecting signatures in one of two locations. An XML Namespace Provider is needed if the XPath expression contains namespaces.

Some transforms are very powerful, for example, the XSLT transform describes an engine that is highly programmable. This makes the signature verification process vulnerable because it is the equivalent of running code provided by the peer. An attacker can easily write a transform that adversely affects the server, for example by running an infinite loop. To counter these threats, the Acceptable Transforms parameter can be set to a space-separated list of transform names. The service will accept to execute a transform only if it appears in this white list. If another transform is encountered, then the validation fails before the transform is evaluated. By default, the service accepts to execute any transform available to the server. The service treats the Signature canonicalization method as just another kind of transform with respect to this parameter, and therefore its algorithm must also be present in the white list.

The service can verify an encryption key has not been used inadvertently for signing. When the Enforce KeyUsage Extension parameter is set, the service checks the KeyUsage extension in the signer certificate for the presence of the digitalSignature and/or nonRepudiation flags. The validation fails if the KeyUsage extension is missing or the chosen combination of the flags is off. An application interested in these features will also be interested in the Signature Coverage feature, which is discussed in Example 4: Signature Coverage.

It is assumed that the XML Namespace provider xmlnsprov defines the following prefixes:

Prefix	XML Namespace
soapenv	http://schemas.xmlsoap.org/soap/envelope/
wsse	http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
ds	http://www.w3.org/2000/09/xmldsig#

The following table lists the parameter values for the service. Other parameters that are not listed have their default value.

Parameter	Value
TrustStore Provider	trustprov
Enforce KeyUsage Extension	digitalSignature
XML Namespace Provider	xmlnsprov
Signature Element Path	/soapenv:Envelope/soapenv:Header/wsse:Security/ds:Signature
Acceptable Transforms	http://www.w3.org/TR/2001/REC-xml-c14n-20010315 http://www.w3.org/2000/09/xmldsig#enveloped-signature http://www.w3.org/2001/10/xml-exc-c14n# http://docs.oasis-open.org/wss/oasis-wss-SwAProfile-1.1#Attachment-Content-Signature-Transform

The following signature is rejected by the service because it is not in the expected location within the document:

The following signature is rejected because the Reference includes a transform that is not listed in the list provided by the Acceptable Transforms parameter: