Identity signing keys

​

Overview

• Keys belong to a single identity.
• An identity can have more than one key. A signature from any of them is accepted.
• The signature covers the exact operation, such as the amount and destination of a transfer, so it cannot be reused for a different one.

​

Example use cases

• End user approval on a phone. Your mobile app generates the key in the phone’s secure hardware and unlocks it with Face ID, a fingerprint, or a passcode. Each signature shows the end user started the operation on their own phone.
• A separate signing service. Your platform holds the key in a key management service (KMS), a hardware security module (HSM), or a secure enclave, apart from the systems that hold your API key. Funds movement then needs both your API key and a signature from that service.
• Keys held by end users. End users who run their own systems hold their own keys, and you register their public keys on their identities.

​

How enforcement works

​

Signed operations

​

Set up a signing key

{
  "kty": "EC",
  "crv": "P-256",
  "x": "zsgHUb5YXL9y_QBvIs8zeTXT6Ve0SzFvRheyI5MKk7Q",
  "y": "Jg3qIIYcSPl4g3Fmo3LmIWd-KFx0zkSnbc9sKeW9ojo"
}

curl -X POST https://api.prod.bastion.com/v2/identities/{identity_id}/signing-keys \
  -H "Authorization: Bearer bas_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": {
      "kty": "EC",
      "crv": "P-256",
      "x": "zsgHUb5YXL9y_QBvIs8zeTXT6Ve0SzFvRheyI5MKk7Q",
      "y": "Jg3qIIYcSPl4g3Fmo3LmIWd-KFx0zkSnbc9sKeW9ojo"
    },
    "label": "Payments signer (prod)"
  }'

curl -X POST https://api.prod.bastion.com/v2/crypto/transfers \
  -H "Authorization: Bearer bas_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "bastion-identity-signature: eyJhbGciOiJFUzI1NiIs...In0..PiJy4J5sm1JIQIse7D1h8iZ..." \
  -d '{ ... }'

​

Signature format

​

Example

import { createHash, generateKeyPairSync, sign } from 'node:crypto';

// 1. Generate a P-256 key pair. In production, generate it where it will sign.
const { publicKey, privateKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
const { kty, crv, x, y } = publicKey.export({ format: 'jwk' });
const publicJwk = { kty, crv, x, y }; // send this to Register Signing Key

// 2. The key ID is the RFC 7638 SHA-256 thumbprint of the public JWK.
const keyId = createHash('sha256')
  .update(JSON.stringify({ crv, kty, x, y }))
  .digest('base64url');

// 3. Serialize the intent with keys sorted at every level and no whitespace.
function canonicalJson(value) {
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
  if (value !== null && typeof value === 'object') {
    const keys = Object.keys(value).sort();
    return `{${keys.map((k) => `${canonicalJson(k)}:${canonicalJson(value[k])}`).join(',')}}`;
  }
  // Match Go's encoding/json, which escapes <, >, &, U+2028, and U+2029.
  return JSON.stringify(value).replace(
    /[<>&\u2028\u2029]/g,
    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`,
  );
}

// 4. Sign the intent and return a detached compact JWS (header..signature).
function signIntent(intent, privateKey, keyId) {
  const header = { alg: 'ES256', kid: keyId, 'bastion.com/iat': Math.floor(Date.now() / 1000) };
  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
  const encodedPayload = Buffer.from(canonicalJson(intent)).toString('base64url');
  const signature = sign('sha256', Buffer.from(`${encodedHeader}.${encodedPayload}`), {
    key: privateKey,
    dsaEncoding: 'ieee-p1363',
  });
  return `${encodedHeader}..${signature.toString('base64url')}`;
}

const intent = {
  action: 'crypto_transfer',
  request_id: '0b5e6c2a-3f1d-4a8e-9c7b-2d4f6a8b0c1e',
  account_id: '5f0c8a6e-2b7d-4c1a-9e3f-7a2b4c6d8e0f',
  currency_symbol: 'USDC',
  amount: '25.00',
  destination_address: '0x1234567890abcdef1234567890abcdef12345678',
  destination_chain: 'ETHEREUM_TESTNET',
};

console.log(signIntent(intent, privateKey, keyId)); // value for bastion-identity-signature

​

Signature encoding

// Convert a DER-encoded ECDSA P-256 signature to the 64-byte r || s form.
export function derToRawSignature(der) {
  const sig = Buffer.from(der);
  let offset = 2; // skip the SEQUENCE tag and length
  const readInt = () => {
    const len = sig[offset + 1];
    let int = sig.subarray(offset + 2, offset + 2 + len);
    offset += 2 + len;
    while (int.length > 32 && int[0] === 0) int = int.subarray(1); // drop sign padding
    return Buffer.concat([Buffer.alloc(32 - int.length), int]); // left-pad to 32 bytes
  };
  const r = readInt();
  const s = readInt();
  return Buffer.concat([r, s]);
}

​

Intent payloads

​

Serialization rules

• Keys sorted in byte order at every nesting level.
• No whitespace between tokens.
• Every field listed for the action is present. Fields marked omitted when empty are left out entirely when they have no value.
• Amounts are strings, exactly as sent in the request. "25.00" and "25" produce different signatures.
• Chains, currencies, payment methods, and other enums are the enum value names, as sent in the request (for example ETHEREUM_TESTNET, USDC, WIRE).
• The characters <, >, &, U+2028 (line separator), and U+2029 (paragraph separator) inside strings are escaped as \u003c, \u003e, \u0026, \u2028, and \u2029. JSON.stringify leaves them unescaped, so add this step if your JSON library does the same. Most intents never contain these characters, but free-text compliance fields can.

{"account_id":"5f0c8a6e-2b7d-4c1a-9e3f-7a2b4c6d8e0f","action":"crypto_transfer","amount":"25.00","currency_symbol":"USDC","destination_address":"0x1234567890abcdef1234567890abcdef12345678","destination_chain":"ETHEREUM_TESTNET","request_id":"0b5e6c2a-3f1d-4a8e-9c7b-2d4f6a8b0c1e"}

​

Fields by action

{
  "account_id": "...",
  "action": "conversion",
  "amount": "100",
  "destination": { "chain": "ETHEREUM_TESTNET", "currency": "USDC", "payment_method": "BLOCKCHAIN" },
  "request_id": "...",
  "source": { "currency": "USD", "payment_method": "WIRE" }
}

{
  "account_id": "...",
  "action": "conversion",
  "amount": "100",
  "destination": { "bank_account_id": "...", "currency": "MXN", "payment_method": "SPEI" },
  "quote_id": "...",
  "request_id": "...",
  "source": { "chain": "ETHEREUM_TESTNET", "currency": "USDC", "payment_method": "BLOCKCHAIN" }
}

​

Manage keys

• List keys: List Signing Keys returns the active keys for an identity.
• Remove a key: Delete Signing Key revokes a key right away. Signatures made with it stop working.
• Rotate a key: register the new key first, then delete the old one. The identity stays protected the whole time.
• Replace a lost or compromised key: register the new key, then delete the old one. If the end user holds the key, for example on a lost phone, confirm who they are through your own account recovery process before you register a new key.

​

Errors

​

Requests sent without a signature

{
  "code": "SIGNED_INTENT_REQUIRED",
  "message": "This identity requires a signed device intent for this operation.",
  "retryable": false
}

{
  "code": "IDENTITY_REQUIRES_SIGNING_KEY",
  "message": "This identity requires a signing key for this operation.",
  "retryable": false
}

​

All signature error codes

​

Best practices

• Show end users what they sign. When an end user approves a signature, show them the amount, currency, and destination from the intent.
• Keep the private key apart from your API key. If the same system holds both, an attacker who gets into it can sign requests too, and the key adds no protection.
• Sign right before sending. Signatures expire after 5 minutes.
• Reuse the signature for retries. Retrying with the same request_id and values reuses the same intent, so the same signature works while it is still valid.
• Test in sandbox. Signing works the same way in sandbox as in production.