Overview (KSI SDK 4.19.220 API)

Packages
Package	Description
com.guardtime.ksi	KSI API interface
com.guardtime.ksi.blocksigner	Classes and interfaces to create multiple signatures with one signing request
com.guardtime.ksi.concurrency	Classes for concurrency handling
com.guardtime.ksi.exceptions	KSI exception classes
com.guardtime.ksi.hashing	Classes to create and represent data hashes
com.guardtime.ksi.pdu	PDU (Protocol Data Unit) interfaces
com.guardtime.ksi.pdu.exceptions	PDU exception classes
com.guardtime.ksi.pdu.v2	PDU v2 implementation
com.guardtime.ksi.publication	Interfaces to decode and encode publications files
com.guardtime.ksi.publication.adapter	Adapters for publications file client
com.guardtime.ksi.publication.inmemory	Implementation to decode and encode in-memory publications files
com.guardtime.ksi.service	Classes and interfaces to sign and extend, advanced version
com.guardtime.ksi.service.client	Classes and interfaces to sign and extend, basic version
com.guardtime.ksi.service.client.http	Common classes for KSI Apache HTTP client and KSI Simple HTTP client
com.guardtime.ksi.service.client.http.apache	Apache HTTP client for KSI
com.guardtime.ksi.service.ha	High Availability KSI service, combines other services to achieve redundancy
com.guardtime.ksi.service.http.simple	Simple HTTP client for KSI
com.guardtime.ksi.service.tcp	KSI TCP client
com.guardtime.ksi.tlv	Classes and interfaces to decode and encode TLV elements
com.guardtime.ksi.tree	Classes and interfaces to build a hash tree
com.guardtime.ksi.trust	Trust provider classes
com.guardtime.ksi.unisignature	Interfaces to decode and encode KSI signatures
com.guardtime.ksi.unisignature.inmemory	Classes to decode and encode in-memory KSI signatures
com.guardtime.ksi.unisignature.verifier	Classes and interfaces to verify KSI signatures
com.guardtime.ksi.unisignature.verifier.policies	KSI signature verification policies
com.guardtime.ksi.unisignature.verifier.rules	KSI signature verification rules
com.guardtime.ksi.util	Internal utility classes

Introduction

This is the Java SDK for KSI service. It provides functionality to create, extend and verify KSI signatures.

Modules

The KSI Java SDK project contains the following modules:

ksi-api - main module
ksi-common - contains common functionality
ksi-service-client - common module for all KSI service clients
ksi-service-client-common-http - common module for all KSI HTTP service clients
ksi-service-client-apache-http - KSI HTTP service client implementation, uses apache-async-httpclient to communicate with the server
ksi-service-client-simple-http - KSI HTTP service client implementation, uses Java standard API to communicate with the server
ksi-service-client-tcp - KSI TCP signing and extending service client implementation.
ksi-service-ha - KSI High-availability service implementation (Implements KSISigningService and KSIExtenderService)
ksi-blocksigner - module for signing multiple data hashes as a block, in one operation

Dependencies

The following is a list of compile dependencies for this project. These dependencies are required to compile and run the application:

Bouncycastle - used for cryptographic functions
SLF4J - logging facade for logging

Optional libraries:

apache-async-httpclient - dependency needed in application classpath if the ksi-service-client-apache-http module is used
mina-core - used by ksi-service-client-tcp module
SLF4J simple implementation - simple SLF4J backend that logs to standard output

All libraries are bundled with source, including optional libraries. If these are not required, the SDK user must exclude them.

Logging

KSI Java SDK uses SLF4J for logging, SLF4J is a facade for different logging frameworks(e.g. java.util.logging, logback, log4j). By default simple implementation is included with API that logs to standard output.

SLF4J allows developers to send KSI Java SDK logs to the logging framework used in their application. To enable it, logging framework support must be downloaded from SLF4J homepage and added to classpath.

Usage

Java SDK API is provided by com.guardtime.ksi.KSI interface

Initialization

To obtain a instance of com.guardtime.ksi.KSI the com.guardtime.ksi.KSIBuilder class can be used. com.guardtime.ksi.KSIBuilder class checks that at least the following parameters are present:

signing client - used to sign data
extender client - used to extend/verify KSI signatures
publications file client - used to download publications file
publications file trusted certificate selector - used to define the additional parameters to check while verifying the publications file signing certificate

The following code creates a instance of com.guardtime.ksi.KSI with SimpleHttpClient:


    SimpleHttpClient simpleHttpClient = ...

    KSIBuilder builder = new KSIBuilder().
    setKsiProtocolSignerClient(simpleHttpClient).
    setKsiProtocolExtenderClient(simpleHttpClient).
    setKsiProtocolPublicationsFileClient(simpleHttpClient).
    setPublicationsFileTrustedCertSelector(new X509CertificateSubjectRdnSelector("E=test@test.com"));

    KSI ksi = builder.build();

    // use KSI object


    // release resources
    ksi.close();

The following clients are currently implemented:

SimpleHttpClient - uses Java standard API to communicate with the server
ApacheHttpClient - uses Apache HTTP client to communicate with the server
TCPClient - uses TCP protocol. NB! Only signing and extending are supported! Can not be used to download publications file!
HAService - Combines one to many KSISigningServices and one to many KSIExtenderClients or KSIExtenderServices to achieve redundancy. NB! Only signing and extending are supported!

Method setPublicationsFilePkiTrustStore(trustStore) from com.guardtime.ksi.KSIBuilder class can be used to specify the default Java KeyStore to be used when verifying the publications file. This keystore is used to build a valid certificate path from root certificate to the certificate that was used for publications file signing. Method setPublicationsFileTrustedCertSelector(CertSelector certSelector) from com.guardtime.ksi.KSIBuilder class defines the additional parameters to check when verifying the signing certificate. A CertSelector defines a set of criteria for signing certificate. The following implementation of CertSelector exist:

com.guardtime.ksi.trust.X509CertificateSubjectRdnSelector implemented by Guardtime. Selects certificates by Subject DN values (e.g. E=test@test.com).
java.security.cert.X509CertSelector is part of Java SDK. See X509CertSelector javadoc for more information.

A new implementation (e.g. reading configuration from file) can be added by implementing CertSelector interface. The following example code creates an instance of com.guardtime.ksi.KSI with com.guardtime.ksi.trust.X509CertificateSubjectRdnSelector and custom truststore:


    SimpleHttpClient simpleHttpClient = ...

    KeyStore trustStore = loadKeyStore();
    KSIBuilder builder = new KSIBuilder().
    setKsiProtocolSignerClient(simpleHttpClient).
    setKsiProtocolExtenderClient(simpleHttpClient).
    setKsiProtocolPublicationsFileClient(simpleHttpClient).
    setPublicationsFilePkiTrustStore(trustStore).
    setPublicationsFileTrustedCertSelector(new X509CertificateSubjectRdnSelector("E=test@test.com, CN=My Test CN"));

    KSI ksi = builder.build();

Method setDefaultSigningHashAlgorithm(HashAlgorithm algorithm) from com.guardtime.ksi.KSIBuilder class is used to specify the default signing hash algorithm. For all the following operations, KSI object can be used. There are also separate interfaces created. The following examples cover usage of KSI interface and also operation specific ones.

Read Signature

The following code can be used to read signature:


    // KSI
    KSI ksi = ...

    // read signature from disk
    KSISignature signature = ksi.read(new File("signature.ksig"));

    // read using input stream
    KSISignature signature2 = ksi.read(new FileInputStream("signature.ksig"));

    // read using byte array
    byte[] bytes = getSignatureBytes();
    KSISignature signature3 = ksi.read(bytes);
    
    
    // using Reader interface
    Reader reader = new SignatureReader();
    KSISignature signature = reader.read(new File("signature.ksig"));

Create Signature

The following code can be used to create signature:


    // KSI
    KSI ksi = ...

    // synchronous signing
    KSISignature sig = ksi.sign(new File("file.txt"));
    // asynchronous signing
    Future<KSISignature> future = ksi.asyncSign(new File("asyncFile.txt"));
    KSISignature signature2 = future.getResult();


    // using Signer interface
    CredentialsAwareHttpSettings settings = new CredentialsAwareHttpSettings("signing-service-url", KSIServiceCredentials);
    SimpleHttpSigningClient signingClient = new SimpleHttpSigningClient(settings);

    Signer signer = new SignerBuilder().setSigningService(new KSISigningClientServiceAdapter(signingClient)).build();

    KSISignature signature = signer.sign(new File("file.txt"));

Extend Signature

The following code can be used to extend signature:


    // KSI
    KSI ksi = ...

    // read signature from disk
    KSISignature signature = ksi.read(new File("signature.ksig"));

    // synchronous extending
    KSISignature extendedSignature = ksi.extend(signature);

    // asynchronous extending
    Future<KSISignature> future = ksi.asyncExtend(signature);
    KSISignature extendedSignature2 = future.getResult();
    
    
    // using Extender interface
    CredentialsAwareHttpSettings settings = new CredentialsAwareHttpSettings("extender-service-url", KSIServiceCredentials);
    SimpleHttpExtenderClient extenderClient = new SimpleHttpExtenderClient(settings);

    Extender extender = new ExtenderBuilder().setExtendingService(new KSIExtendingClientServiceAdapter(extenderClient))
                                             .setPublicationsHandler(publicationsHandler).build();

    KSISignature extendedSignature = extender.extend(signature);

Verify Signature

Java SDK provides policy based verification process. To verify a signature the VerificationContext must be built and policy must be selected. Currently the following policies are implemented:

KeyBasedVerificationPolicy can be used if the signature contains a calendar hash chain and a calendar authentication record. NB! Key-based verification should be used for short-term verification before a publication becomes available.
UserProvidedPublicationBasedVerificationPolicy can be used to verify signatures with user provided publication.
PublicationsFileBasedVerificationPolicy can be used to verify signatures using publications file.
CalendarBasedVerificationPolicy takes as input the computed output hash of aggregation hash chains and the `aggregation time'. It requires on-line access to the extending service and allows verification using the calendar database as the trust anchor.

Any verification process may finish with three possible outcomes:

Verification succeeded, which means there's a way to prove the correctness of the signature.
Verification not possible, which means there is not enough data to prove or disprove the correctness of the signature.
Verification failed, which means the signature is definitely invalid or the document does not match with the signature.

The following code can be used to create verification context:


    KSI ksi = ...
    SimpleHttpClient simpleHttpClient = ...
    PublicationsFile publicationsFile = ...

    KSISignature signature = ksi.read(new File("signature.ksig"));

    VerificationContextBuilder builder = new VerificationContextBuilder().
    setSignature(signature).
    setExtenderClient(simpleHttpClient).
    setPublicationsFile(publicationsFile);
    VerificationContext context = builder.createVerificationContext();

The following code can be used to verify the signature:


    // KSI
    KSI ksi = ...

    VerificationContext context = ...
    Policy policy = new KeyBasedVerificationPolicy();
    VerificationResult result = ksi.verify(context, policy);
    
    
    // using Verifier interface
    Verifier verifier = new SignatureVerifier();
      
    VerificationResult result = verifier.verify(signature, ContextAwarePolicyAdapter.createKeyPolicy(publicationsHandler));

Get Info About Configuration

KSI SDK can be used to get information about KSISigningService's or KSIExtenderService's configuration. If the service is connected to a single Gateway then it represents the configuration of this Gateway. If the service composes of multiple other clients then their configurations are consolidated into one. To get information about a service's configuration one should register a configuration update listener. Configuration updates can be pushed by Gateways without client explicitly asking for them and they can be invoked by service also. Following is the example how to register a listener for Aggregator configuration updates and how to call for an update (works similarly with KSIExtenderClient):


    KSISigningClient signingClient = ...
    signingClient.registerAggregatorConfigurationListener(new ConfigurationListener<AggregatorConfiguration> {
        public void updated(AggregatorConfiguration aggregatorConfiguration) {
            // do something with the updated configuration
        }

        public void updateFailed(Throwable t) {
            // do something with the exception that made the configuration update fail
        }
    });
    signingClient.getAggregationConfiguration(); // Invokes a configuration request. Does not block until it responds. Gives back a Future which can be used as an alternative way in addition to listeners to access the result.

HTTP Proxy Configuration

By adding the following JVM arguments to Java, KSI SDK will use the proxy to create HTTP requests.

http.proxyHost=PROXY_URL_OR_IP
http.proxyPort=PROXY_PORT

Alternatively the HTTPConnectionParameters class can be used to configure HTTP proxy. The following code creates the SimpleHttpClient using the proxy with given configuration.


    KSIServiceCredentials credentials = new KSIServiceCredentials("user", "key");
    HttpClientSettings settings = new HttpClientSettings("signing_url", "extending_url",
    "publications_file_url", credentials);
    HTTPConnectionParameters parameters = new HTTPConnectionParameters();
    parameters.setProxyUrl(new URL("proxy_url"));
    parameters.setProxyUser("proxy_username");
    parameters.setProxyPassword("proxy_password");
    settings.setParameters(parameters);
    SimpleHttpClient httpClient = new SimpleHttpClient(settings);

NB! When the proxy server uses username/password for authentication then the HTTPConnectionParameters class must be used to configure proxy.

HAService Configuration

More redundant connection to gateway can be achieved using HAService. HAService combines multiple other services, sends requests to all of them in parallel and gives back the first successful one.

To configure HAService, initialize the services it uses and build a HA services with those instances:

    KSISigningClient signingClient1 = ...
    KSISigningClient signingClient2 = ...
    KSISigningClient signingClient3 = ...

    KSIExtenderClient extenderClient1 = ...
    KSIExtenderClient extenderClient2 = ...
    KSIExtenderClient extenderClient3 = ...

    SigningHAService signingHaService = new SigningHAService.Builder()
                            .addClients(Arrays.asList(signingClient1, signingClient2, signingClient3))
                            .build();
    ExtendingHaService extendingHaService = new ExtendingHAService.Builder()
                            .addClients(Arrays.asList(extenderClient1, extenderClient2, extenderClient3))
                            .build();

    KSI ksi = new KSIBuilder()
                            .setSigningService(signingHaService)
                            .setExtendingService(extendingHaService)
                            // set everything else
                            .build();

Acknowledgements

This product relies on software developed by the Legion of the Bouncy Castle (www.bouncycastle.org).

This product includes software developed by The Apache Software Foundation (www.apache.org/).