JOSE.JWK
JWK stands for JSON Web Key which is defined in RFC 7517.
Summary
Functions
Decrypts the encrypted
binary or map using the jwk
. See JOSE.JWE.block_decrypt/2
Encrypts the plain_text
using the jwk
and the default jwe
based on the key type. See block_encrypt/3
Encrypts the plain_text
using the jwk
and algorithms specified by the jwe
. See JOSE.JWE.block_encrypt/3
Key Agreement decryption of the encrypted
binary or map using my_private_jwk
. See box_encrypt/2
and JOSE.JWE.block_decrypt/2
Key Agreement encryption of plain_text
by generating an ephemeral private key based on other_public_jwk
curve. See box_encrypt/3
Key Agreement encryption of plain_text
using my_private_jwk
, other_public_jwk
, and the default jwe
based on the key types. See box_encrypt/4
Key Agreement encryption of plain_text
using my_private_jwk
, other_public_jwk
, and the algorithms specified by the jwe
Decrypts an encrypted binary or map into a JOSE.JWK
using the specified password
Converts a binary into a JOSE.JWK
Reads file and calls from_binary/1
to convert into a JOSE.JWK
Reads encrypted file and calls from_binary/2
to convert into a JOSE.JWK
using password
. See from/2
Converts Erlang records for :ECPrivateKey
, :ECPublicKey
, :RSAPrivateKey
, and :RSAPublicKey
into a JOSE.JWK
Converts a map into a JOSE.JWK
Converts an arbitrary binary into a JOSE.JWK
with "kty"
of "oct"
Reads file and calls from_oct/1
to convert into a JOSE.JWK
Reads encrypted file and calls from_oct/2
to convert into a JOSE.JWK
using password
. See from/2
Converts an octet key pair into a JOSE.JWK
with "kty"
of "OKP"
Converts an openssh key into a JOSE.JWK
with "kty"
of "OKP"
Reads file and calls from_openssh_key/1
to convert into a JOSE.JWK
Converts a PEM (Privacy Enhanced Email) binary into a JOSE.JWK
Decrypts an encrypted PEM (Privacy Enhanced Email) binary into a JOSE.JWK
using password
Reads file and calls from_oct/1
to convert into a JOSE.JWK
Reads encrypted file and calls from_pem/2
to convert into a JOSE.JWK
using password
Converts a :jose_jwk
record into a JOSE.JWK
Computes the shared secret between two keys. Currently only works for "EC"
keys and "OKP"
keys with "crv"
set to "X25519"
or "X448"
Signs the plain_text
using the jwk
and the default signer algorithm jws
for the key type. See sign/3
Signs the plain_text
using the jwk
and the algorithm specified by the jws
. See JOSE.JWS.sign/3
Returns the unique thumbprint for a JOSE.JWK
using the :sha256
digest type. See thumbprint/2
Returns the unique thumbprint for a JOSE.JWK
using the digest_type
Converts a JOSE.JWK
into a binary
Encrypts a JOSE.JWK
into a binary using password
and the default jwe
for the key type. See to_binary/3
Encrypts a JOSE.JWK
into a binary using password
and jwe
Calls to_binary/1
on a JOSE.JWK
and then writes the binary to file
Calls to_binary/2
on a JOSE.JWK
and then writes the encrypted binary to file
Calls to_binary/3
on a JOSE.JWK
and then writes the encrypted binary to file
Converts a JOSE.JWK
into the raw key format
Converts a JOSE.JWK
into a map
Encrypts a JOSE.JWK
into a map using password
and jwe
Converts a JOSE.JWK
into a raw binary octet
Encrypts a JOSE.JWK
into a raw binary octet using password
and jwe
Converts a JOSE.JWK
into an octet key pair
Converts a JOSE.JWK
into an OpenSSH key binary
Calls to_openssh_key/1
on a JOSE.JWK
and then writes the binary to file
Converts a JOSE.JWK
into a PEM (Privacy Enhanced Email) binary
Encrypts a JOSE.JWK
into a PEM (Privacy Enhanced Email) encrypted binary using password
Calls to_public/1
and then to_file/2
on a JOSE.JWK
Calls to_public/1
and then to_key/1
on a JOSE.JWK
Calls to_public/1
and then to_map/1
on a JOSE.JWK
Converts a JOSE.JWK
struct to a :jose_jwk
record
Converts a JOSE.JWK
into a map that can be used by thumbprint/1
and thumbprint/2
Verifies the signed
using the jwk
. See JOSE.JWS.verify/2
Verifies the signed
using the jwk
and whitelists the "alg"
using allow
. See JOSE.JWS.verify_strict/3
Types
t :: %JOSE.JWK{fields: term, keys: term, kty: term}
Functions
Decrypts the encrypted
binary or map using the jwk
. See JOSE.JWE.block_decrypt/2
.
Encrypts the plain_text
using the jwk
and the default jwe
based on the key type. See block_encrypt/3
.
Encrypts the plain_text
using the jwk
and algorithms specified by the jwe
. See JOSE.JWE.block_encrypt/3
.
Key Agreement decryption of the encrypted
binary or map using my_private_jwk
. See box_encrypt/2
and JOSE.JWE.block_decrypt/2
.
Key Agreement encryption of plain_text
by generating an ephemeral private key based on other_public_jwk
curve. See box_encrypt/3
.
# bob wants alice to send him a secret, so he first sends alice his public key:
bob_public_jwk = JOSE.JWK.from(%{"crv" => "P-256", "kty" => "EC",
"x" => "6pwDpICQ8JBWdvuLuXeWILAxSEUNB_BBAswikgYKKmY",
"y" => "fEHj1ehsIJ7PP-qon-oONl_J2yZLWpUncNRedZT7xqs"})
# alice uses bob's public key to generate an ephemeral private key used to encrypt the secret:
iex> {enc_alice2bob_tuple, alice_private_jwk} = JOSE.JWK.box_encrypt("secret", bob_public_jwk)
{{%{alg: :jose_jwe_alg_ecdh_es, enc: :jose_jwe_enc_aes},
%{"ciphertext" => "zcIIZLDB", "encrypted_key" => "",
"iv" => "9p8c7YJV5htz8zLI",
"protected" => "eyJhbGciOiJFQ0RILUVTIiwiYXB1IjoiaEhibEsxZlNWQ1FjTE5NQkpXMjB5Mko0VHMzcUhqR2c4ZDlocmFfc2QyZyIsImFwdiI6IlU4MkpJbFFNS0FWYWY5bXVwU0I2c0JERWpIQ1Qxdl9JU00xMUNsZHpVUGMiLCJlbmMiOiJBMTI4R0NNIiwiZXBrIjp7ImNydiI6IlAtMjU2Iiwia3R5IjoiRUMiLCJ4IjoiSUY3RTFza0hJMjBwQjRwbi0tMVZ4dVF4Vkl4Sjkzd21IaFl4VEp0VkZOVSIsInkiOiJiVDdidzdhRjVlM1hLNUh6YVM4MEFVbktKVGE2eWdYbkJDVDFxNERHSWNrIn19",
"tag" => "MHtfyNub8vG84ER0MPynuA"}},
%JOSE.JWK{fields: %{}, keys: :undefined,
kty: {:jose_jwk_kty_ec,
{:ECPrivateKey, 1,
<<138, 8, 179, 41, 203, 0, 127, 144, 178, 132, 66, 96, 50, 161, 103, 50, 4, 119, 71, 57, 63, 63, 33, 29, 69, 201, 182, 210, 106, 37, 196, 183>>,
{:namedCurve, {1, 2, 840, 10045, 3, 1, 7}},
<<4, 32, 94, 196, 214, 201, 7, 35, 109, 41, 7, 138, 103, 251, 237, 85, 198, 228, 49, 84, 140, 73, 247, 124, 38, 30, 22, 49, 76, 155, 85, 20, 213, 109, 62, 219, 195, 182, 133, 229, 237, 215, ...>>}}}}
# alice compacts the encrypted message and sends it to bob which contains alice's public key:
iex> enc_alice2bob_binary = JOSE.JWE.compact(enc_alice2bob_tuple) |> elem(1)
"eyJhbGciOiJFQ0RILUVTIiwiYXB1IjoiaEhibEsxZlNWQ1FjTE5NQkpXMjB5Mko0VHMzcUhqR2c4ZDlocmFfc2QyZyIsImFwdiI6IlU4MkpJbFFNS0FWYWY5bXVwU0I2c0JERWpIQ1Qxdl9JU00xMUNsZHpVUGMiLCJlbmMiOiJBMTI4R0NNIiwiZXBrIjp7ImNydiI6IlAtMjU2Iiwia3R5IjoiRUMiLCJ4IjoiSUY3RTFza0hJMjBwQjRwbi0tMVZ4dVF4Vkl4Sjkzd21IaFl4VEp0VkZOVSIsInkiOiJiVDdidzdhRjVlM1hLNUh6YVM4MEFVbktKVGE2eWdYbkJDVDFxNERHSWNrIn19..9p8c7YJV5htz8zLI.zcIIZLDB.MHtfyNub8vG84ER0MPynuA"
# bob can then decrypt the encrypted message using his private key:
bob_private_jwk = JOSE.JWK.from(%{"crv" => "P-256", "d" => "69sPu8znGIFuysKso-RemObfFs8bMBmkF0dfI1h6S1E",
"kty" => "EC", "x" => "6pwDpICQ8JBWdvuLuXeWILAxSEUNB_BBAswikgYKKmY",
"y" => "fEHj1ehsIJ7PP-qon-oONl_J2yZLWpUncNRedZT7xqs"})
iex> JOSE.JWK.box_decrypt(enc_alice2bob_binary, bob_private_jwk)
{"secret",
%JOSE.JWE{alg: {:jose_jwe_alg_ecdh_es,
{:jose_jwe_alg_ecdh_es,
{{{:ECPoint,
<<4, 32, 94, 196, 214, 201, 7, 35, 109, 41, 7, 138, 103, 251, 237, 85, 198, 228, 49, 84, 140, 73, 247, 124, 38, 30, 22, 49, 76, 155, 85, 20, 213, 109, 62, 219, 195, 182, 133, 229, 237, 215, ...>>},
{:namedCurve, {1, 2, 840, 10045, 3, 1, 7}}}, %{}},
<<132, 118, 229, 43, 87, 210, 84, 36, 28, 44, 211, 1, 37, 109, 180, 203, 98, 120, 78, 205, 234, 30, 49, 160, 241, 223, 97, 173, 175, 236, 119, 104>>,
<<83, 205, 137, 34, 84, 12, 40, 5, 90, 127, 217, 174, 165, 32, 122, 176, 16, 196, 140, 112, 147, 214, 255, 200, 72, 205, 117, 10, 87, 115, 80, 247>>,
:undefined}},
enc: {:jose_jwe_enc_aes,
{:jose_jwe_enc_aes, {:aes_gcm, 128}, 128, 16, 12, :undefined, :undefined,
:undefined, :undefined}}, fields: %{}, zip: :undefined}}
Key Agreement encryption of plain_text
using my_private_jwk
, other_public_jwk
, and the default jwe
based on the key types. See box_encrypt/4
.
Key Agreement encryption of plain_text
using my_private_jwk
, other_public_jwk
, and the algorithms specified by the jwe
.
# let's
Converts a binary or map into a JOSE.JWK
.
iex> JOSE.JWK.from(%{"k" => "", "kty" => "oct"})
%JOSE.JWK{fields: %{}, keys: :undefined, kty: {:jose_jwk_kty_oct, ""}}
iex> JOSE.JWK.from("{"k":"","kty":"oct"}")
%JOSE.JWK{fields: %{}, keys: :undefined, kty: {:jose_jwk_kty_oct, ""}}
The "kty"
field may be overridden with a custom module that implements the :jose_jwk
and :jose_jwk_kty
behaviours.
For example:
iex> JOSE.JWK.from({%{ kty: MyCustomKey }, %{ "kty" => "custom" }})
%JOSE.JWK{fields: %{}, keys: :undefined, kty: {MyCustomKey, :state}}
Decrypts an encrypted binary or map into a JOSE.JWK
using the specified password
.
iex> JOSE.JWK.from("password", "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkExMjhHQ00iLCJwMmMiOjQwOTYsInAycyI6Im5OQ1ZNQUktNTU5UVFtbWRFcnBsZFEifQ.Ucye69ii4dxd1ykNFlJyBVeA6xeNu4aV.2pZ4nBoxBjmdrneS.boqwdFZVNAFHk1M5P6kPYgBUgGwW32QuKzHuFA.wL9Hy6dcE_DPkUW9s5iwKA")
{%JOSE.JWE{alg: {:jose_jwe_alg_pbes2,
{:jose_jwe_alg_pbes2, :sha256, 128,
<<80, 66, 69, 83, 50, 45, 72, 83, 50, 53, 54, 43, 65, 49, 50, 56, 75, 87, 0, 156, 208, 149, 48, 2, 62, 231, 159, 80, 66, 105, 157, 18, 186, 101, 117>>,
4096}},
enc: {:jose_jwe_enc_aes,
{:jose_jwe_enc_aes, {:aes_gcm, 128}, 128, 16, 12, :undefined, :undefined,
:undefined, :undefined}}, fields: %{"cty" => "jwk+json"}, zip: :undefined},
%JOSE.JWK{fields: %{}, keys: :undefined, kty: {:jose_jwk_kty_oct, "secret"}}}
Converts a binary into a JOSE.JWK
.
Reads file and calls from_binary/1
to convert into a JOSE.JWK
.
Reads encrypted file and calls from_binary/2
to convert into a JOSE.JWK
using password
. See from/2
.
Converts Erlang records for :ECPrivateKey
, :ECPublicKey
, :RSAPrivateKey
, and :RSAPublicKey
into a JOSE.JWK
.
Converts a map into a JOSE.JWK
.
Converts an arbitrary binary into a JOSE.JWK
with "kty"
of "oct"
.
Decrypts an encrypted arbitrary binary into a JOSE.JWK
with "kty"
of "oct"
using password
. See from/2
.
Reads file and calls from_oct/1
to convert into a JOSE.JWK
.
Reads encrypted file and calls from_oct/2
to convert into a JOSE.JWK
using password
. See from/2
.
Converts an octet key pair into a JOSE.JWK
with "kty"
of "OKP"
.
Converts an openssh key into a JOSE.JWK
with "kty"
of "OKP"
.
Reads file and calls from_openssh_key/1
to convert into a JOSE.JWK
.
Converts a PEM (Privacy Enhanced Email) binary into a JOSE.JWK
.
Decrypts an encrypted PEM (Privacy Enhanced Email) binary into a JOSE.JWK
using password
.
Reads file and calls from_oct/1
to convert into a JOSE.JWK
.
Reads encrypted file and calls from_pem/2
to convert into a JOSE.JWK
using password
.
Converts a :jose_jwk
record into a JOSE.JWK
.
Generates a new JOSE.JWK
based on another JOSE.JWK
or from initialization params provided.
Passing another JOSE.JWK
results in different behavior depending on the "kty"
:
"EC"
- uses the same named curve to generate a new key"oct"
- uses the byte size to generate a new key"RSA"
- uses the same modulus and exponent sizes to generate a new key
The following initialization params may also be used:
{:ec, :secp256r1 | :secp384r1 | :secp521r1}
- generates an"EC"
key using the"P-256"
,"P-384"
, or"P-521"
curves{:oct, bytes}
- generates an"oct"
key made of a randombytes
number of bytes{:rsa, modulus_size} | {:rsa, modulus_size, exponent_size}
- generates an"RSA"
key using themodulus_size
andexponent_size
Signs the plain_text
using the jwk
and the default signer algorithm jws
for the key type. See sign/3
.
Signs the plain_text
using the jwk
and the algorithm specified by the jws
. See JOSE.JWS.sign/3
.
Returns the unique thumbprint for a JOSE.JWK
using the :sha256
digest type. See thumbprint/2
.
Returns the unique thumbprint for a JOSE.JWK
using the digest_type
.
# let's define two different keys that will have the same thumbprint
jwk1 = JOSE.JWK.from_oct("secret")
jwk2 = JOSE.JWK.from(%{ "use" => "sig", "k" => "c2VjcmV0", "kty" => "oct" })
iex> JOSE.JWK.thumbprint(jwk1)
"DWBh0SEIAPYh1x5uvot4z3AhaikHkxNJa3Ada2fT-Cg"
iex> JOSE.JWK.thumbprint(jwk2)
"DWBh0SEIAPYh1x5uvot4z3AhaikHkxNJa3Ada2fT-Cg"
iex> JOSE.JWK.thumbprint(:md5, jwk1)
"Kldz8k5PQm7y1E3aNBlMiA"
iex> JOSE.JWK.thumbprint(:md5, jwk2)
"Kldz8k5PQm7y1E3aNBlMiA"
See JSON Web Key (JWK) Thumbprint RFC 7638 for more information.
Converts a JOSE.JWK
into a binary.
Encrypts a JOSE.JWK
into a binary using password
and the default jwe
for the key type. See to_binary/3
.
Encrypts a JOSE.JWK
into a binary using password
and jwe
.
Calls to_binary/1
on a JOSE.JWK
and then writes the binary to file.
Calls to_binary/2
on a JOSE.JWK
and then writes the encrypted binary to file.
Calls to_binary/3
on a JOSE.JWK
and then writes the encrypted binary to file.
Converts a JOSE.JWK
into the raw key format.
Converts a JOSE.JWK
into a map.
Encrypts a JOSE.JWK
into a map using password
and jwe
.
Converts a JOSE.JWK
into a raw binary octet.
Encrypts a JOSE.JWK
into a raw binary octet using password
and the default jwe
for the key type. See to_oct/3
.
Encrypts a JOSE.JWK
into a raw binary octet using password
and jwe
.
Converts a JOSE.JWK
into an octet key pair.
Converts a JOSE.JWK
into an OpenSSH key binary.
Calls to_openssh_key/1
on a JOSE.JWK
and then writes the binary to file.
Converts a JOSE.JWK
into a PEM (Privacy Enhanced Email) binary.
Encrypts a JOSE.JWK
into a PEM (Privacy Enhanced Email) encrypted binary using password
.
Converts a private JOSE.JWK
into a public JOSE.JWK
.
iex> jwk_rsa = JOSE.JWK.generate_key({:rsa, 256})
%JOSE.JWK{fields: %{}, keys: :undefined,
kty: {:jose_jwk_kty_rsa,
{:RSAPrivateKey, :"two-prime",
89657271283923333213688956979801646886488725937927826421780028977595670900943,
65537,
49624301670095289515744590467755999498582844809776145284365095264133428741569,
336111124810514302695156165996294214367,
266748895426976520545002702829665062929,
329628611699439793965634256329704106687,
266443630200356088742496100410997365601,
145084675516165292189647528713269147163, :asn1_NOVALUE}}}
iex> JOSE.JWK.to_public(jwk_rsa)
%JOSE.JWK{fields: %{}, keys: :undefined,
kty: {:jose_jwk_kty_rsa,
{:RSAPublicKey,
89657271283923333213688956979801646886488725937927826421780028977595670900943,
65537}}}
Calls to_public/1
and then to_file/2
on a JOSE.JWK
.
Calls to_public/1
and then to_key/1
on a JOSE.JWK
.
Calls to_public/1
and then to_map/1
on a JOSE.JWK
.
Converts a JOSE.JWK
struct to a :jose_jwk
record.
Converts a JOSE.JWK
into a map that can be used by thumbprint/1
and thumbprint/2
.
Verifies the signed
using the jwk
. See JOSE.JWS.verify/2
.
Verifies the signed
using the jwk
and whitelists the "alg"
using allow
. See JOSE.JWS.verify_strict/3
.