# `SignCore.Algorithm`
[🔗](https://github.com/utaladriz/pkcs11ex/blob/v0.1.0/lib/sign_core/algorithm.ex#L1)

Behaviour for algorithm adapters.

Adapts a JOSE `alg` to a PKCS#11 mechanism, the wire signature encoding for
a given context (JOSE vs. X.509/CMS), and the canonical hash. See
`docs/specs/api.md` §2.1.

Implementations registered under `:algorithms` are accepted by the algorithm
allowlist; unknown atoms surface as `:unsupported_alg`.

# `alg`

```elixir
@type alg() :: atom()
```

# `encoding_context`

```elixir
@type encoding_context() :: :jose | :der
```

# `hash`

```elixir
@type hash() :: :sha256 | :sha384 | :sha512 | :none
```

# `key_type`

```elixir
@type key_type() :: :rsa | :ec | :ed25519
```

# `mechanism`

```elixir
@type mechanism() :: atom()
```

# `signature`

```elixir
@type signature() :: binary()
```

# `alg`

```elixir
@callback alg() :: alg()
```

The JOSE `alg` atom this adapter handles.

# `compatible_key_types`

```elixir
@callback compatible_key_types() :: [key_type(), ...]
```

Key types compatible with this algorithm.

# `decode_signature`

```elixir
@callback decode_signature(signature(), encoding_context()) ::
  {:ok, raw :: binary()} | {:error, term()}
```

Inverse of `encode_signature/2`. Used on verify to feed PKCS#11 the format
it expects.

# `encode_signature`

```elixir
@callback encode_signature(raw :: binary(), encoding_context()) ::
  {:ok, signature()} | {:error, term()}
```

Transform a raw PKCS#11 signature into the wire format required by the
given encoding context.

  * `:jose` — JWS / JOSE format (e.g., ES256 raw `r‖s`).
  * `:der`  — X.509 / CMS format (e.g., ES256 DER `SEQUENCE(r, s)`).

Most algorithms (PS256, RS256) are identity in both contexts.

# `hash`

```elixir
@callback hash() :: hash()
```

Canonical hash function for this algorithm.

# `signing_mechanism`

```elixir
@callback signing_mechanism() :: mechanism()
```

Atom describing the PKCS#11 mechanism used for signing.

The Rust bridge translates the atom into a `CK_MECHANISM` plus parameters.
Elixir never builds PKCS#11 binary structures directly.

# `verifying_mechanism`

```elixir
@callback verifying_mechanism() :: mechanism()
```

Atom describing the PKCS#11 mechanism used for verification.

# `builtins`

```elixir
@spec builtins() :: %{required(atom()) => module()}
```

The built-in algorithm registry.

# `lookup`

```elixir
@spec lookup(alg()) :: {:ok, module()} | {:error, :unsupported_alg}
```

Returns the algorithm-adapter module for an `alg` atom.

Looks up `Application.get_env(:pkcs11ex, :algorithms)` first, falling back
to the built-in registry. Returns `{:error, :unsupported_alg}` if the alg
is not registered.

---

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