JOSE v1.8.4 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

Returns a block encryptor map for the key type

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

Converts a binary or map into a JOSE.JWK

Decrypts an encrypted binary or map into a JOSE.JWK using the specified password

Converts a binary into a JOSE.JWK

Decrypts an encrypted binary into a JOSE.JWK using password. See from/2

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 Firebase certificate public keys into a map of JOSE.JWK

Converts Erlang records for :ECPrivateKey, :ECPublicKey, :RSAPrivateKey, and :RSAPublicKey into a JOSE.JWK

Converts a map into a JOSE.JWK

Decrypts an encrypted map into a JOSE.JWK using password. See from/2

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

Merges map on right into map on left

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 a signer map for the key type

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 the default jwe for the key type. See to_map/3

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

Calls to_oct/1 on a JOSE.JWK and then writes the binary to file

Calls to_oct/2 on a JOSE.JWK and then writes the encrypted binary to file

Calls to_oct/3 on a JOSE.JWK and then writes the encrypted binary to file

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_pem/1 on a JOSE.JWK and then writes the binary to file

Calls to_pem/2 on a JOSE.JWK and then writes the encrypted binary to file

Converts a private JOSE.JWK into a public 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

Returns a verifier algorithm list for the key type

Verifies the signed using the jwk. See JOSE.JWS.verify_strict/3

Verifies the signed using the jwk and whitelists the "alg" using allow. See JOSE.JWS.verify/2

Types

t()
t() :: %JOSE.JWK{fields: term, keys: term, kty: term}

Functions

block_decrypt(encrypted, jwk)

Decrypts the encrypted binary or map using the jwk. See JOSE.JWE.block_decrypt/2.

block_encrypt(plain_text, jwk)

Encrypts the plain_text using the jwk and the default jwe based on the key type. See block_encrypt/3.

block_encrypt(plain_text, jwe, jwk)

Encrypts the plain_text using the jwk and algorithms specified by the jwe. See JOSE.JWE.block_encrypt/3.

block_encryptor(list)

Returns a block encryptor map for the key type.

box_decrypt(encrypted, my_private_jwk)

Key Agreement decryption of the encrypted binary or map using my_private_jwk. See box_encrypt/2 and JOSE.JWE.block_decrypt/2.

box_encrypt(plain_text, other_public_jwk)

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}}
box_encrypt(plain_text, other_public_jwk, my_private_jwk)

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.

box_encrypt(plain_text, jwe, other_public_jwk, my_private_jwk)

Key Agreement encryption of plain_text using my_private_jwk, other_public_jwk, and the algorithms specified by the jwe.

# let's 
from(list)

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}}
from(password, list)

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"}}}
from_binary(list)

Converts a binary into a JOSE.JWK.

from_binary(password, list)

Decrypts an encrypted binary into a JOSE.JWK using password. See from/2.

from_file(file)

Reads file and calls from_binary/1 to convert into a JOSE.JWK.

from_file(password, file)

Reads encrypted file and calls from_binary/2 to convert into a JOSE.JWK using password. See from/2.

from_firebase(any)

Converts Firebase certificate public keys into a map of JOSE.JWK.

from_key(list)

Converts Erlang records for :ECPrivateKey, :ECPublicKey, :RSAPrivateKey, and :RSAPublicKey into a JOSE.JWK.

from_map(list)

Converts a map into a JOSE.JWK.

from_map(password, list)

Decrypts an encrypted map into a JOSE.JWK using password. See from/2.

from_oct(list)

Converts an arbitrary binary into a JOSE.JWK with "kty" of "oct".

from_oct(password, list)

Decrypts an encrypted arbitrary binary into a JOSE.JWK with "kty" of "oct" using password. See from/2.

from_oct_file(file)

Reads file and calls from_oct/1 to convert into a JOSE.JWK.

from_oct_file(password, file)

Reads encrypted file and calls from_oct/2 to convert into a JOSE.JWK using password. See from/2.

from_okp(list)

Converts an octet key pair into a JOSE.JWK with "kty" of "OKP".

from_openssh_key(list)

Converts an openssh key into a JOSE.JWK with "kty" of "OKP".

from_openssh_key_file(file)

Reads file and calls from_openssh_key/1 to convert into a JOSE.JWK.

from_pem(list)

Converts a PEM (Privacy Enhanced Email) binary into a JOSE.JWK.

from_pem(password, list)

Decrypts an encrypted PEM (Privacy Enhanced Email) binary into a JOSE.JWK using password.

from_pem_file(file)

Reads file and calls from_oct/1 to convert into a JOSE.JWK.

from_pem_file(password, file)

Reads encrypted file and calls from_pem/2 to convert into a JOSE.JWK using password.

from_record(jose_jwk)

Converts a :jose_jwk record into a JOSE.JWK.

generate_key(parameters)

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
  • "OKP" - uses the same named curve 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, "P-256" | "P-384" | "P-521"} - generates an "EC" key using the "P-256", "P-384", or "P-521" curves
  • {:oct, bytes} - generates an "oct" key made of a random bytes number of bytes
  • {:okp, :Ed25519 | :Ed25519ph | :Ed448 | :Ed448ph | :X25519 | :X448} - generates an "OKP" key using the specified EdDSA or ECDH edwards curve
  • {:rsa, modulus_size} | {:rsa, modulus_size, exponent_size} - generates an "RSA" key using the modulus_size and exponent_size
merge(left, right)

Merges map on right into map on left.

shared_secret(your_jwk, my_jwk)

Computes the shared secret between two keys. Currently only works for "EC" keys and "OKP" keys with "crv" set to "X25519" or "X448".

sign(plain_text, key_list)

Signs the plain_text using the jwk and the default signer algorithm jws for the key type. See sign/3.

sign(plain_text, jws, jwk)

Signs the plain_text using the jwk and the algorithm specified by the jws. See JOSE.JWS.sign/3.

signer(list)

Returns a signer map for the key type.

thumbprint(list)

Returns the unique thumbprint for a JOSE.JWK using the :sha256 digest type. See thumbprint/2.

thumbprint(digest_type, list)

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.

to_binary(list)

Converts a JOSE.JWK into a binary.

to_binary(password, list)

Encrypts a JOSE.JWK into a binary using password and the default jwe for the key type. See to_binary/3.

to_binary(password, jwe, jwk)

Encrypts a JOSE.JWK into a binary using password and jwe.

to_file(file, jwk)

Calls to_binary/1 on a JOSE.JWK and then writes the binary to file.

to_file(password, file, jwk)

Calls to_binary/2 on a JOSE.JWK and then writes the encrypted binary to file.

to_file(password, file, jwe, jwk)

Calls to_binary/3 on a JOSE.JWK and then writes the encrypted binary to file.

to_key(list)

Converts a JOSE.JWK into the raw key format.

to_map(list)

Converts a JOSE.JWK into a map.

to_map(password, list)

Encrypts a JOSE.JWK into a map using password and the default jwe for the key type. See to_map/3.

to_map(password, jwe, jwk)

Encrypts a JOSE.JWK into a map using password and jwe.

to_oct(list)

Converts a JOSE.JWK into a raw binary octet.

to_oct(password, list)

Encrypts a JOSE.JWK into a raw binary octet using password and the default jwe for the key type. See to_oct/3.

to_oct(password, jwe, jwk)

Encrypts a JOSE.JWK into a raw binary octet using password and jwe.

to_oct_file(file, jwk)

Calls to_oct/1 on a JOSE.JWK and then writes the binary to file.

to_oct_file(password, file, jwk)

Calls to_oct/2 on a JOSE.JWK and then writes the encrypted binary to file.

to_oct_file(password, file, jwe, jwk)

Calls to_oct/3 on a JOSE.JWK and then writes the encrypted binary to file.

to_okp(list)

Converts a JOSE.JWK into an octet key pair.

to_openssh_key(list)

Converts a JOSE.JWK into an OpenSSH key binary.

to_openssh_key_file(file, jwk)

Calls to_openssh_key/1 on a JOSE.JWK and then writes the binary to file.

to_pem(list)

Converts a JOSE.JWK into a PEM (Privacy Enhanced Email) binary.

to_pem(password, list)

Encrypts a JOSE.JWK into a PEM (Privacy Enhanced Email) encrypted binary using password.

to_pem_file(file, jwk)

Calls to_pem/1 on a JOSE.JWK and then writes the binary to file.

to_pem_file(password, file, jwk)

Calls to_pem/2 on a JOSE.JWK and then writes the encrypted binary to file.

to_public(list)

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}}}
to_public_file(file, jwk)

Calls to_public/1 and then to_file/2 on a JOSE.JWK.

to_public_key(list)

Calls to_public/1 and then to_key/1 on a JOSE.JWK.

to_public_map(list)

Calls to_public/1 and then to_map/1 on a JOSE.JWK.

to_record(list)

Converts a JOSE.JWK struct to a :jose_jwk record.

to_thumbprint_map(list)

Converts a JOSE.JWK into a map that can be used by thumbprint/1 and thumbprint/2.

verifier(list)

Returns a verifier algorithm list for the key type.

verify(signed, jwk)

Verifies the signed using the jwk. See JOSE.JWS.verify_strict/3.

verify_strict(signed, allow, jwk)

Verifies the signed using the jwk and whitelists the "alg" using allow. See JOSE.JWS.verify/2.