Validation gate

Add a pre-signing authorization step where your HTTP handler approves or rejects every DFNS signing request before it reaches the signers.

The validation gate is an optional feature for customers running signers on their own infrastructure. When enabled, the signer sends an HTTP request to an endpoint you control before performing a signature or key export. If your handler returns 200 OK, the operation proceeds. Any other response rejects it.

This gives you full control over which operations your signers are allowed to perform, based on your own business logic.

How it works

1. Signer receives a request

   A signing or key export request reaches the signer through the normal DFNS flow.

2. Signer calls your validation gate handler

   Before performing the operation, the signer sends an HTTP POST request with a JSON body to the URL you configured. The payload contains information about the operation (see Request payload below).

3. Your handler decides

   Your handler inspects the payload and returns:

   • 200 OK to approve the operation
   • Any other status code to reject it
4. Signer acts on the response

   If approved, the signer proceeds with the signing or key export. If rejected, the operation fails and the rejection is propagated back to the caller.

Request payload

Your handler receives a POST request with a JSON body.

signerInfo fields

The signerInfo object contains trusted information provided by the signer itself. These values are derived from the signer’s own state and are not user-supplied.

Field	Type	Description
kind	"Signing" or "KeyExport"	The type of operation being performed.
key_id	string	ID of the key being used.
public_key	string	Hex-encoded public key associated with the key.
tx_hash	string (optional)	Hex-encoded digest of the payload to be signed. Present for signing requests, absent for key exports.
derivation_path	array of numbers (optional)	HD derivation path, when the key uses hierarchical derivation.
child_public_key	string (optional)	Hex-encoded child public key derived from the master key using the derivation_path. Present only when derivation_path is set.

Examples

Signing request with HD derivation:

{
  "signerInfo": {
    "tx_hash": "a1b2c3d4e5f6...",
    "kind": "Signing",
    "key_id": "key-abc-123",
    "public_key": "04abcdef...",
    "derivation_path": [44, 60, 0, 0, 0],
    "child_public_key": "04fedcba..."
  }
}

Key export request:

{
  "signerInfo": {
    "kind": "KeyExport",
    "key_id": "key-abc-123",
    "public_key": "04abcdef..."
  }
}

Response handling

Your handler must return 200 OK to approve the operation. The signer treats any other response as a rejection:

Your handler returns	Signer behavior
200 OK	Operation approved. Signer proceeds.
400 Bad Request	Rejected. Treated as an authentication error.
401 Unauthorized	Rejected. Treated as an authentication error.
Any other non-200 status	Rejected. Treated as permission denied.
Connection failure	Rejected. Treated as an internal error.

When your handler rejects a request, return a meaningful response body. The signer includes it in the error message propagated to the caller.

Setup

The validation gate is configured as part of the signer deployment, through the signer’s command-line options:

Option	Description
--validation-gate-url	URL of your handler. Providing it enables the validation gate.
--validation-gate-secret	Shared secret (32 bytes, hex-encoded) used to sign each request body so your handler can verify the request comes from your signer.
--validation-gate-disable-tls	Explicitly disable TLS for the connection to your handler. Required if no validation gate TLS certificates are present in the signer’s key pack.

--validation-gate-secret and --validation-gate-disable-tls are only valid when --validation-gate-url is set.

Request authentication (HMAC)

When a shared secret is configured, the signer signs the raw request body with HMAC-SHA256 and sends the signature with each request:

Header	Value
x-payload-signature	Base64-encoded HMAC-SHA256 of the request body
x-payload-signature-type	hmac-sha256

Verify the signature in your handler before trusting the payload.

TLS

The TLS material for the connection to your handler is delivered in the signer’s key pack, created with the signer CLI’s make-pack subcommand:

make-pack option	Description
--validation-gate-tls-server-ca	CA certificate of your handler’s server certificate.
--validation-gate-tls-client-key	Dedicated client TLS key for authenticating to your handler.
--validation-gate-tls-client-cert	Dedicated client TLS certificate for authenticating to your handler.

Three modes are supported:

• mTLS: all three options are provided (server CA + client key + client certificate).
• TLS (no client authentication): only --validation-gate-tls-server-ca is provided.
• Disabled: no TLS material is provided, and --validation-gate-disable-tls is explicitly passed.

If the key pack contains no validation gate TLS certificates and --validation-gate-disable-tls is not set, the signer refuses to start.

Limitations

The validation gate is not compatible with ECDSA pre-signatures: when the gate is enabled, signing requests that use a pre-signature are rejected, because the signer cannot provide the key’s identity to your handler for those requests.

For help configuring the validation gate in your deployment, contact our .