Library to perform transaction signatures.
This is library to perform signing and validation of transactions consisting of one or more documents. Documents are signed according to the ETSI specifications for advanced electronic signatures:
-
XAdES (ETSI TS 101 903)
-
PAdES (ETSI TS 102 778)
-
CAdES (ETSI TS 103 173)
A full working example is available in BasicExample.java
. This section goes
through the essential parts of basic usage.
The following example shows how to create a new instance of a transaction signer that can be used to sign documents. In this example authentication is performed using an API key.
Note
|
For more information about how the transaction signer can be configured
please read the Javadoc for TransactionSigner.Builder .
|
TransactionSigner signer = new TransactionSigner.Builder() .apiEndpoint("http://192.168.99.21:8080/lcso/signRequest/rest/v1") .apiKey("iqxMo5Im4ya2EZsPravicPxj") .signType("rsa2048_sha256") .keyId("testkey") .build();
It is also possible to perform authentication using client certificate. The following
example shows how to create transaction signer that is using client certificate and
private key from an existing java.security.KeyStore
, along with a custom truststore
that will be used when verifying server certificates during TLS handshake.
Note
|
loadExternalKeyStore and loadExternalTrustStore in this example needs to be
implemented by the reader. Truststore is optional when building the transaction signer
and if not specified the default JRE truststore will be used, containing publicly trusted
certificate authorities.
|
KeyStore keyStore = loadExternalKeyStore(); KeyStore trustStore = loadExternalTrustStore(); TransactionSigner signer = new TransactionSigner.Builder() .apiEndpoint("http://localhost:8080/lcso/signRequest/rest/v1") .sslKeyStore(keyStore, "123456") .sslTrustStore(trustStore) .signType("rsa2048_sha256") .keyId("testkey") .build();
It is also possible to specify keystore and/or truststore using a path that is available on the local file system.
TransactionSigner signer = new TransactionSigner.Builder() .apiEndpoint("http://192.168.99.21:8080/lcso/signRequest/rest/v1") .sslKeyStore("/path/to/keystore.jks", "123456", "JKS") .sslTrustStore("/path/to/truststore.jks", "changeit", "JKS") .signType("rsa2048_sha256") .keyId("testKey") .build();
Document can then be signed as shown in the following example.
Document document = new Document("/some/file.xml"); SignedDocument signedDocument = signer.signDocument(document);
The following example shows how to create an instance of a transaction validator that can be used to validate a previously signed document.
Note
|
For more information about how the transaction validator can be configured
please read the Javadoc for TransactionValidator.Builder .
|
TransactionValidator validator = new TransactionValidator.Builder() .trustStore("/path/to/truststore.jks", "changeit", "JKS") .build();
It is also possible to specify truststore using an existing instance of a java.security.KeyStore
which might be needed
if the keystore is loaded from an external data store (e.g. key vault service) and not available on the local file system.
Note
|
loadExternalTrustStore in this example needs to be implemented by the reader.
|
KeyStore trustStore = loadExternalTrustStore(); TransactionValidator validator = new TransactionValidator.Builder() .trustStore(trustStore) .build();
A signed document can then be validated as shown in the following example.
try { validator.validateDocument(signedDocument); // Signature validation successful. } catch(ValidationException e){ // Signature validation failed. }
In some scenarios the library might be used in Java environments that does not support the default XML processor features and/or attributes, indicated by the following error.
Failed to process sign response: SECURITY : unable to set attribute(s) [Attribute 'http://javax.xml.XMLConstants/property/accessExternalDTD' = ''. Cause : Not supported: http://javax.xml.XMLConstants/property/accessExternalDTD, Attribute 'http://javax.xml.XMLConstants/property/accessExternalStylesheet' = ''. Cause : Not supported: http://javax.xml.XMLConstants/property/accessExternalStylesheet]
This can be solved by removing unsupported attributes and/or disabling unsupported features by using a customized TransformerFactoryBuilder. The example error above can be resolved with the following piece of code.
// Necessary imports
import eu.europa.esig.dss.jaxb.TransformerFactoryBuilder;
import eu.europa.esig.dss.jaxb.XmlDefinerUtils;
// Create custom TransformerFactoryBuilder without unsupported attributes
TransformerFactoryBuilder secureTransformerFactoryBuilder = TransformerFactoryBuilder.getSecureTransformerBuilder();
secureTransformerFactoryBuilder.removeAttribute("http://javax.xml.XMLConstants/property/accessExternalDTD");
secureTransformerFactoryBuilder.removeAttribute("http://javax.xml.XMLConstants/property/accessExternalStylesheet");
// Instruct DSS library to use it
XmlDefinerUtils.getInstance().setTransformerFactoryBuilder(secureTransformerFactoryBuilder);
This should be executed during application startup before any document is signed or validated.
A Simple commandline tool exist to test functionality of the library.
The tool is available in the class se.signatureservice.transactionsigning.cli.SignTool
.
Note
|
To enable logging a SLF4J binding must be placed on the classpath (ex. slf4j-simple-x.y.z.jar ).
|
export TS_APIENDPOINT="https://sign.somecompany.com/lcso/signRequest/rest/v1" export TS_SIGNTYPE="rsaSign_ades" export TS_KEYID="testKey" export TS_APIKEY="iqxMo5Im4ya2EZsPravicPxj" java -cp certservice-transactionsigning-1905.1.jar \ se.signatureservice.transactionsigning.cli.SignTool \ sign /some/path/testdocument.xml /tmp/signeddoc.xml
export TS_APIENDPOINT="https://sign.somecompany.com/lcso/signRequest/rest/v1" export TS_SIGNTYPE="rsaSign_ades" export TS_KEYID="testKey" export TS_KEYSTORE="/some/path/keystore.jks" export TS_KEYSTORE_PASSWORD="somepassword" java -cp certservice-transactionsigning-1905.1.jar \ se.signatureservice.transactionsigning.cli.SignTool \ sign /some/path/testdocument.xml /tmp/signeddoc.xml
export TS_APIENDPOINT="https://sign.somecompany.com/lcso/signRequest/rest/v1" export TS_SIGNTYPE="rsaSign_ades" export TS_KEYID="testKey" export TS_KEYSTORE="/some/path/keystore.jks" export TS_KEYSTORE_PASSWORD="somepassword" export TS_TRUSTSTORE="/tmp/ssl-truststore.jks" export TS_TRUSTSTORE_PASSWORD="foo123" java -cp certservice-transactionsigning-1905.1.jar \ se.signatureservice.transactionsigning.cli.SignTool \ sign /some/path/testdocument.xml /tmp/signeddoc.xml
This section describes how to migrate from old version of the library (โ 2211.1) to a newer version of the library.
The new version of the library is called Signature Service Transaction Signing Library. This means that the release artifact names has changed.
Old artifact name | New artifact package |
---|---|
certservice-transactionsigning-<version>.zip |
signservice-transactionsigning-<version>.zip |
certservice-transactionsigning-<version>.jar |
signservice-transactionsigning-<version>.jar |