JOSE v1.11.5

View Source JOSE.JWA (JOSE v1.11.5)

JWA stands for JSON Web Algorithms which is defined in RFC 7518.

cryptographic-algorithm-fallback

 Cryptographic Algorithm Fallback

Native implementations of all cryptographic and public key algorithms required by the JWA specifications are not present in current versions of Elixir and OTP.

JOSE will detect whether a specific algorithm is natively supported or not and, by default, it will mark the algorithm as unsupported if a native implementation is not found.

However, JOSE also has pure Erlang versions of many of the missing algorithms which can be used as a fallback by calling JOSE.crypto_fallback/1 and passing true.

Link to this section Summary

Functions

block_cipher(cipher)

Returns the current module and first argument for the specified cipher.

block_decrypt(cipher, key, cipher_text)

Decrypts cipher_text according to cipher block cipher.

block_decrypt(cipher, key, iv, cipher_text)

Decrypts cipher_text according to cipher block cipher.

block_encrypt(cipher, key, plain_text)

Encrypts plain_text according to cipher block cipher.

block_encrypt(cipher, key, iv, plain_text)

Encrypts plain_text according to cipher block cipher.

constant_time_compare(a, b)

Performs a constant time comparison between two binaries to help avoid timing attacks.

crypto_ciphers()

Returns the current block ciphers and their associated modules.

crypto_fallback()

See JOSE.crypto_fallback/0

crypto_fallback(boolean)

See JOSE.crypto_fallback/1

crypto_supports()

Returns the current listing of supported :crypto and :public_key algorithms.

decrypt_private(cipher_text, private_key, options)

Decrypts cipher_text using the private_key.

ec_key_mode()

Returns either :binary or :list depending on the detected runtime behavior for EC keys.

encrypt_public(plain_text, public_key, options)

Encrypts plain_text using the public_key.

is_block_cipher_supported(cipher)

Checks whether the cipher is natively supported by :crypto or not.

is_chacha20_poly1305_supported()

Checks whether ChaCha20/Poly1305 support is available or not.

is_rsa_crypt_supported(padding)

Checks whether the padding is natively supported by :public_key or not.

is_rsa_sign_supported(padding)

Checks whether the padding is natively supported by :public_key or not.

sign(message, digest_type, private_key, options)

Signs the digested message using the digest_type and private_key.

supports()

Returns the current listing of supported JOSE algorithms.

unsecured_signing()

See JOSE.unsecured_signing/0

unsecured_signing(boolean)

See JOSE.unsecured_signing/1

verify(message, digest_type, signature, public_key, options)

Verifies the signature with the digested message using the digest_type and public_key.

Link to this section Functions

Link to this function

block_cipher(cipher)

View Source

Returns the current module and first argument for the specified cipher.

iex> JOSE.JWA.block_cipher({:aes_cbc, 128})
{:crypto, :aes_cbc128}
iex> JOSE.JWA.block_cipher({:aes_cbc, 192})
{:jose_jwa_unsupported, {:aes_cbc, 192}}
iex> JOSE.crypto_fallback(true)
:ok
iex> JOSE.JWA.block_cipher({:aes_cbc, 192})
{:jose_jwa_aes, {:aes_cbc, 192}}
Link to this function

block_decrypt(cipher, key, cipher_text)

View Source

Decrypts cipher_text according to cipher block cipher.

Currently supported block ciphers:

  • {:aes_ecb, 128} - AES ECB with 128-bit key size
  • {:aes_ecb, 192} - AES ECB with 192-bit key size
  • {:aes_ecb, 256} - AES ECB with 256-bit key size
Link to this function

block_decrypt(cipher, key, iv, cipher_text)

View Source

Decrypts cipher_text according to cipher block cipher.

Currently supported block ciphers:

  • {:aes_cbc, 128} - AES CBC with 128-bit key size and 128-bit iv size
  • {:aes_cbc, 192} - AES CBC with 192-bit key size and 128-bit iv size
  • {:aes_cbc, 256} - AES CBC with 256-bit key size and 128-bit iv size
  • {:aes_gcm, 128} - AES GCM with 128-bit key size and variable iv size
  • {:aes_gcm, 192} - AES GCM with 192-bit key size and variable iv size
  • {:aes_gcm, 256} - AES GCM with 256-bit key size and variable iv size
  • {:chacha20_poly1305, 256} - ChaCha20/Poly1305 with 256-bit key size and 96-bit iv size
Link to this function

block_encrypt(cipher, key, plain_text)

View Source

Encrypts plain_text according to cipher block cipher.

Currently supported block ciphers:

  • {:aes_ecb, 128} - AES ECB with 128-bit key size
  • {:aes_ecb, 192} - AES ECB with 192-bit key size
  • {:aes_ecb, 256} - AES ECB with 256-bit key size
Link to this function

block_encrypt(cipher, key, iv, plain_text)

View Source

Encrypts plain_text according to cipher block cipher.

Currently supported block ciphers:

  • {:aes_cbc, 128} - AES CBC with 128-bit key size and 128-bit iv size
  • {:aes_cbc, 192} - AES CBC with 192-bit key size and 128-bit iv size
  • {:aes_cbc, 256} - AES CBC with 256-bit key size and 128-bit iv size
  • {:aes_gcm, 128} - AES GCM with 128-bit key size and variable iv size
  • {:aes_gcm, 192} - AES GCM with 192-bit key size and variable iv size
  • {:aes_gcm, 256} - AES GCM with 256-bit key size and variable iv size
  • {:chacha20_poly1305, 256} - ChaCha20/Poly1305 with 256-bit key size and 96-bit iv size
Link to this function

constant_time_compare(a, b)

View Source

Performs a constant time comparison between two binaries to help avoid timing attacks.

Link to this function

crypto_ciphers()

View Source

Returns the current block ciphers and their associated modules.

iex> JOSE.JWA.crypto_ciphers()
[{{:aes_cbc, 128}, :crypto}, {{:aes_cbc, 192}, :crypto},
 {{:aes_cbc, 256}, :crypto}, {{:aes_ecb, 128}, :crypto},
 {{:aes_ecb, 192}, :crypto}, {{:aes_ecb, 256}, :crypto},
 {{:aes_gcm, 128}, :crypto}, {{:aes_gcm, 192}, :crypto},
 {{:aes_gcm, 256}, :crypto},
 {{:chacha20_poly1305, 256}, :jose_chacha20_poly1305}]
Link to this function

crypto_fallback()

View Source

See JOSE.crypto_fallback/0

Link to this function

crypto_fallback(boolean)

View Source

See JOSE.crypto_fallback/1

Link to this function

crypto_supports()

View Source

Returns the current listing of supported :crypto and :public_key algorithms.

iex> JOSE.JWA.crypto_supports()
[ciphers: [aes_cbc: 128, aes_cbc: 192, aes_cbc: 256, aes_ecb: 128, aes_ecb: 192,
  aes_ecb: 256, aes_gcm: 128, aes_gcm: 192, aes_gcm: 256,
  chacha20_poly1305: 256],
 hashs: [:md5, :poly1305, :sha, :sha256, :sha384, :sha512, :shake256],
 public_keys: [:ec_gf2m, :ecdh, :ecdsa, :ed25519, :ed25519ph, :ed448, :ed448ph,
  :rsa, :x25519, :x448], rsa_crypt: [:rsa1_5, :rsa_oaep, :rsa_oaep_256],
 rsa_sign: [:rsa_pkcs1_padding, :rsa_pkcs1_pss_padding]]
Link to this function

decrypt_private(cipher_text, private_key, options)

View Source

Decrypts cipher_text using the private_key.

options

 Options

  • :rsa_padding - one of :rsa_pkcs1_oaep_padding or :rsa_pkcs1_padding
  • :rsa_oaep_md - sets the hashing algorithm for :rsa_pkcs1_oaep_padding, defaults to :sha
  • :rsa_oaep_label - sets the label for :rsa_pkcs1_oaep_padding, defaults to <<>>
Link to this function

ec_key_mode()

View Source

Returns either :binary or :list depending on the detected runtime behavior for EC keys.

Link to this function

encrypt_public(plain_text, public_key, options)

View Source

Encrypts plain_text using the public_key.

options

 Options

  • :rsa_padding - one of :rsa_pkcs1_oaep_padding or :rsa_pkcs1_padding
  • :rsa_oaep_md - sets the hashing algorithm for :rsa_pkcs1_oaep_padding, defaults to :sha
  • :rsa_oaep_label - sets the label for :rsa_pkcs1_oaep_padding, defaults to <<>>
Link to this function

is_block_cipher_supported(cipher)

View Source

Checks whether the cipher is natively supported by :crypto or not.

Link to this function

is_chacha20_poly1305_supported()

View Source

Checks whether ChaCha20/Poly1305 support is available or not.

Link to this function

is_rsa_crypt_supported(padding)

View Source

Checks whether the padding is natively supported by :public_key or not.

Link to this function

is_rsa_sign_supported(padding)

View Source

Checks whether the padding is natively supported by :public_key or not.

Link to this function

sign(message, digest_type, private_key, options)

View Source

Signs the digested message using the digest_type and private_key.

options

 Options

  • :rsa_padding - one of :rsa_pkcs1_pss_padding or :rsa_pkcs1_padding
  • :rsa_pss_saltlen - sets the salt length for :rsa_pkcs1_pss_padding, defaults to -1
    • -2 - use maximum for salt length
    • -1 - use hash length for salt length
    • any number higher than -1 is used as the actual salt length
Link to this function

supports()

View Source

Returns the current listing of supported JOSE algorithms.

iex> JOSE.JWA.supports()
[{:jwe,
  {:alg,
   ["A128GCMKW", "A128KW", "A192GCMKW", "A192KW", "A256GCMKW", "A256KW",
    "ECDH-ES", "ECDH-ES+A128KW", "ECDH-ES+A192KW", "ECDH-ES+A256KW",
    "PBES2-HS256+A128KW", "PBES2-HS384+A192KW", "PBES2-HS512+A256KW",
    "RSA-OAEP", "RSA-OAEP-256", "RSA1_5", "dir"]},
  {:enc,
   ["A128CBC-HS256", "A128GCM", "A192CBC-HS384", "A192GCM", "A256CBC-HS512",
    "A256GCM", "ChaCha20/Poly1305"]}, {:zip, ["DEF"]}},
 {:jwk, {:kty, ["EC", "OKP", "RSA", "oct"]},
  {:kty_OKP_crv,
   ["Ed25519", "Ed25519ph", "Ed448", "Ed448ph", "X25519", "X448"]}},
 {:jws,
  {:alg,
   ["ES256", "ES384", "ES512", "Ed25519", "Ed25519ph", "Ed448", "Ed448ph",
    "HS256", "HS384", "HS512", "PS256", "PS384", "PS512", "Poly1305", "RS256",
    "RS384", "RS512", "none"]}}]
Link to this function

unsecured_signing()

View Source

See JOSE.unsecured_signing/0

Link to this function

unsecured_signing(boolean)

View Source

See JOSE.unsecured_signing/1

Link to this function

verify(message, digest_type, signature, public_key, options)

View Source

Verifies the signature with the digested message using the digest_type and public_key.

options

 Options

  • :rsa_padding - one of :rsa_pkcs1_pss_padding or :rsa_pkcs1_padding
  • :rsa_pss_saltlen - sets the salt length for :rsa_pkcs1_pss_padding, defaults to -1
    • -2 - automatically determine based on the PSS block structure
    • -1 - use hash length for salt length
    • any number higher than -1 is used as the actual salt length