Powered by AppSignal & Oban Pro

Contract-major 3 ES256 grants and proofs

docs/notebooks/es256-signing.livemd

Contract-major 3 ES256 grants and proofs

Download this .livemd file, open it in Livebook, and choose Open → Import from file, then Run all. Use Elixir 1.18 or later and OTP 27 or later with access to public Hex. No secrets or external services are needed.

Sign a compute-job grant and proof with P-256. Convert DER signatures to low-S raw form, verify the envelope, and refuse high-S signatures, another holder, and cross-major inputs.

The signer owns conversion and normalization; assembly refuses noncanonical signatures. The host supplies trusted public keys and context and owns replay, revocation, and the decision. The generated keys stay in memory; this notebook starts no services and creates no files.

Open this 1.1.0 release notebook. The launch opens this journey at its immutable release tag.

Setup

Install the exact published package. Fixed evaluation times keep the results reproducible; only safe semantic values are persisted, never keys, signatures, tokens, or nonces.

Mix.install([{:bounded_authority_protocol, "== 1.1.0"}])
:ok

Generate P-256 keys and convert signatures

OTP returns DER ECDSA signatures. Convert to raw r || s, normalize low S, and only then assemble a compact JWS. The holder thumbprint uses the EC JWK construction.

alias BoundedAuthorityProtocol.Es256
alias BoundedAuthorityProtocol.V3
alias BoundedAuthorityProtocol.V3.EcJwk

{es_issuer_public, es_issuer_private} = :crypto.generate_key(:ecdh, :prime256v1)
{es_holder_public, es_holder_private} = :crypto.generate_key(:ecdh, :prime256v1)

es256_sign = fn message, private_key ->
  der = :crypto.sign(:ecdsa, :sha256, message, [private_key, :prime256v1])
  {:ok, raw} = Es256.der_to_raw(der)
  {:ok, low_s} = Es256.normalize_low_s(raw)
  low_s
end

{:ok, es_holder_thumbprint} = EcJwk.public_key_thumbprint_raw(es_holder_public, %{})

now = 1_800_001_000
:es256_signer_ready
:es256_signer_ready

Build and sign the grant

The issuer permits a batch job using at most eight GPU hours. Contract-major 3 has its own producers and inherits the range selectors of contract-major 2.

es_grant = %V3.Grant{
  key_id: "es-issuer-1",
  issuer: "https://issuer.example",
  grant_id: "grant-2026-es-001",
  audiences: ["https://service.example"],
  issued_at: 1_800_000_000,
  not_before: 1_800_000_000,
  expires_at: 1_800_003_600,
  holder_thumbprint: es_holder_thumbprint,
  operations: [
    %V3.Operation{
      name: "start_job",
      selectors: [
        {:equals, ["job", "queue"], {:string, "batch"}},
        {:lte, ["job", "gpu_hours"], {:integer, 8}}
      ]
    }
  ]
}

{:ok, es_grant_input} = V3.grant_signing_input(es_grant, %{})

{:ok, es_grant_compact} =
  V3.assemble_compact(es_grant_input, es256_sign.(es_grant_input.message, es_issuer_private))

:grant_signed
:grant_signed

Build and sign the proof

Bind the job arguments and the exact grant bytes to this invocation. Only the low-S raw signature enters assembly.

es_arguments =
  {:object, [{"job", {:object, [{"queue", {:string, "batch"}}, {"gpu_hours", {:integer, 4}}]}}]}

es_proof = %V3.Proof{
  holder_public_key: es_holder_public,
  proof_id: "proof-2026-es-001",
  method: "POST",
  target_uri: "https://service.example/jobs",
  issued_at: now,
  nonce: nil,
  invocation_id: "7d444840-9dc0-11ed-a8fc-0242ac120004",
  operation: "start_job",
  grant_compact: es_grant_compact,
  cast_arguments: es_arguments
}

{:ok, es_proof_input} = V3.proof_signing_input(es_proof, %{})
es_proof_signature = es256_sign.(es_proof_input.message, es_holder_private)
{:ok, es_proof_compact} = V3.assemble_compact(es_proof_input, es_proof_signature)

:proof_signed
:proof_signed

Supply trusted keys and expected context

Use the shared expected-context structs from the contract-major 1 namespace. Select the contract-major 3 verifier explicitly; never probe profiles until one accepts.

alias BoundedAuthorityProtocol.V1.{Credentials, ExpectedGrant, ExpectedRequest, TrustedIssuer}

es_trusted = %TrustedIssuer{key_id: "es-issuer-1", public_key: es_issuer_public}
es_credentials = %Credentials{grant: es_grant_compact, proof: es_proof_compact}

es_expected = %ExpectedRequest{
  trusted_issuer: es_trusted,
  issuer: "https://issuer.example",
  audience: "https://service.example",
  method: "POST",
  target_uri: "https://service.example/jobs",
  invocation_id: "7d444840-9dc0-11ed-a8fc-0242ac120004",
  operation: "start_job",
  cast_arguments: es_arguments,
  evaluation_time: now,
  clock_skew: 60,
  proof_max_age: 300,
  nonce: :not_required,
  bounds: %{}
}

expected_grant = %ExpectedGrant{
  issuer: "https://issuer.example",
  audience: "https://service.example",
  evaluation_time: now,
  clock_skew: 60,
  bounds: %{}
}

:expected_context_ready
:expected_context_ready

Verify the grant and envelope

Both verifiers use only public keys. Show the version and operation while keeping random signatures and thumbprints out of persisted output.

{:ok, es_grant_facts} = V3.verify_grant(es_grant_compact, es_trusted, expected_grant)
{:ok, es_envelope_facts} = V3.check_envelope(es_credentials, es_expected)

%{
  grant: Map.take(es_grant_facts, [:version, :grant_id, :authorization]),
  envelope: Map.take(es_envelope_facts, [:operation, :authorization])
}
%{
  grant: %{version: 3, grant_id: "grant-2026-es-001", authorization: :not_evaluated},
  envelope: %{operation: "start_job", authorization: :not_evaluated}
}

Refuse the high-S twin

ECDSA also verifies (r, n - s) in the backend. Demonstrate that fact, recover the original low-S signature, and show that assembly and envelope verification both refuse the high-S twin.

# The P-256 group order (contract-major 3 specification § 3.2):
n = 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551

<<es_r::256, es_s::256>> = es_proof_signature
high_s_signature = <<es_r::256, n - es_s::256>>

high_s_proof =
  es_proof_input.message <> "." <> Base.url_encode64(high_s_signature, padding: false)

# The backend verifies DER, so frame the twin as a DER ECDSA-Sig-Value
# (SEQUENCE { INTEGER r, INTEGER s }; a leading zero byte keeps an INTEGER positive):
der_integer = fn integer ->
  bytes = :binary.encode_unsigned(integer)
  bytes = if :binary.first(bytes) >= 0x80, do: <<0>> <> bytes, else: bytes
  <<0x02, byte_size(bytes)>> <> bytes
end

high_s_body = der_integer.(es_r) <> der_integer.(n - es_s)
high_s_der = <<0x30, byte_size(high_s_body)>> <> high_s_body

true =
  :crypto.verify(:ecdsa, :sha256, es_proof_input.message, high_s_der, [
    es_holder_public,
    :prime256v1
  ])

{:ok, raw_twin} = Es256.der_to_raw(high_s_der)
{:ok, ^es_proof_signature} = Es256.normalize_low_s(raw_twin)
{:error, :invalid} = V3.assemble_compact(es_proof_input, high_s_signature)

{:error, :invalid} =
  V3.check_envelope(%{es_credentials | proof: high_s_proof}, es_expected)

:high_s_refused
:high_s_refused

Refuse another holder

This proof has a valid P-256 signature of its own, but the grant names a different holder thumbprint. Signature validity cannot replace holder binding.

{other_public, other_private} = :crypto.generate_key(:ecdh, :prime256v1)
{:ok, other_input} = V3.proof_signing_input(%{es_proof | holder_public_key: other_public}, %{})

{:ok, other_proof} =
  V3.assemble_compact(other_input, es256_sign.(other_input.message, other_private))

{:error, :invalid} =
  V3.check_envelope(%{es_credentials | proof: other_proof}, es_expected)
{:error, :invalid}

Refuse cross-major bytes

First decode these bytes under their own contract-major. Contract-majors 1 and 2 must refuse both the grant and proof without attempting a fallback.

{:ok, _grant} = V3.decode_grant(es_grant_compact, %{})
{:ok, _proof} = V3.decode_proof(es_proof_compact, %{})
{:error, :invalid} = BoundedAuthorityProtocol.V1.decode_grant(es_grant_compact, %{})
{:error, :invalid} = BoundedAuthorityProtocol.V1.decode_proof(es_proof_compact, %{})
{:error, :invalid} = BoundedAuthorityProtocol.V2.decode_grant(es_grant_compact, %{})
{:error, :invalid} = BoundedAuthorityProtocol.V2.decode_proof(es_proof_compact, %{})

[:major_one_grant, :major_one_proof, :major_two_grant, :major_two_proof]
[:major_one_grant, :major_one_proof, :major_two_grant, :major_two_proof]

See choosing a profile and the ES256 specification for the suite and canonical signature rules.