XAdES Digital Signature Verify Service

In this section:

Syntax: 

com.ibi.agents.XDXAdESVerifyAgent

Description:

This service is used to validate an XML Advanced Electronic Signature. Refer to the XAdES Digital Signature Create service for some background information on XAdES. This guide assumes the reader is familiar with the XAdES specification.

Parameters:

The following tables describe the parameters for the XAdES Digital Signature Verify service. Each table is followed by a discussion of that parameter group.

Signature Location

Parameter Name

Description

XML Namespace Provider

Provider for the mapping between XML namespace prefix and namespace URI. If left blank, the XPath expression in the Element Path and Required Signature Coverage parameters cannot contain namespaces.

XPath Syntax

Determines which syntax level of XPath should be used. You can select the iWay abbreviated syntax or the XPath 1.0 full syntax. The default option selects the syntax level as set in the General Settings area of the iSM Administration Console.

Signature Element Path

Path to the signature XML element. If left blank, the service will search throughout the document for an element named Signature in the namespace http://www.w3.org/2000/09/xmldsig#.

Remove Security Parent Element

If set to True, the WSSE Security parent element is removed from the document after the verification is successful.

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.

The Remove Security Parent Element boolean parameter is a way to remove a SOAP header after it has been processed.

Signature Criteria

Parameter Name

Description

TrustStore Provider

Provider for the keystore containing the Certificate Authorities.

Certificate Store Providers

Comma-separated List of Keystore, Directory CertStore or LDAP providers for the certificate stores used to complete the certificate chain and to retrieve revocation material.

Enable Certificate Revocation

If set to true, use the CRLs from the CertStores to check whether the certificate of the signer has been revoked.

Maximum Path Length

Maximum number of non-self-issued intermediate certificates that may exist in a certification path. The last certificate in a certification path is not included in this limit. 0 implies that the path can only contain a single certificate. -1 implies that there is no maximum. If any of the CA certificates contain the BasicConstraintsExtension, the value of the pathLenConstraint field of the extension overrides the Maximum Path Length parameter.

Enforce KeyUsage Extension

Determines how the KeyUsage Extension is verified when present in the signer certificate. The options are Not Enforced, digitalSignature, nonRepudiation, digitalSignature OR nonRepudiation, digitalSignature AND nonRepudiation.

Message Digest JCE Provider

JCE Provider for the MessageDigest service. If left blank, the default JCE provider for the MessageDigest service will be used.

Required Signature Coverage

An XPath expression that returns a node-set, where each node in the set must have been signed by the Signature to be considered valid.

Unsigned Attachment

Action to perform when a document contains an unsigned attachment. Select one of the following values from the drop-down list:

  • Keep Unsigned Attachment {keep} (default)
  • Remove Unsigned Attachment {remove}
  • Fail Validation {fail}

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.

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.

XAdES Criteria

Parameter Name

Description

Minimum XAdES Form

Specifies the minimum acceptable XAdES form. Signatures simpler than this form will cause a validation failure.

Signature Policy Provider

The name of a Signature Policy Provider. This specifies the mapping from ObjectIdentifier (URI or OID) to policy file. The policy file is needed to verify signatures with an explicit policy. If left blank, only absent or implied policies can be validated.

Accept Implied Policy

Indicates whether the verifier should accept an implied signature policy.

Accept Unknown Properties

Indicates whether the verifier should accept unknown properties. This only affects the unsigned properties.

A XAdES signature is a regular XML Digital Signature with extra signed and unsigned properties. The specification is organized in a handful of signature forms that define strictly increasing set of properties from the simplest form to the most complex one.

The Minimum XAdES Form parameter is a convenient way to require some qualifying properties be present in the signature. The XAdES-BES form is the simplest form, therefore this value accepts every XAdES signature. The XAdES-EPES form demands the presence of a signature policy. The XAdES-T form requires the XAdES-EPES properties plus the presence of a Signature time stamp. Finally, the XAdES-C form demands the XAdES-T properties plus the complete certificate and revocation references.

A signature policy is a document in human readable form. It is an agreement between the signer and verifier describing the rules to follow to produce and verify the signature, and what claims can be made given the rules are satisfied. For example, the policy may demand a certain signing key size, or that certification revocation must be checked. The policy may say the signer agrees to consider his electronic signature legally binding in the context of sending purchase orders to his supplier, provided the policy rules are followed, of course.

The Policy can be absent, implied or explicit in the Signature. An absent policy is not mentioned at all, so the verifier can make no assumptions whether a policy is effectively in use. An implied policy specifies that a policy is in use, but it does not say which one. It is assumed that the applicable policy is clear from context. One would assume the policy itself explains in which context it applies. Finally, an explicit policy has a reference embedded in the signature to uniquely identify the version of the policy document in use. The reference consists of a unique ObjectIdentifier (URI or OID) and a hash computed over the document.

To compute the policy hash, the service needs a mapping from ObjectIdentifier to the policy file. This is done outside the service in a Signature Policy Provider. This type of provider can be configured on the same console page as the other security providers (like KeyStores). Many Signature Policy Providers can be created. The Signature Policy Provider parameter determines which one to use. The same provider can be shared by many XAdES Signature Verify Services, making it convenient to declare the mapping only once for multiple use.

An explicit policy is valid if the Signature Policy Provider can determine the path to the policy file and the hash of the contents of the file is equal to the hash that appears in the Signature. The hash guarantees the signer and verifier have the exact same document in their possession. Since the policy is not in machine readable form, no further checking is done.

The Signature Policy Provider should only map the policies that are deemed acceptable.

The policy document is not needed to verify an implied policy. Since the Signature Policy Provider is not involved, the service relies on the Accept Implied Policy boolean parameter to determine whether an implied policy is acceptable.

Finally, the Accept Unknown Properties boolean parameter indicates whether the verifier should accept unknown properties. This only affects the unsigned properties since the schema of signed properties is closed.

Edges:

The following table lists and describes the edges that are returned by the XAdES Digital Signature Verify service.

Edge

Description

success

The Signature is valid.

fail_parse

An iFL or XPath expression could not be evaluated.

fail_operation

The validation could not be performed.

fail_unsigned

The XML document is not signed.

fail_verify

The Signature is invalid.

fail_coverage

The application specified a node or attachment that should have been signed but was not covered by the Signature.

If the signature validates, the service will continue on the success edge. If validation fails because of Unsigned Attachments or incomplete Required Signature Coverage, the service will follow the fail_coverage edge. If validation fails for other reasons, the service will follow the fail_verify edge. If there is no signature, the flow will continue on the fail_unsigned edge.

Special Registers:

The following table lists and describes the special registers assigned upon successful validation of the signature.

Special Register

Description

xmldsig_signer

Holds the signer Distinguished Name

xmldsig_signer_cn

Holds the signer Common Name found in the signer Distinguished Name

xades_form

The XAdES Signature form. Possible values are XAdES-BES, XAdES-EPES, XAdES-T, XAdES-C.
x
Examples

For more information on related examples of XML Digital Signatures, see XML Digital Signature Verify Service. In particular, Example 3 on Certificate Revocation, Example 4 on Signature Coverage and Example 5 on Reducing Risks are directly applicable. The following examples cover topics specific to XAdES Signature verification.

Note: The examples in this section are specific to the XAdES Digital Signature Verify service. For your convenience, the sample input and output documents are attached to the PDF in unabbreviated form.

For PDF-compatibility purposes, the file extension of the xades.zip file is temporarily renamed to .zap. After saving this file to your file system, you must rename this extension back to .zip before the file can be used.
x
Example 1: Minimum XAdES Form

This example shows how to demand the presence of a signature policy by requesting the XAdES-EPES minimum form.

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

Parameter

Value

TrustStore Provider

trustprov

Minimum XAdES Form

XAdES-EPES

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

The XAdES-EPES form requires a signature policy. Since we did not configure a Signature Policy Provider, the service will only accept signatures with an implied policy. Refer to Example 2: Explicit Signature Policy for an example with an explicit signature policy.

The first sample input document is shown as follows (indented for display purposes only).

A sample output of the service is shown as follows (indented for display purposes only):

This signature is in XAdES-BES form and will be rejected because it lacks a Signature Policy. An error document will be produced and the flow will continue on the fail_verify edge.

The second sample input document is shown as follows (indented for display purposes only).

This signature is in XAdES-EPES form and will be accepted. The output document is the same as the input document. The flow will continue on the success edge. The special register xmldsig_signer will be equal to CN=Partner SMIME Signature, O=Partner, C=US. The special register xmldsig_signer_cn will be equal to Partner SMIME Signature. Finally, the special register xades_form will be equal to XAdES-EPES.
x
Example 2: Explicit Signature Policy

This example shows how to require an explicit signature policy.

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

Parameter

Value

TrustStore Provider

trustprov

Minimum XAdES Form

XAdES-EPES

Signature Policy Provider

policyprov

Accept Implied Policy

false

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

The minimum XAdES form chosen requires a signature policy. Since the Accept Implied Policy parameter is false, this will require an explicit policy. The mapping between policy ObjectIdentifier (URI or OID) to the policy file must be configured in a Signature Policy Provider. Assume the provider policyprov has a mapping from the URI http://iwaysoftware.com/xades#policy1.0 to the policy file policies/policy-1.0.doc. Assume that file contains the policy document.

The second input document in Example 1 will now be rejected because the policy is not explicit. A sample output of the service is shown as follows (indented for display purposes only):

Another sample input document is shown as follows (indented for display purposes only).

This signature will be accepted if the policy-1.0.doc file contains the same policy document used by the signer. The output document will be the same as the input. The flow will continue on the success edge.

If the contents of the policy-1.0.doc file is modified, the hash will no longer agree and the signature will be rejected. The flow would continue on the fail_verify edge with an error document.

iWay Software