Attesto.Cose (Attesto v2.28.0)

Copy Markdown View Source

Minimal COSE helpers for ISO 18013-5 issuer authentication.

Issuer COSE_Sign1 verification supports ES256/P-256, ES384/P-384 and ES512/P-521, with :accepted_algs defaulting to ["ES256"]. Signing, detached device verification, and EC2 COSE_Key conversion remain ES256/P-256 only. This is not general-purpose COSE.

RFC 9053 §2.1, Table 1 maps COSE -7/-35/-36 to SHA-256/384/512 and suggests, for example, "SHA-384 be used only with curve P-384". Attesto enforces all three recommended pairings strictly, returning :algorithm_key_mismatch before signature verification for a different EC curve. The raw ECDSA signature is two fixed-width integers: 32, 48 or 66 bytes each. P-521 therefore uses a 132-byte signature with SHA-512. See Attesto.Mdoc for ISO/IEC 18013-5 and HAIP requirements and the unsupported curves.

Summary

Functions

Map a JOSE signing algorithm name (such as "ES256") to its COSE algorithm integer.

Convert an EC2 P-256 COSE_Key map to a public JWK map.

Convert an EC P-256 public JWK to an EC2 P-256 COSE_Key map.

Maximum accepted CBOR payload size in bytes.

Decode and validate the protected and unprotected header maps of a COSE_Sign1 without verifying its signature.

Sign payload_bstr as an ES256 COSE_Sign1 and return its CBOR bytes.

Sign external_payload as an ES256 COSE_Sign1 with a detached (null) payload and return its CBOR bytes.

Verify an ECDSA COSE_Sign1 against a supplied public JWK or PEM.

Verify an ES256 COSE_Sign1 with a detached (null) payload against external_payload, supplied out of band by the caller.

Types

verify_error()

@type verify_error() ::
  :algorithm_key_mismatch
  | :invalid_cose
  | :invalid_key
  | :invalid_signature
  | :unsupported_algorithm
  | :unsupported_critical_header

Functions

alg_id(name)

@spec alg_id(term()) :: integer() | nil

Map a JOSE signing algorithm name (such as "ES256") to its COSE algorithm integer.

cose_to_key(arg1)

@spec cose_to_key(map()) :: map()

Convert an EC2 P-256 COSE_Key map to a public JWK map.

key_to_cose(public_jwk)

@spec key_to_cose(JOSE.JWK.t() | map()) :: map()

Convert an EC P-256 public JWK to an EC2 P-256 COSE_Key map.

max_cbor_bytes()

@spec max_cbor_bytes() :: pos_integer()

Maximum accepted CBOR payload size in bytes.

peek_headers(cose_sign1_bytes, opts \\ [])

@spec peek_headers(
  binary(),
  keyword()
) :: {:ok, map(), map()} | {:error, verify_error()}

Decode and validate the protected and unprotected header maps of a COSE_Sign1 without verifying its signature.

Pass allow_tagged: true to accept CBOR tag 18 (COSE_Sign1) in addition to an untagged four-element array.

sign1(pem, payload_bstr, opts)

@spec sign1(String.t(), binary(), keyword()) :: binary()

Sign payload_bstr as an ES256 COSE_Sign1 and return its CBOR bytes.

:x5chain may contain issuer-certificate DER binaries. Certificate-chain validation is outside this slice; the chain is carried in unprotected header label 33 for a verifier that implements that policy.

sign1_detached(pem, external_payload, opts)

@spec sign1_detached(String.t(), binary(), keyword()) :: binary()

Sign external_payload as an ES256 COSE_Sign1 with a detached (null) payload and return its CBOR bytes.

ISO 18013-5 DeviceSignature transmits its payload as null; the actual signed content (e.g. DeviceAuthenticationBytes) is reconstructed by both parties from context instead of being carried on the wire.

verify1(cose_sign1_bytes, jwk_or_pem, opts)

@spec verify1(binary(), JOSE.JWK.t() | map() | String.t(), keyword()) ::
  {:ok, binary()} | {:error, verify_error()}

Verify an ECDSA COSE_Sign1 against a supplied public JWK or PEM.

Returns the signed payload byte string without decoding it. :accepted_algs defaults to ["ES256"]; supported additional values are "ES384" and "ES512". A disallowed or unknown algorithm returns :unsupported_algorithm. A supported algorithm with a different EC curve returns :algorithm_key_mismatch, regardless of the acceptance policy.

verify1_detached(cose_sign1_bytes, external_payload, jwk_or_pem, opts)

@spec verify1_detached(
  binary(),
  binary(),
  JOSE.JWK.t() | map() | String.t(),
  keyword()
) ::
  :ok | {:error, verify_error()}

Verify an ES256 COSE_Sign1 with a detached (null) payload against external_payload, supplied out of band by the caller.

Returns :ok on success, since (unlike verify1/3) there is no embedded payload to hand back.