Signed Request Specification

The following describes the format for signed signature requests to be used with the Signed Request Authorizer. Signed signature requests can be created using the SignClient/signdocument or by following the format detailed below.

Signed Signature Request

The meaning of a Signed Signature Request here is a request intended for one of the workers in SignServer and which is protected by an extra request metadata field called SIGNED_REQUEST containing a signature in the format described here.

Format

The value of the SIGNED_REQUEST metadata property is a JSON Web Signature (JWS) in compact serialization and with a payload format as in JSON Web Token (JWT).

JWS Header Parameters

JWS Payload

The payload is a JSON object with keys and values.

A key is either a request field name or prefixed with "meta." followed by a request metadata key.

The value is the hash of the field or metadata value.

JWS Signature

Using algorithm declared in the JWS Header Parameter alg.

Algorithms

Signature algorithms should be using RSA or ECDSA and follow RFC 7518.

The digest algorithm used for hashing in the JWS Payload should be the same as the hash algorithm in the signature algorithm. For example, if ES256 (SHA256withECDSA) is used as signature algorithm then the hash algorithm SHA-256 should be used for every hash in the JWS Payload.

Signing

Follow the steps below to sign:

1. Construct a key-value map that will be used as the payload in the signature.
   
   1. To the map, add the key "data" with the value set to the hexadecimal encoded hash of the input data field or file upload.
   2. To the map, add the key "workerName" or "workerId" with the hexadecimal encoded hash of the string value of the workerName or workerId.
   3. If there is a filename provided with the request it must be included in the request metadata and added to the map the key "FILENAME" with the hexadecimal encoded hash of the string value of the file name.
   4. For each request metadata entry, to the map add the key from the metadata entry prefixed with "meta." and the value set to the hexadecimal encoded hash of the request metadata entry value.
2. Create and sign using JWS:
   1. Set the header parameter "typ" to "http://signserver.org/specs/signedrequest/1.0".
   2. Set the header parameter "x5c" to a list of base64 ( not base64url) encoded certificates making up the certificate chain with the end entity certificate first.
   3. Add the payload key-values with the same structure as JWT claims.
   4. Sign using the private key and use a signature algorithm allowed by the JWT specification.
   5. Finally, encode using JWS Compact Serialization.
3. Store the signature value in the request metadata as "SIGNED_REQUEST".

Verification

Follow the steps below to verify:

1. Extract the SIGNED_REQUEST request metadata property value or if missing fail.
2. Parse the JWS and fail if not signed.
3. Extract the certificate chain from the "x5c" header parameter.
4. Perform certificate chain validation and if required certificate revocation checks.
5. If the certificate was successfully validated and trusted, use the public key of the end entity certificate to verify the signature of the JWS, otherwise fail.
6. Verify that the header parameter "typ" has the value "http://signserver.org/specs/signedrequest/1.0", otherwise fail.
7. Extract the payload key-value pairs/claims.
8. For each key-value pair that starts with "meta." calculate the hash value for the corresponding request metadata property value and check that it is the same, otherwise fail.
9. For each request metadata property check that there is a corresponding key-value prefixed with "meta.". If it is FILENAME then compare its hash with the key-value FILENAME. If it is any other property that is missing, fail.
10. Check that if both FILENAME and meta.FILENAME are present they are the same, otherwise fail.
11. Check that if FILENAME is present in the key-values, its hash matches, otherwise fail.
12. If there is a workerName in the key-values, check that its hash matches the workerName in the request, otherwise fail.
13. If there is a workerId in the key-values, check that its hash matches the workerId in the request, otherwise fail.
14. Calculate the hash of the request data field or file upload and check that it equals the expected hash in the key-value pair "data", otherwise fail.

Examples

The following provides two examples of signed signature requests for signing a file and providing some request metadata, one example using the HTTP protocol and the other example using ClientWS protocol (SOAP/WS). 

Example 1 - Using HTTP Protocol

Example of a signed signature request for signing a file using HTTP protocol and providing some request metadata as well with the request.

SignClient Command

The "-nohttps" is only used here to more easily capture the request with Wireshark/tcpdump.

Full HTTP Request

Metadata Property

Decoded

Header:

Payload:

Example 2 - Using ClientWS Protocol

Example of a signed signature request for signing a file using ClientWS protocol (SOAP/WS) and providing some request metadata as well with the request.

SOAP Request

Data is a reference to a separate part of the HTTP request.

Decoded

Header:

Payload:

Sample Code

Java sample code for sending a signed signature request using ClientWS is available in the SignServer Enterprise sources under modules/mod-enterprise/SignServer--Sample-Clients module and called ClientWSWithSignedRequestSampleApp.java.