# `Attesto.Cose`
[🔗](https://github.com/XukuLLC/attesto/blob/v2.1.0/lib/attesto/cose.ex#L2)

Minimal COSE helpers for ISO 18013-5 issuer authentication.

This slice supports `COSE_Sign1` with ES256 and EC2 P-256 `COSE_Key`
conversion. It intentionally does not implement general-purpose COSE.

# `verify_error`

```elixir
@type verify_error() ::
  :invalid_cose | :invalid_key | :invalid_signature | :unsupported_algorithm
```

# `cose_to_key`

```elixir
@spec cose_to_key(map()) :: map()
```

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

# `key_to_cose`

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

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

# `sign1`

```elixir
@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`

```elixir
@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`

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

Verify an ES256 `COSE_Sign1` against a supplied public JWK or PEM.

Returns the signed payload byte string without decoding it.

# `verify1_detached`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*