JWT's with either symmetric (HMAC) or asymmetric (EDDSA) signatures. The default, simplest and most performant option is symmetric signatures (MAC), with the key derived from the Charon base secret.

Asymmetric tokens can be used when it is desirable for an external party to be able to verify a token's integrity, in which case distributing symmetric keys can be a hassle and a security risk.

keysets

Keysets

In order to sign and verify JWT's, a keyset is used. A keyset is a map of key ID's to keys. A key is a tuple of the signing algorithm and the actual secret(s). To simplify things and discourage key reuse, a key can only be used with a single signing algorithm. The default keyset looks like this, for example:

%{"default" => {:hmac_sha256, <<0, ...>>}}

Every token that is signed gets a "kid" claim in its header, allowing it to be verified with the specific key and algorithm that it was signed with.

key-cycling

Key cycling

It is possible to transition to a new signing key by adding a new key to the keyset and setting it as the new signing key using the :signing_key config option:

%{
  "default" => {:hmac_sha256, <<0, ...>>},
  "new!" => {:hmac_sha512, <<1, ...>>}
}

Older tokens will be verified using the older key, based on their "kid" header claim.

tokens-without-a-kid-header-claim

Tokens without a "kid" header claim

Legacy or external tokens may not have a "kid" header claim. Such tokens can still be verified by adding a "kid_not_set.<alg>" (for example "kid_not_set.HS256") key to the keyset.

symmetric-signatures

Symmetric signatures

Symmetric signatures are message authentication codes or MACs, either HMACs based on SHA256, 384 or 512, or a MAC generated using Blake3's keyed-hashing mode, which can be used directly without using a HMAC wrapper. Using Blake3 requires the optional dependency Blake3 and a key of exactly 256 bits.

By default, a SHA256-based HMAC is used.

asymmetric-signatures

Asymmetric signatures

Asymmetric signatures are created using EDDSA (Edwards-curve Digital Signature Algorithm) based on Curve25519 or Curve448. Use in JWTs is standardized (pending) in RFC 8073. These algorithms were chosen for performance and implementation ease, since they offer built-in protection against many side-channel (timing) attacks and are not susceptible to nonce-reuse (technically, they are, but not on the part of the implementation, which means they are safe to use in your PlayStation). Unless you are paranoid, use Curve25519, which offers about 128 bits of security. Curve448 offers about 224 bits, but is significantly slower.

In order to use asymmetric signatures, generate a key using gen_keypair/1. Create a publishable JWK using keypair_to_pub_jwk/1.

iex> keypair = Jwt.gen_keypair(:eddsa_ed25519)
iex> {:eddsa_ed25519, {_pubkey, _privkey}} = keypair
iex> %{"crv" => "Ed25519", "kty" => "OKP", "x" => <<_::binary>>} = Jwt.keypair_to_pub_jwk(keypair)

config

Config

Additional config is required for this module (see Charon.TokenFactory.Jwt.Config):

Charon.Config.from_enum(
  ...,
  optional_modules: %{
    Charon.TokenFactory.Jwt => %{
      get_keyset: fn -> %{"key1" => {:hmac_sha256, "my_key"}} end,
      signing_key: "key1"
    }
  }
)

The following options are supported:

• :get_keyset (optional, default default_keyset/1). The keyset used to sign and verify JWTs. If not specified, a default keyset with a single key called "default" is used, which is derived from Charon's base secret.
• :signing_key (optional, default "default"). The ID of the key in the keyset that is used to sign new tokens.

examples-doctests

Examples / doctests

# gracefully handles malformed tokens / unsupported algo's / invalid signature
iex> verify("a", @charon_config)
{:error, "malformed token"}
iex> verify("a.b.c", @charon_config)
{:error, "encoding invalid"}
iex> header = "notjson" |> url_encode()
iex> verify(header <> ".YQ.YQ", @charon_config)
{:error, "json invalid"}
iex> header = %{"missing" => "alg"} |> Jason.encode!() |> url_encode()
iex> verify(header <> ".YQ.YQ", @charon_config)
{:error, "malformed header"}
iex> header = %{"alg" => "boom"} |> Jason.encode!() |> url_encode()
iex> verify(header <> ".YQ.YQ", @charon_config)
{:error, "key not found"}
iex> header = %{"alg" => "HS256", "kid" => "default"} |> Jason.encode!() |> url_encode()
iex> verify(header <> ".YQ.YQ", @charon_config)
{:error, "signature invalid"}

# supports cycling to a new signing key, while still verifying old tokens
iex> {:ok, token} = sign(%{}, @charon_config)
iex> keyset = Jwt.default_keyset(@charon_config)
iex> keyset = Map.put(keyset, "ed25519_1", Jwt.gen_keypair(:eddsa_ed25519))
iex> config = override_opt_mod_conf(@charon_config, Jwt, get_keyset: fn _ -> keyset end, signing_key: "ed25519_1")
iex> {:ok, _} = verify(token, config)
iex> {:ok, new_token} = sign(%{}, config)
iex> new_token == token
false

# an old / external / legacy token without a "kid" claim can still be verified
# by adding a "kid_not_set.<alg>" key to the keyset
# a token MUST have an alg claim, which is mandatory according to the JWT spec
iex> [header, pl] = [%{"alg" => "HS256"}, %{}] |> Enum.map(&Jason.encode!/1) |> Enum.map(&url_encode/1)
iex> base = "#{header}.#{pl}"
iex> key = :crypto.strong_rand_bytes(32)
iex> signature = :crypto.mac(:hmac, :sha256, key, base) |> url_encode()
iex> token = "#{base}.#{signature}"
iex> {:error, "key not found"} = verify(token, @charon_config)
iex> keyset = %{"kid_not_set.HS256" => {:hmac_sha256, key}}
iex> config = override_opt_mod_conf(@charon_config, Jwt, get_keyset: fn _ -> keyset end)
iex> {:ok, _} = verify(token, config)