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 OKto 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 aPOST request with a JSON body. The format depends on your signer version.
- MPC signer 2.24.5 and later
- MPC signer 2.24.3 and 2.24.4
- MPC signer before 2.24.3 or HSM Driver
The body holds two objects:Key export request:
The signer forwards
context as the platform declared it, without verifying it. operation is what the signer actually signs: check context against it before approving. If a signing request comes without context, the signer still calls your handler with operation alone.The body can also carry the top-level transaction, path, payload, userId and username fields of earlier versions. They are deprecated: use context.operation fieldscontext fieldscontext.signedContentcontext.userActionSigning request for a transfer:
Response handling
Your handler must return200 OK to approve the operation. The signer treats any other response as a rejection:
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:Shared secret (32 bytes, hex-encoded) used to sign each request body so your handler can verify the request comes from your signer.
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: 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’smake-pack subcommand:
Before MPC signer 2.24.5, these options are named --validation-gate-tls-server-ca, --validation-gate-tls-client-key and --validation-gate-tls-client-cert. The signer does not accept a key pack built with the old names: build a new one when you upgrade.
Three modes are supported:
- mTLS: all three options are provided (server CA + client key + client certificate).
- TLS (no client authentication): only
--validation-gate-server-tls-cais provided. - Disabled: no TLS material is provided, and
--validation-gate-disable-tlsis explicitly passed.
--validation-gate-disable-tls is not set, the signer refuses to start.