signservice-integration

Signature Service Integration Programming Guide

License

Programming Guide for the Signature Service Integration Service.

Table of contents

  1. Introduction

    1.1. Getting the Artifacts

    1.2. Java Documentation

    1.3. Design Principles

    1.3.1. PostConstruct Annotations

    1.3.2. Use of Lombok

    1.3.3. Java Version Compatibility

    1.3.4. Logging

  2. Initializing the Library

    2.1. Spring Boot Example

    2.2. Initializing Manually

1. Introduction

This is the Programming Guide for how to use the implementation of the Signature Service Intergration API. If you haven’t already done so, check out the documentation for the API. There you find information about the federated signing concept and detailed descriptions of the actual API. This programming guide focuses on how to use the implementation of the API and assumes that you are familiar with the API.

1.1. Getting the Artifacts

The implementation of the Signature Service Integration API comprises of three artifacts:

Even though you can build the artifacts yourself by cloning the https://github.com/idsec-solutions/signservice-integration repo, it is probably easier to just download the artifacts from Maven central.

signservice-integration-impl

Maven Central

<dependency>
  <groupId>se.idsec.signservice.integration</groupId>
  <artifactId>signservice-integration-impl</artifactId>
  <version>${signservice-impl.version}</version>
</dependency>

Note: The signservice-integration-impl artifact has an optional dependency to spring-core (org.springframework:spring-core). The only reason for that is if you need to use the PdfSignatureImageTemplateExt class. This will probably change in the future.

signservice-integration-xml

Maven Central

If you want to support signing of XML documents, you need the signservice-integration-xml artifact.

<dependency>
  <groupId>se.idsec.signservice.integration</groupId>
  <artifactId>signservice-integration-xml</artifactId>
  <version>${signservice-xml.version}</version>
  <exclusions>
    <exclusion>
      <groupId>se.idsec.signservice.integration</groupId>
      <artifactId>signservice-integration-impl</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Note: The exclusion of the implicit dependency to signservice-integration-impl and replacing it with an explicit dependency is a good practice, especially if an update of signservice-integration-impl is available.

signservice-integration-pdf

Maven Central

If you want to support signing of PDF documents, you need the signservice-integration-pdf artifact.

<dependency>
  <groupId>se.idsec.signservice.integration</groupId>
  <artifactId>signservice-integration-pdf</artifactId>
  <version>${signservice-pdf.version}</version>
  <exclusions>
    <exclusion>
      <groupId>se.idsec.signservice.integration</groupId>
      <artifactId>signservice-integration-impl</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Note: The exclusion of the implicit dependency to signservice-integration-impl and replacing it with an explicit dependency is a good practice, especially if an update of signservice-integration-impl is available.

1.2. Java Documentation

Java API documentation, or javadoc, for the API, implementations and the commons libraries are available here:

Note: We will put together a site where all the javadoc above is merged together.

1.3. Design Principles

The interfaces and classes of the SignService Integration libraries are built with dependency injection in mind, and most classes are constructed as beans with setter and getters for class properties.

Yes. We are Spring Framework fanatics, but you can use the libraries without Spring as well. However, there are a few things that you need to be aware about.

1.3.1. PostConstruct Annotations

Some beans have methods, usually named afterPropertiesSet(), that are annotated with @PostConstruct. The PostConstruct annotation is a Java EE construct whose purpose is to indicate a method for bean initialization after the bean instance has been created and all its setters called. Spring, and some other framework supporting dependency injection, will invoke methods annotated with PostConstruct automatically, but if you are not using such a framework you need to remember to invoke these methods manually.

Suppose that we have the class Foo:

public class Foo {
  private Integer height;
  private Integer width;

  // setters and getters

  @PostConstruct
  public void afterPropertiesSet() throws Exception {
    if (this.height == null || this.width == null) {
      throw new IllegalArgumentException("Must height and width must be set");
    }
  }  

}

If you “manually” create an instance of Foo you should then invoke afterPropertiesSet yourself. The methods annotated with PostConstruct do not only assert that everything is assigned, but may also assign default values or initialize the bean in other ways. Therefore, don’t try to be clever and skip the afterProperties-invocation.

Foo bean = new Foo();
bean.setHeight(100);
bean.setWidth(200);
bean.afterProperties();

1.3.2. Use of Lombok

Writing code and documentation for setters, getters och sometimes for a builder is really boring. Even if we are not lazy we prefer to spend our time in writing high quality business logic instead. Therefore we make use of Lombok in many places.

So, you probably want to set up your Java IDE to use Lombok if you are using the SignService Integration libraries in any of your products. The Lombok setup guide will assist you.

1.3.3. Java Version Compatibility

All SignService libraries are built with Java 8. This means that no specific functionality from later Java releases are used. Of course, you can set up your project to use a later Java version.

1.3.4. Logging

All the SignService libraries use the Simple Logging Facade for Java (SLF4J).

So, if you use Java logging, log4j, logback or any other supported logging framework the logs from the SignService Integration libraries will be visible for you.

You have access to all source code so you’ll figure out which packages to configure for logging, but for those of you that are a bit lazy, here’s a brief listing:

2. Initializing the Library

The SignService Integration libraries use the Apache Santuario xmlsec library and OpenSAML to implement things like XML signing and validation, encryption of sign messages using a recipient key found in SAML metadata, and more.

Unfortunately, these libraries must be initialized, and to some extent configured. Therefore, the SignService Integration Service needs to be initialized the first thing when your application starts.

The class SignServiceIntegrationServiceInitializer offers a simple way to initalize all underlying libraries that needs initializing.

SignServiceIntegrationServiceInitializer defines two initializing methods:

If you are running in a environment that is according to the Swedish eID Framework you should pass in an instance of SwedishEidSecurityConfiguration. This configuration sets up the default algorithms according to chapter 8, “Cryptographic Algorithms”, of the Deployment Profile for the Swedish eID Framework.

2.1. Spring Boot Example

When running in a Spring Boot environment you can create a bean that initializes the SignService Integration library. But this bean really needs to be created before any other SignService Integration beans, so you would have to add a @DependentOn annotation just about everywhere.

A better solution is to create a Component and make sure it has the higest precedence (i.e., is created first). That way you can forget about dependent beans.

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class SignServiceIntegrationInitComponent {

  public SignServiceIntegrationInitComponent() throws Exception {
    SignServiceIntegrationServiceInitializer.initialize(
      new SwedishEidSecurityConfiguration());
  }
}

2.2. Initializing Manually

If you are not using a framework like Spring you need to make sure that the SignServiceIntegrationServiceInitializer.initialize call is made at application start up.

public class SignerApplication {

  public static void main(final String[] args) {
    try {
      SignServiceIntegrationServiceInitializer.initialize(
        new SwedishEidSecurityConfiguration());
    }
    catch (Exception e) {
      ... <report error>
    }
  }

}

Copyright © 2019-2023, IDsec Solutions AB. Licensed under version 2.0 of the Apache License.

This site is open source. Improve this page.