ClearBank.Auth.Signer (ClearBank v1.0.0)

Copy Markdown View Source

Computes the DigitalSignature header value required by ClearBank for all POST / PATCH / PUT requests.

Algorithm

  1. UTF-8 encode the raw request body.
  2. SHA-256 digest the encoded body.
  3. Sign the digest with the RSA private key using PKCS#1 v1.5 padding.
  4. Base64-encode the resulting signature bytes.

The private key must be stored in a FIPS 140-2 level 2 compliant HSM in production. In simulation, any RSA key pair works.

Usage

body_json = Jason.encode!(payload)
pem_bin   = File.read!("/path/to/private.pem")

{:ok, signature} = ClearBank.Auth.Signer.sign(body_json, pem_bin)
# => "Base64EncodedSignature..."

Summary

Types

pem()
signature()

Functions

sign(body, pem_or_key)

Signs a request body and returns the Base64-encoded signature.

sign!(body, pem_or_key)

Like sign/2 but raises on failure.

verify(body, signature_b64, public_key_pem)

Verifies a DigitalSignature using ClearBank's public key. Used for verifying inbound webhook signatures.

Types

pem()

@type pem() :: binary()

signature()

@type signature() :: String.t()

Functions

sign(body, pem_or_key)

@spec sign(body :: iodata(), pem_or_key :: pem()) ::
  {:ok, signature()} | {:error, term()}

Signs a request body and returns the Base64-encoded signature.

Returns {:ok, signature} or {:error, reason}.

sign!(body, pem_or_key)

@spec sign!(body :: iodata(), pem_or_key :: pem()) :: signature()

Like sign/2 but raises on failure.

verify(body, signature_b64, public_key_pem)

@spec verify(body :: iodata(), signature_b64 :: String.t(), public_key_pem :: pem()) ::
  :ok | {:error, :invalid_signature | :bad_encoding}

Verifies a DigitalSignature using ClearBank's public key. Used for verifying inbound webhook signatures.

Returns :ok or {:error, :invalid_signature}.