REST Interface

The following covers information on the SignServer REST Interface.

API Overview

The SignServer REST Interface supports integration with SignServer over a RESTful Web Service.

In this initial version the API is limited to one flavor of the client operation for submitting a process (signing) request to SignServer. This is a more modern and RESTful alternative to the Client WS Interface and the Client HTTP Interface.

In future versions, the interface may be extended to support additional API calls from the other interfaces and/or add new ones.

Getting Started

The SignServer REST interface is described using the OpenAPI Specification (OAS). The OpenAPI Specification is a community-driven specification for describing REST APIs.

OpenAPI documents describe API services and are represented in YAML or JSON formats. These documents may be produced and served statically or generated dynamically from an application.

OpenAPI Document

The interface is documented in an OpenAPI document in YAML or JSON formats:

Document	JSON	YAML
SignServer REST Interface 1.2.1	openapi.json	openapi.yaml

Alternatively, you can also generate the document from a server running SignServer assuming that is enabled and supported by the application server.

Enabling MicroProfile OpenAPI in WildFly

Using JBoss CLI, enable the extension and subsystem, and then restart the application server:

/extension=org.wildfly.extension.microprofile.openapi-smallrye:add()
/subsystem=microprofile-openapi-smallrye:add()
reload

After restarting the application server and deploying SignServer, the OpenAPI document can be obtained from /signserver/openapi (for YAML format) or /signserver/openapi?format=JSON (for JSON format).

Integrating with the REST API

Resources

The SignServer REST API provides the following resource:

/rest/v1/workers

Methods

Each request requires a specified HTTP method.

Note that a numeric value for [idOrName] is treated by SignServer as a WorkerID. If the {idOrName} value is not numeric, SignServer will take it as a WorkerID.

Method	URL	Request Media Type	Request parameters	Response Media Type
POST	/rest/v1/workers/{idOrName}/process	application/json	data, metadata, encoding	application/json

Custom Header requires

The admin operations of the SignServer REST API requires a custom header called "X-Keyfactor-Requested-With" to accept the request. This protects SignServer REST endpoints from being maliciously invoked from administrator machines by clickjacking or CSRF methods.

Examples

The following provides examples of how to use the SignServer REST API.

Example - Sign Text with CMS Signer

The following provides an example of signing a sample text with the CMS Signer using the JSON request media type. This example assumes that you have a SignServer CMS Signer set up in SignServer.

Send a request to the CMS Signer using the worker name CMSSigner and use a JSON media type for sending the request in the body. The response is in JSON format and contains archiveId, data, requestId, and the signer certificate.

URL:

http://localhost:8080/signserver/rest/v1/workers/CMSSigner/process

Request Body:

{
  "metaData": {
    "additionalProp1": "value1",
    "additionalProp2": "value2",
    "additionalProp3": "value3"
  },
  "data": "Sample Data!"
}

Response:

{
   "archiveId": "bd83996d12787f6b11531b219c236803ea16ffd9",
   "data": "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",
   "requestId": "12345678",
   "signerCertificate": "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhcwDQYJKoZIhvcNAQELBQAwTDEWMBQGA1UEAwwNRFNTIFN1YiBDQSAxMTEQMA4GA1UECwwHVGVzdGluZzETMBEGA1UECgwKU2lnblNlcnZlcjELMAkGA1UEBhMCU0UwHhcNMTYwMzAzMDgyNTA0WhcNMzYwMjI3MDgyNTA0WjBKMRQwEgYDVQQDDAtzaWduZXIwMDAwMzEQMA4GA1UECwwHVGVzdGluZzETMBEGA1UECgwKU2lnblNlcnZlcjELMAkGA1UEBhMCU0UwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCyFKqwwiHS2o4PO3zovqC+jGuIELnja1iAlg/hyrRp28mF6BOGVaKE6ZzbQIMmmICRz+EeqXN1W8gyCEh6T2qN3QvXTAF9mrrUI3hG4Xn/Davgsln8saRE0zt45yy47dPq5YofYJWWIdW/6qssiX+ApcPqthCQfkgraUSagS/Reqy0WT/A2lwKh147GB9+MxhheskQIPaKQasOpI7vGfzey+GnkHPsfU21irS2nC8uzv6hd0G6hNYUEmJtIh9/5WebMoMiGFq1sydTtZp7pJilfPyxrAkHXEwMUEEMcVlE/ISCoKMttnLMUT/F00cHesU4D2yNl6gcSjpMj4Q/iF+hAgMBAAGjfzB9MB0GA1UdDgQWBBQ2/WY3Ln7tdUmDrTyvtvSZwBg8YzAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFBxgQUremK3l1gOK6GaCqX6w8gKHMA4GA1UdDwEB/wQEAwIF4DAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwQwDQYJKoZIhvcNAQELBQADggEBAIUh6kkCMc0Fs6U+Sw6Ns0Yd28Fb5SM//nE6mq3mf1SD4lAyChVrFvlqMZJaqeJlkVeHc9E+KCE5bX1r2iGC8rnE9DuItI0pKMrgFt4cbSbDwgovnTrkiIhuqP2pjdhmrHtlLqZBR8e16c4xGSn6XWKJ8vPzx2AJl7MY3sY3Z4aPckBFNjG1lzH1inq5WM/+WaLghOQQngaXeU+SWpoAM7cUjB8Uyjf2Qr2GerI4AZZJMuC6BuvMdFMyXX78l7c9qmvK9Bre+SFKdtcMAgnglLzu0lyPHPwYL0R+pwc5dFOJipafxeqeHGpkZTXMsdMn6f1USRznlGbRWru68/XOOFU="
}