# `Pasexto.Key`
[🔗](https://github.com/alexkornitzer/pasexto/blob/v0.1.2/lib/pasexto/key.ex#L1)

Keys are used to build and parse tokens, which are always scoped to a
specific PASETO version and purpose.

A Key can be created like so:

```elixir
iex> key = Pasexto.Key.new(:v4, :local)
```

If the key material has been created elsewhere it can be provided to
`Pasexto.Key.new/3`:

```elixir
iex> material = <<201, 3, 44, 87, 98, 136, 53, 5, 211, 173, 138, 220, 3, 167, 157,
  215, 185, 137, 185, 48, 48, 162, 235, 83, 44, 168, 166, 118, 59, 241, 154,
  117>>
iex> key = Pasexto.Key.new(:v4, :local, material)
```

# `material`

```elixir
@type material() :: term()
```

The key material.

# `purpose`

```elixir
@type purpose() :: :local | :public
```

The protocol purpose for the key.

# `t`

```elixir
@type t() :: %Pasexto.Key{
  material: material(),
  purpose: purpose(),
  version: version()
}
```

# `version`

```elixir
@type version() :: :v1 | :v2 | :v3 | :v4
```

The protocol version for the key.

# `extract`

```elixir
@spec extract(t(), version(), purpose()) ::
  {:ok, material()} | {:error, :invalid_purpose | :invalid_version}
```

Extracts the key material for a given protocol version and purpose.

Returns an error if the version or purpose do not match that of the key.

# `material_from_pem`

```elixir
@spec material_from_pem(
  binary(),
  keyword()
) :: material()
```

Returns key matrial from the provided PEM.

## Options

* `password` - The password for use with encrypted PEMs.

Raises an argument error if the PEM does not contain material that is valid
for PASETO protocols.

# `new`

```elixir
@spec new(version(), purpose(), material() | nil) :: t()
```

Returns a key for use with the given protocol version and purpose.

If the key material is not provided then new material will be made for the
selected protocol.

Raises an argument error if invalid key material is provided for a given
protocol.

---

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