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.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="
}