A module containing core API:s and classes for the signature service. The module declares interfaces and classes for common structures, and also declares interfaces for the different SignService handlers.
The Signature Service Architectural Overview
describes the structure of a signature service, where an application comprises of one or several engines (one
per client), and where each engine is instantiated with a set of "handlers". The signservice-core module
declares interfaces for engines and handlers.
The SignServiceEngine interface describes the API for a specific SignService engine. It has the following methods:
SignServiceProcessingResult processRequest(HttpUserRequest, SignServiceContext)
The main entry point for a SignService Engine. The SignServiceEngineManager accepts HTTP user requests passed from the application/frontend, and after deciding which engine instance that can serve this request invokes this method to process the request. The engine will find out the type of message and process it accordingly.
Apart from processing requests, the engine may also serve resources. Examples of such resources are status pages and authentication provider metadata.
boolean canProcess(HttpUserRequest)
A predicate that given a request tells whether this engine instance can process the request.
This method will always be invoked by the application (i.e., the engine manager) before
processRequest is called.
The ProtocolHandler interface defines a handler that is responsible of parsing a SignRequest message to the internal request format, and to produce a SignResponse message.
Each protocol supported should have its own ProtocolHandler-implementation.
The ProtocolHandler has the following methods:
SignRequestMessage decodeRequest(HttpUserRequest, SignServiceContext)
Given a message (the HTTP user request) and the context the handler decodes the message into a SignRequestMessage instance (which is the internal, and protocol-agnostic, representation of a SignRequest message).
No validation of the message is performed, other than ensuring that a decode operation is possible.
SignResponseMessage createSignResponseMessage(SignServiceContext, SignRequestMessage)
A factory method that creates a SignResponseMessage given the context and the corresponding request message. The SignResponseMessage is the internal, and protocol-agnostic, representation of a SignResponse message.
Which parts of the SignResponseMessage that is populated is implementation dependent.
The caller of the method can now populate the response message based on the current operation.
HttpResponseAction encodeResponse(SignResponseMessage, SignServiceContext)
Encodes a response message so that it can be returned to the SignService application.
The AuthenticationHandler interface defines methods that are used to authenticate the user during the signature operation.
The handler interface supports authentication schemes that can authenticate the user "in one go" and schemes that require that the user is directed to a remote authentication service (IdP). Therefore there are two methods defined:
AuthenticationResultChoice authenticate(AuthnRequirements, SignMessage, SignServiceContext)
Initiates authentication of the user. Depending on the authentication scheme the return result object may contain the authentication result (assertion) or a request to direct the user to a remote service.
It is the responsibility of authenticate, or resumeAuthentication (see below), to assert that all
requirements from the supplied AuthnRequirements are fulfilled. This means that
the authentication must assert the supplied signer attributes and also check that the authentication is
performed under an accepted authentication context.
AuthenticationResultChoice resumeAuthentication(HttpUserRequest, SignServiceContext)
Resumes an authentication process. This method is invoked when the authentication scheme used leads to that the user is directed to an external authentication service (IdP). When the user returns to the client/service provider (the SignService application), the authentication process is resumed (and completed) by invoking this method.
The KeyAndCertificateHandler interface defines methods for generating the user signing credential, i.e., the private key and certificate.
void checkRequirements(SignRequestMessage, SignServiceContext)
Verifies that the requirements put in the supplied SignRequest is correct and the handler can process the request. If not an exception is thrown. The reason that this check exists is that the engine needs to ensure that a current request is correct before sending the user to authenticate. The user would be grumpy if he or she first authenticates and then getting an error message telling the operation failed. Better to detect any potential errors at an early phase.
PkiCredential generateSigningCredential(SignRequestMessage, IdentityAssertion, SignServiceContext)
Generates a signing (private) key and issues a signing certificate given the supplied parameters. The identity assertion is the result from the user's authentication.
This step involves interaction with a Certificate Authority (CA) in order to issue the user's signature certificate.
The SignatureHandler interface defines methods for producing the actual signature. The handler is activated when a user has authenticated and a user credential has been created.
CompletedSignatureTask sign(RequestedSignatureTask, PkiCredential, SignRequestMessage, SignServiceContext)
Signs the supplied signature task with the given signing credential. This method is invoked once per requested signature task (a SignRequest message may contain several "documents" to sign).
The AuditLogger interface defines methods for audit logging. Each engine will have its own instance of an audit logger. Normally, we wish to separate audit logs for different customers (clients/engines).
Audit logging is mainly performed from the engine implementation, but any handler can produce audit entries and have them logged via the AuditLoggerSingleton.
Configuring and setting up a Signature Service application requires that a huge amount of objects/beans are created.
Of course it is possible to do this "by hand" and create each handler and supply them with their respective settings.
However, this does not scale well, and in the end we would like to spin up an application just by supplying property
settings. Therefore, the signservice-core defines a framework for configuring SignService Handlers.
Each implementation of a handler must also define a corresponding configuration class and a factory that, based on the configuration, knows how create a handler instance.
The HandlerConfiguration interface defines common configuration settings. Implementing classes are expected to supply setters and getters for all properties that should be config-data for that specific type of configuration class.
The general idea is that a particular handler should always be "stand-alone", i.e., it should possible to create a
handler by manually assigning all of its required configuration data without the use of a
HandlerConfiguration data object. The HandlerConfiguration is intended to be used when SignService
handlers are configured, and created in an application from properties, or YML-files, for example using Spring Boot
or Quarkus.
Each class implementing the HandlerConfiguration must tell which HandlerFactory
class that understands its settings and can be used to create a handler based on the configuration.
The HandlerFactory interface defines create methods that based on a specific configuration
creates a handler instance.
Copyright © 2022-2023, Myndigheten för digital förvaltning - Swedish Agency for Digital Government (DIGG). Licensed under version 2.0 of the Apache License.