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

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 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 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

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 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 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

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

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.

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(any)

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, any)

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(binary)

Converts a binary into a JOSE.JWK.

from_binary(password, binary)

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_key(key)

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

from_map(map)

Converts a map into a JOSE.JWK.

from_map(password, map)

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

from_oct(oct)

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

from_oct(password, oct)

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_pem(pem)

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

from_pem(password, pem)

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
  • "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 random bytes number of bytes
  • {:rsa, modulus_size} | {:rsa, modulus_size, exponent_size} - generates an "RSA" key using the modulus_size and exponent_size
sign(plain_text, jwk)

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.

thumbprint(jwk)

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

thumbprint(digest_type, jwk)

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(jwk)

Converts a JOSE.JWK into a binary.

to_binary(password, jwk)

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(jwk)

Converts a JOSE.JWK into the raw key format.

to_map(jwk)

Converts a JOSE.JWK into a map.

to_map(password, jwk)

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(jwk)

Converts a JOSE.JWK into a raw binary octet.

to_oct(password, jwk)

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_pem(jwk)

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

to_pem(password, jwk)

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(jwk)

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(jwk)

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

to_public_map(jwk)

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

to_record(j_w_k)

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

to_thumbprint_map(jwk)

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

verify(signed, jwk)

Verifies the signed using the jwk. See JOSE.JWS.verify/2.

verify_strict(signed, allow, jwk)

Verifies the signed using the jwk and whitelists the "alg" using allow. See JOSE.JWS.verify_strict/3.