Powered by AppSignal & Oban Pro

Advanced: strict Ed25519

docs/notebooks/strict-crypto.livemd

Advanced: strict Ed25519

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.

Verify an honest signature, reject certified key-only forgeries and an out-of-range scalar, then compare protocol key acceptance with the stricter host enrollment subgroup check.

Rule S1 rejects noncanonical and small-order keys and signature points and requires S < L. It deliberately omits subgroup checking on the verification path. The host calls torsion_free?/1 at enrollment and trust installation. These checks establish neither trust nor authority. Generated keys stay in memory; corpus files are read from the installed package. No processes, tables, or files are created.

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 an honest primitive signature

Sign a fixed message with an ephemeral Ed25519 key. This primitive control needs no grant, holder proof, audience, or request context.

alias BoundedAuthorityProtocol.Ed25519

{public_key, private_key} = :crypto.generate_key(:eddsa, :ed25519)
message = "strict Ed25519 integration control"
signature = :crypto.sign(:eddsa, :none, message, [private_key, :ed25519])

%{public_key_bytes: byte_size(public_key), signature_bytes: byte_size(signature)}
%{public_key_bytes: 32, signature_bytes: 64}

Verify the honest signature and enrollment key

The generated key is canonical, acceptable, and torsion free. Strict verification also requires the signature equation to hold for this exact message.

true = Ed25519.acceptable_public_key?(public_key)
true = Ed25519.torsion_free?(public_key)
true = Ed25519.verify_strict(message, signature, public_key)

:honest_signature_verified
:honest_signature_verified

Load certified forgery controls

The shipped corpus supplies an identity-point key, its noncanonical encoding, and the key-only signature R = B, S = 1. The group order L is used for the scalar control.

# The prime order of the base point (specification § 14.1, RFC 8032):
l = 2 ** 252 + 27_742_317_777_372_353_535_851_937_790_883_648_493

# Corpus case key-only-v1-identity-a-basepoint-r-s1-0: R = B, then S = 1 (little-endian).
key_only_forgery =
  Base.decode16!(
    "5866666666666666666666666666666666666666666666666666666666666666" <>
      "0100000000000000000000000000000000000000000000000000000000000000",
    case: :lower
  )

# Corpus key small-order-0: the identity point, of order 1.
small_order_key =
  Base.decode16!("0100000000000000000000000000000000000000000000000000000000000000",
    case: :lower
  )

# Corpus key y-p-plus-1 (case key-only-v1-y-p-plus-1-prime-r-0): y = p + 1, a non-canonical
# encoding of the same identity point.
noncanonical_key =
  Base.decode16!("eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f",
    case: :lower
  )

:forgery_controls_loaded
:forgery_controls_loaded

Refuse key-only forgeries before the backend

The bare backend accepts the certified key-only signature under either identity encoding. Strict verification and key acceptance refuse both. A mathematically valid backend equation alone is not the protocol’s acceptance rule.

true = :crypto.verify(:eddsa, :none, message, key_only_forgery, [small_order_key, :ed25519])
true = :crypto.verify(:eddsa, :none, message, key_only_forgery, [noncanonical_key, :ed25519])

false = Ed25519.acceptable_public_key?(small_order_key)
false = Ed25519.acceptable_public_key?(noncanonical_key)
false = Ed25519.verify_strict(message, key_only_forgery, small_order_key)
false = Ed25519.verify_strict(message, key_only_forgery, noncanonical_key)

[:small_order_key, :noncanonical_key]
[:small_order_key, :noncanonical_key]

Refuse a scalar at or above the group order

Adding L to an honest S preserves its curve point. Strict verification and the backend both refuse the resulting noncanonical signature.

<<r::binary-size(32), s::little-size(256)>> = signature
s_plus_l_signature = r <> <<s + l::little-size(256)>>

false = Ed25519.verify_strict(message, s_plus_l_signature, public_key)
false = :crypto.verify(:eddsa, :none, message, s_plus_l_signature, [public_key, :ed25519])

:scalar_overflow_refused
:scalar_overflow_refused

Read the installed certified grant corpus

Read public conformance data from the package installation, not this checkout. The following steps use its complete signed controls to exercise verify_grant/3 as well as the primitives.

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

corpus_cases =
  :bounded_authority_protocol
  |> Application.app_dir(
    "priv/conformance/strict-ed25519/cases/grant-verify/grant-verify-01.json"
  )
  |> File.read!()
  |> JSON.decode!()
  |> Map.fetch!("cases")
  |> Map.new(&{&1["id"], &1["input"]})

:certified_corpus_loaded
:certified_corpus_loaded

Verify the honest corpus grant

Use the corpus’s explicit issuer key and expected context. This control establishes that the fixture path, decoding, and grant verification work before the refusal cases.

honest = Map.fetch!(corpus_cases, "grant-verify-v1-issuer-honest")

expected = %ExpectedGrant{
  issuer: honest["issuer"],
  audience: honest["audience"],
  evaluation_time: honest["evaluation_time"],
  clock_skew: honest["clock_skew"],
  bounds: %{}
}

trusted = %TrustedIssuer{
  key_id: honest["key_id"],
  public_key: Base.url_decode64!(honest["public_key"], padding: false)
}

{:ok, honest_facts} = V1.verify_grant(honest["compact"], trusted, expected)
Map.take(honest_facts, [:grant_id, :authorization])
%{grant_id: "urn:example:grant:1", authorization: :not_evaluated}

Refuse certified grant forgeries

Each case isolates a clause: a small-order key, a noncanonical key, a small-order signature point under an honest key, or an out-of-range scalar. All return the same closed error.

verify_case = fn id ->
  input = Map.fetch!(corpus_cases, id)

  key = %TrustedIssuer{
    key_id: input["key_id"],
    public_key: Base.url_decode64!(input["public_key"], padding: false)
  }

  context = %ExpectedGrant{
    issuer: input["issuer"],
    audience: input["audience"],
    evaluation_time: input["evaluation_time"],
    clock_skew: input["clock_skew"],
    bounds: %{}
  }

  V1.verify_grant(input["compact"], key, context)
end

{:error, :invalid} = verify_case.("grant-verify-v1-issuer-iso-small-order-a-1")
{:error, :invalid} = verify_case.("grant-verify-v1-issuer-iso-noncanonical-a-y-p-plus-0")
{:error, :invalid} = verify_case.("grant-verify-v1-issuer-honest-a-identity-r")
{:error, :invalid} = verify_case.("grant-verify-v1-issuer-s-plus-l")

[:small_order_key, :noncanonical_key, :identity_signature_point, :scalar_overflow]
[:small_order_key, :noncanonical_key, :identity_signature_point, :scalar_overflow]

Keep host enrollment stricter than verification

The mixed-torsion corpus key is acceptable under rule S1 and has a valid signature. It fails the host’s subgroup check, which prevents treating torsioned variants of one secret as independent identities at enrollment, trust install, and revocation comparison.

mixed = Map.fetch!(corpus_cases, "grant-verify-v1-issuer-mixed-a-mixed-r-both")
mixed_public = Base.url_decode64!(mixed["public_key"], padding: false)

mixed_expected = %ExpectedGrant{
  issuer: mixed["issuer"],
  audience: mixed["audience"],
  evaluation_time: mixed["evaluation_time"],
  clock_skew: mixed["clock_skew"],
  bounds: %{}
}

true = Ed25519.acceptable_public_key?(mixed_public)
false = Ed25519.torsion_free?(mixed_public)

{:ok, mixed_facts} =
  V1.verify_grant(
    mixed["compact"],
    %TrustedIssuer{key_id: mixed["key_id"], public_key: mixed_public},
    mixed_expected
  )

%{grant_id: mixed_facts.grant_id, protocol: :verified, enrollment: :refused}
%{grant_id: "urn:example:grant:1", protocol: :verified, enrollment: :refused}

See trusted keys and rotation and the strict Ed25519 rule for the host boundary.