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.