Client Signer

The API Client Signer enables you to programmatically complete signing requests and also manage the underlying cryptographic keys directly. When used with the API, it enables automated transaction signing workflows within your own environment.

Get started in 5 steps:

1. Enable API and get an API token
2. Enable and configure the Client Signer in MPCVault
3. Grant key access to the Client Signer
4. Deploy and run the Client Signer
5. Sign transactions via Client Signer

Step 1: Enable API and Get API token

Before using the Client Signer, you need an API token to interact with MPCVault.

1. Visit the MPCVault Web Console  and log in as your organization admin.
2. Navigate to the API page and click Create an APl user.
3. Fill in the required fields:
   • Name: Enter a unique name for the API user.
   • Permission: Select the vaults this API user can access.
   • IP whitelist: Specify one or more IPv4 or IPv6 CIDR ranges that are allowed to access the API.
4. Click Create to finish. The API token will be displayed once in a pop-up. Copy and store it securely, as it cannot be retrieved later.

Step 2: Enable and configure the Client Signer in MPCVault

Preparation

Generate an Ed25519 key pair for Client Signer authentication:

1. Open your terminal.
2. Paste the following text, replacing the key name:

   ssh-keygen -t ed25519 -C "[key_name]"

3. Choose a location to save the public and private keys.
4. Do not set a password when prompted.
5. Keep the private key secure, as you will need it in the next step.
6. Locate the generated public key file (usually ending in .pub) and copy its content. It should look like:

   ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q [key_name]

Enable

1. Visit your vault in the MPCVault Web Console  and open the Team & Tx policies page.
2. Click +New Client Signer to enter editing state.
3. In editing mode, click +New Client Signer again to add a new signer.
4. Enter the required info (including the public key from above) and click Continue.
5. After the pop-up window closes, click Confirm at the top right to submit the Vault setting update signing request.
6. Open the MPCVault app to approve the request.

Step 3: Grant key access to the Client Signer

After completing Step 2, a “Grant key access” signing request is generated automatically:

1. Approve and sign this request in the MPCVault app.
2. Once authorized, the Client Signer has access to vault keys and can perform signing operations.

Step 4: Deploy and run the Client Signer

The MPCVault Client Signer is distributed as a Docker image: ClienT Signer Docker Image 

1. Install Docker and pull image

   docker pull ghcr.io/mpcvault/client-signer:latest

2. Create config file

   Create a file named config.yml with your vault and signer settings, for example:

    
   http-health:
     listening-addr: localhost:8080 # Address to listen on for exposing health check endpoint
   vault-uuid: 350063e9-1234-1234-ae54-aaf939821815 # Your own vault UUID for signing
   ssh:
     private-key: | # Private key for your client signer (generated in Step 2)
       -----BEGIN OPENSSH PRIVATE KEY-----
       WJDmz0bAAAAkKYeHKWr/4fZWLsVWFAKERAAAkKYeHKWr/4fZWLsVWJDmz0bAAAAkKYeH
       WJDmz0bAAAAkKYeHKWr/4fZWLsVWJDmz0bAAAAkKYeHKWr/4fZWLsVWJDmz0bAAAAkKYeH
       WJDmz0bAAAAkKYeHKWr/4fZWLsVWJDmz0bAAAAkKYeHKWr/4fZWLsVWJDmz0bAAAAkKYeH
       njJbsYDOxrEym+WJDmz0bAAAAkKYeHKWr/4fZWLsVWJDmz0bAAAAkKYeHKWr/4fZWLsVWJ
       WJDmz0bAAAAkKYeHKWr/4fZWLsVWJDmz0bAAAAkKYeHKWr/4fZWLsVWJDmz0bAAAAkKYeH
       sP2Y3yL4H8Mz220w==
       -----END OPENSSH PRIVATE KEY-----
     password: "pass1234" # Password for the private key. Leave empty if there is no password
    
   callback-url: "http://host.docker.internal:8088/callback" # callback URL for the vault to call when getting a request to complete a signing request.
    

   Note: If you are calling back to your host. Your call back address should be:

   http://host.docker.internal:8088/callback

   This is because from the docker perspective, the host machine is at host.docker.internal as opposed to localhost. More info: StackOverflow: Docker host IP from inside container 

3. Start the Client Signer

   sudo docker run -it -p 8080:8080 {path to your config.yml}:/config.yml ghcr.io/mpcvault/client-signer --config-path=/config.yml
   

Step 5: Sign transactions via Client Signer

1. Implement a callback service

   Implement an HTTP callback service to handle signing approval requests triggered by ExecuteSigningRequests.

   • When you call ExecuteSigningRequests, the Client Signer sends a callback request to your callback endpoint.
   • The request body is a serialized protobuf SigningRequest.
   • Your service must respond with HTTP 200 to approve the signing request. Any non-200 response will reject it.
   • After the callback is approved, the ExecuteSigningRequests call completes and returns the signing response.

   Example callback handler in Go:

    
   func callback(sr *apipb.SigningRequest) error {
       srBytes, err := proto.Marshal(sr)
       if err != nil {
           return err
       }
    
       code, err := Post(callbackURL, srBytes, nil)
       if err != nil {
           return err
       }
    
       if code != http.StatusOK {
           return fmt.Errorf("callback status code: %v", code)
       }
    
       return nil
   }
    

2. Create and execute signing requests

   • Start your callback service before creating signing requests.
   • Create signing requests in your application and call ExecuteSigningRequests.
   • Each signing request will be sent to your callback service for approval.
   • After your callback service responds with HTTP 200, the Client Signer proceeds with signing and the API returns the signed transaction details.