Joken v2.0.0-rc2 Joken.Signer View Source
Interface between Joken and JOSE for signing and verifying tokens.
Link to this section Summary
Types
A key may be an octet or a map with parameters according to JWK (JSON Web Key)
A Joken.Signer
instance is a JWS (JSON Web Signature) and JWK (JSON Web Key) struct
Functions
All supported algorithms
Creates a new Joken.Signer struct. Can accept either a binary for HS* algorithms or a map with arguments for the other kinds of keys
Generates a Joken.Signer from Joken’s application configuration
Signs a map of claims with the given Joken.Signer
Verifies the given token’s signature with the given Joken.Signer
Link to this section Types
A key may be an octet or a map with parameters according to JWK (JSON Web Key)
t() :: %Joken.Signer{ alg: binary() | nil, jwk: JOSE.JWK.t() | nil, jws: JOSE.JWS.t() | nil }
A Joken.Signer
instance is a JWS (JSON Web Signature) and JWK (JSON Web Key) struct.
It also contains an alg
field for performance reasons.
Link to this section Functions
All supported algorithms.
create(binary(), key(), %{optional(binary()) => term()}) :: Joken.Signer.t()
Creates a new Joken.Signer struct. Can accept either a binary for HS* algorithms or a map with arguments for the other kinds of keys.
Example:
iex> Joken.Signer.create("HS256", "s3cret")
%Joken.Signer{
alg: "HS256",
jwk: %JOSE.JWK{
fields: %{},
keys: :undefined,
kty: {:jose_jwk_kty_oct, "s3cret"}
},
jws: %JOSE.JWS{
alg: {:jose_jws_alg_hmac, :HS256},
b64: :undefined,
fields: %{"typ" => "JWT"}
}
}
parse_config(atom()) :: Joken.Signer.t() | nil
Generates a Joken.Signer from Joken’s application configuration.
A Joken.Signer has an algorithm (one of [“HS256”, “HS384”, “HS512”, “RS256”, “RS384”, “RS512”, “ES256”, “ES384”, “ES512”, “PS256”, “PS384”, “PS512”, “Ed25519”, “Ed25519ph”, “Ed448”, “Ed448ph”]) and a key.
There are several types of keys used by JWTs algorithms:
- RSA
- Elliptic Curve
- Octet (binary)
- So on…
Also, they can be encoded in several ways:
- Raw (map of parameters)
- PEM (Privacy Enhanced Mail format)
- Open SSH encoding
- So on…
To ease configuring these types of keys used by JWTs algorithms, Joken accepts a few parameters in its configuration:
- signer_alg : one of [“HS256”, “HS384”, “HS512”, “RS256”, “RS384”, “RS512”, “ES256”, “ES384”, “ES512”, “PS256”, “PS384”, “PS512”, “Ed25519”, “Ed25519ph”, “Ed448”, “Ed448ph”]
- key_pem : a binary containing a key in PEM encoding format
- key_openssh : a binary containing a key in Open SSH encoding format
- key_map : a map with the raw parameters
- key_octet : a binary used as the password for HS algorithms only
Examples
config :joken,
hs256: [
signer_alg: "HS256",
key_octet: "test"
]
config :joken,
rs256: [
signer_alg: "RS256",
key_pem: """
-----BEGIN RSA PRIVATE KEY-----
MIICWwIBAAKBgQDdlatRjRjogo3WojgGHFHYLugdUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQsHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5Do2kQ+X5xK9cipRgEKwIDAQABAoGAD+onAtVye4ic7VR7V50DF9bOnwRwNXrARcDhq9LWNRrRGElESYYTQ6EbatXS3MCyjjX2eMhu/aF5YhXBwkppwxg+EOmXeh+MzL7Zh284OuPbkglAaGhV9bb6/5CpuGb1esyPbYW+Ty2PC0GSZfIXkXs76jXAu9TOBvD0ybc2YlkCQQDywg2R/7t3Q2OE2+yo382CLJdrlSLVROWKwb4tb2PjhY4XAwV8d1vy0RenxTB+K5Mu57uVSTHtrMK0GAtFr833AkEA6avx20OHo61Yela/4k5kQDtjEf1N0LfI+BcWZtxsS3jDM3i1Hp0KSu5rsCPb8acJo5RO26gGVrfAsDcIXKC+bQJAZZ2XIpsitLyPpuiMOvBbzPavd4gY6Z8KWrfYzJoI/Q9FuBo6rKwl4BFoToD7WIUS+hpkagwWiz+6zLoX1dbOZwJACmH5fSSjAkLRi54PKJ8TFUeOP15h9sQzydI8zJU+upvDEKZsZc/UhT/SySDOxQ4G/523Y0sz/OZtSWcol/UMgQJALesy++GdvoIDLfJX5GBQpuFgFenRiRDabxrE9MNUZ2aPFaFp+DyAe+b4nDwuJaW2LURbr8AEZga7oQj0uYxcYw==
-----END RSA PRIVATE KEY-----
"""
]
sign(Joken.claims(), Joken.Signer.t()) :: {:ok, Joken.bearer_token()} | {:error, Joken.error_reason()}
Signs a map of claims with the given Joken.Signer.
Examples
iex> Joken.Signer.sign(%{"name" => "John Doe"}, Joken.Signer.create("HS256", "secret"))
{:ok, "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds"}
iex> Joken.Signer.sign(%{"name" => "John Doe"}, Joken.Signer.parse_config(:rs256))
{:ok, "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.e3hyn_oaaA2lxMlqH1UPo8STN-a_sszl8B2_s6tY9aT_YBAmfd7BXJOPsOMl7x2wXeKMQaNBVjna2tA0UiO_m3SpwiYgoTcU65D6OgkzugmLD_DhjDK1YCOKlm7So1uhbkb_QCuo4Ij5scsQqwv7hkxo4IximGBeH9LAvPhPTaGmYJMI7_tWIld2TlY6tNUQP4n0qctXsI3hjvGzdvuQW-tRnzAQCC4TYe-mJgFa033NSHeiX-sZB-SuYlWi7DJqDTiwlb_beVdqWpxxtFDA005Iw6FZTpH9Rs1LVwJU5t3RN5iWB-z4ZI-kKsGUGLNrAZ7btV6Ow2FMAdj9TXmNpQ"}
verify(Joken.bearer_token(), Joken.Signer.t()) :: Joken.claims() | {:error, Joken.error_reason()}
Verifies the given token’s signature with the given Joken.Signer
.
Examples
iex> Joken.Signer.verify("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds", Joken.Signer.create("HS256", "secret"))
{:ok, %{"name" => "John Doe"}}
iex> Joken.Signer.verify("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.e3hyn_oaaA2lxMlqH1UPo8STN-a_sszl8B2_s6tY9aT_YBAmfd7BXJOPsOMl7x2wXeKMQaNBVjna2tA0UiO_m3SpwiYgoTcU65D6OgkzugmLD_DhjDK1YCOKlm7So1uhbkb_QCuo4Ij5scsQqwv7hkxo4IximGBeH9LAvPhPTaGmYJMI7_tWIld2TlY6tNUQP4n0qctXsI3hjvGzdvuQW-tRnzAQCC4TYe-mJgFa033NSHeiX-sZB-SuYlWi7DJqDTiwlb_beVdqWpxxtFDA005Iw6FZTpH9Rs1LVwJU5t3RN5iWB-z4ZI-kKsGUGLNrAZ7btV6Ow2FMAdj9TXmNpQ", Joken.Signer.parse_config(:rs256))
{:ok, %{"name" => "John Doe"}}