REST SAD Provider

The implementation class of the REST SAD Provider is:

com.czertainly.signserver.module.entrustsam.sad.RestSAMSadProvider

The following properties can be configured for the REST SAD Provider:

Property	Description	Default Value	Mandatory
SAD_PROVIDER_URL	URL to get the Signature Activation Data. The URL should implement REST interface of this provider.	NONE	YES
SAD_PROVIDER_AUTH_TYPE	Authorization type for the REST API. Supported values are: NONE BASIC TLS See information about the authentication properties below.	NONE	YES
SAD_PROVIDER_MAX_PARALLEL_CONNECTIONS	Number defining the maximum number of total pooled connections. Increasing this value can improve concurrency when multiple requests are executed in parallel.	20	NO
SAD_PROVIDER_MAX_CONNECTIONS_PER_ROUTE	Number defining the maximum number of pooled connections per route (per target host). Increasing this value can improve concurrency when multiple requests are executed in parallel.	15	NO
SAD_PROVIDER_CONNECTION_REQUEST_TIMEOUT	Number (in seconds) defining how long to wait for a connection to become available from the connection pool before timing out.	60	NO
SAD_PROVIDER_CONNECT_TIMEOUT	Number (in seconds) defining the maximum time to establish a TCP connection. This includes the time to complete the socket handshake.	5	NO
SAD_PROVIDER_SOCKET_TIMEOUT	Number (in seconds) defining the maximum period of inactivity when waiting for data on an established socket connection.	30	NO
SAD_PROVIDER_RESPONSE_TIMEOUT	Number (in seconds) defining the maximum total time to wait for the entire HTTP response once the request has been sent.	60	NO

Authorization types

BASIC

SAP_PROVIDER_AUTH_TYPE = BASIC needs additional properties to be configured, in particular:

Property	Description	Default Value	Mandatory
SAD_PROVIDER_USERNAME	Identification of the user.	NONE	Mandatory for SAD_PROVIDER_AUTH_TYPE = BASIC
SAD_PROVIDER_PASSWORD	Password for the username.	NONE	Mandatory for SAD_PROVIDER_AUTH_TYPE = BASIC
SAD_PROVIDER_ENABLE_PREEMPTIVE_AUTH	Enable preemptive authentication. If enabled, the client will send the authentication header without receiving a challenge from the server.	false	NO

TLS

SAP_PROVIDER_AUTH_TYPE = TLS authenticates based on client certificate provided and server identity (TLS mutual authentication). The following options are available for the configuration of TLS authentication:

Property	Description	Default Value	Mandatory
SAD_PROVIDER_KEYSTORE_FORMAT	Format of the keystore provided. Supported values are: CRYPTOTOKEN BASE64 FILE	NONE	Mandatory for SAD_PROVIDER_AUTH_TYPE = TLS
SAD_PROVIDER_KEYSTORE_ALIAS	Alias of the private key stored in the keystore.	NONE	Mandatory for SAD_PROVIDER_AUTH_TYPE = TLS
SAD_PROVIDER_KEYSTORE_INDEX	Index of the Crypto Token that is configured in OTHER_SIGNERS property.	NONE	Mandatory for SAD_PROVIDER_KEYSTORE_FORMAT = CRYPTOTOKEN
SAD_PROVIDER_KEYSTORE	Referring to the keystore content. See Keystore formats.	NONE	Mandatory for SAD_PROVIDER_KEYSTORE_FORMAT = BASE64, FILE
SAD_PROVIDER_KEYSTORE_TYPE	Type of the keystore. Supported values are: PKCS12 JKS	NONE	Mandatory for SAD_PROVIDER_KEYSTORE_FORMAT = BASE64, FILE
SAD_PROVIDER_KEYSTORE_PASSWORD	Password for the keystore.	NONE	Mandatory for SAD_PROVIDER_KEYSTORE_FORMAT = BASE64, FILE
SAD_PROVIDER_TRUSTSTORE	Referring to the truststore content. See Truststore formats.	NONE	NO
SAD_PROVIDER_TRUSTSTORE_FORMAT	Format of the truststore provided. Supported values are: PEM BASE64 FILE	NONE	Mandatory when SAD_PROVIDER_TRUSTSTORE provided
SAD_PROVIDER_TRUSTSTORE_TYPE	Type of the truststore. Supported values are: PKCS12 JKS	NONE	Mandatory for SAD_PROVIDER_TRUSTSTORE_FORMAT = BASE64, FILE
SAD_PROVIDER_TRUSTSTORE_PASSWORD	Password for the truststore.	NONE	Mandatory for SAD_PROVIDER_TRUSTSTORE_FORMAT = BASE64, FILE

Keystore formats

The supported values for SAD_PROVIDER_KEYSTORE_FORMAT are defined as:

• CRYPTOTOKEN - the keystore is provided as reference to other Crypto Token defined in the SignServer. It must be part of the OTHER_SIGNERS property
• BASE64 - The keystore is provided as Base64-encoded value that is part of the SAD_PROVIDER_KEYSTORE property
• FILE - The keystore is loaded from the filesystem and the absolute path for the keystore is expected to be provided as part of the SAD_PROVIDER_KEYSTORE property

Truststore formats

The supported values for SAD_PROVIDER_TRUSTSTORE_FORMAT are defined as:

• PEM - the truststore is provided as list of PEM-encoded certificates to be used as a trusted sources and is expected to be provided as part of the SAD_PROVIDER_TRUSTSTORE property
• BASE64 - The truststore is provided as Base64-encoded value that is part of the SAD_PROVIDER_TRUSTSTORE property
• FILE - The keystore is loaded from the filesystem and the absolute path for the keystore is expected to be provided as part of the SAD_PROVIDER_TRUSTSTORE property

OpenAPI Definition

warning

v2 implementation of the OpenAPI definition is mandatory to use batch signing. See Batch Signing for more information.

v1

openapi: 3.0.3
info:
  title: REST Signature SAP Provider
  version: v1
paths:
  /v1/sad/buildSad:
    post:
      operationId: buildSad
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildSadRequestDTO'
        required: true
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BuildSadResponseDTO'
components:
  schemas:
    BuildSadRequestDTO:
      type: object
      properties:
        userId:
          type: string
        keyId:
          type: string
        dtbs:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
    BuildSadResponseDTO:
      type: object
      properties:
        sad:
          type: string

v2

v2 API supports building Signature Activation Data for multiple data to be signed. It is mandatory to implement to support batch signing. See Batch Signing for more information.

openapi: 3.0.3
info:
  title: REST Signature SAP Provider
  version: v1
paths:
  /v2/sad/buildSad:
    post:
      operationId: buildSad
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildSadRequestDTO'
        required: true
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/BuildSadResponseDTO'
components:
  schemas:
    BuildSadRequestDTO:
      type: object
      properties:
        userId:
          type: string
        keyId:
          type: string
        dtbs:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties:
            type: string
    BuildSadResponseDTO:
      type: object
      properties:
        sad:
          type: string