Pasexto.Paserk (pasexto v0.1.1)

PASERK is an extension to PASETO that provides key-wrapping and serialization.

PASERK supports the following purposes:

lid - Unique Identifier for a separate PASERK for local PASETOs.
local - Symmetric key for local tokens.
local_pw - Symmetric key wrapped using password-based encryption.
local_wrap - Symmetric key wrapped by another symmetric key.
pid - Unique Identifier for a separate PASERK for public PASETOs.
public - Public key for verifying public tokens.
seal - Symmetric key wrapped using asymmetric encryption.
secret - Secret key for signing public tokens.
secret_pw - Asymmetric secret key wrapped using password-based encryption.
secret_wrap - Asymmetric secret key wrapped by another symmetric key.
sid - Unique Identifier for a separate PASERK for public PASETOs.

A PASERK can be created like so:

iex> key = Pasexto.Key.new(:v4, :local)
iex> {:ok, paserk} = Pasexto.Paserk.build(:k4, :lid, key)

Summary

Types

kind()

purpose()

Functions

build(kind, purpose, key, opts \\ [])

Returns a PASERK for the given kind, purpose and key.

parse(kind, purpose, paserk, opts \\ [])

Parses a PASERK for the given kind and purpose.

Types

kind()

@type kind() :: :k1 | :k2 | :k3 | :k4

purpose()

@type purpose() ::
  :lid
  | :local
  | :local_pw
  | :local_wrap
  | :pid
  | :public
  | :seal
  | :secret
  | :secret_pw
  | :secret_wrap
  | :sid

Functions

build(kind, purpose, key, opts \\ [])

@spec build(kind(), purpose(), Pasexto.Key.t(), keyword()) ::
  {:ok, binary()} | {:error, term()}

Returns a PASERK for the given kind, purpose and key.

Some purposes require additional information to successfully build, these can be provided as options.

Options

password - A password for use with :local_pw and :secret_pw.
public_key - A public key for use with :seal.
- for v1 this must be a 4096-bit RSA public key.
- for v2 this must be a Ed25519 public key.
- for v3 this must be a P-384 public key.
- for v4 this must be a Ed25519 public key.
wrapper - A Pasexto.Wrapper for use with :local_wrap and :secret_wrap.

In addition to the above options :local_pw and :secret_pw also accept the following options for their key derivation functions:

iterations - defines how many iterations to perform, defaults to 100_000. Versions v1 and v3 only.
memory_cost - defines how much memory to use in bytes, defaults to 67_108_864. Versions v2 and v4 only.
parallelism_degree - defines the independent number of tasks, defaults to 1. Versions v2 and v4 only.
time_cost - defines the execution time as a number of iterations, defaults to 2. Versions v2 and v4 only.

parse(kind, purpose, paserk, opts \\ [])

@spec parse(kind(), purpose(), binary(), keyword()) ::
  {:ok, binary()} | {:error, term()}

Parses a PASERK for the given kind and purpose.

Some purposes require additional information to successfully build, these can be provided as options.

Options

password - A password for use with :local_pw and :secret_pw.
private_key - A private key for use with :seal.
- for v1 this must be a 4096-bit RSA private key.
- for v2 this must be a Ed25519 private key.
- for v3 this must be a P-384 private key.
- for v4 this must be a Ed25519 private key.
wrapper - A Pasexto.Wrapper for use with :local_wrap and :secret_wrap.

As :lid, :pid and :sid can only be serialised, trying to set this purpose will raise an argument error.