View Source Asymmetric cryptography signers

It is common to divide cryptography in three categories:

Symmetric cryptography (also called symmetric-key algorithms):
- Clear text is passed to an algorithm that uses a key for encrypting and decrypting to generate cipher text;
- Examples include: AES (Advanced Encryption Standard), Blowfish, DES (Data Encryption Standard), etc;
- In the BEAM ecosystem, it is represented by the :crypto.supports()[:ciphers].
Asymmetric cryptography (also called public-key cryptography):
- It uses a pair of keys where one is private (only known to the owner) and the other is public;
- Clear text is passed to an algorithm plus the private key and generates a cipher text;
- The cipher text can be verified by the public key, that is, we can check that it was generated by the private key.
Hash cryptography (also called one-way functions):
- Clear text is passed to a function that may or may not receive a key to generate irreversible cipher text.

In the JWA specification we have algorithms that use both symmetric and asymmetric cryptography functions. Let's see them (taken from the specification):

-------	-------------------------------	--------------
HS256	HMAC using SHA-256	Required
HS384	HMAC using SHA-384	Optional
HS512	HMAC using SHA-512	Optional
RS256	RSASSA-PKCS1-v1_5 using	Recommended
	SHA-256
RS384	RSASSA-PKCS1-v1_5 using	Optional
	SHA-384
RS512	RSASSA-PKCS1-v1_5 using	Optional
	SHA-512
ES256	ECDSA using P-256 and SHA-256	Recommended+
ES384	ECDSA using P-384 and SHA-384	Optional
ES512	ECDSA using P-521 and SHA-512	Optional
PS256	RSASSA-PSS using SHA-256 and	Optional
	MGF1 with SHA-256
PS384	RSASSA-PSS using SHA-384 and	Optional
	MGF1 with SHA-384
PS512	RSASSA-PSS using SHA-512 and	Optional
	MGF1 with SHA-512
-------	-------------------------------	--------------

(removed the none algorithm we don't support**)

Besides the HSxxx family of algorithms, all others use asymmetric cryptography.

using-asymmetric-algorithms
Using asymmetric algorithms

What is nice about public-key cryptography is that you don't need to "share a key" between parties. The one with the private key can generate tokens and publish his public key online so that anybody can check that token was generated by the owner of the private key.

In Joken that usually means a private key can be used to call Joken.encode_and_sign and Joken.verify. If only have the public key, then you can only call Joken.verify.

There are some specifications that use this: OpenID Connect being one very famous. It specifies that authentication servers must publish their keys in JWK (JSON Web Key) format on a public URL. Here are some examples:

Google: https://www.googleapis.com/oauth2/v3/certs
Microsoft: https://login.microsoftonline.com/common/discovery/v2.0/keys

We have a Joken Hook that can fetch these keys, turn them into signers and verify tokens. This is JokenJwks.

key-formats
KEY formats

Different algorithms use different key formats. For example, RSA is based on huge prime numbers arithmetic. Its keys contain data about these prime numbers and other variables in the RSA function specification.

Elliptic curve cryptography is based on elliptic curve arithmetic. Its keys represent the function that generates infinite points on a curve specification.

Because of those differences, we usually have a container for each key type. There is a specification for how to represent these keys in JSON format. That is the JSON Web Key specification. It has a JSON format for each type of key.

We recommend reading on the appendix examples for each type of key. Here is the appendix of the JSON Web Key specification with examples for public and private RSA and EC keys.

Let's see some examples on parsing asymmetric RSA keys with Joken:

rsxxx-keys
RSxxx keys

This algorithm uses the RSASSA-PKCS1-v1_5 that uses SHA2 hash algorithms. The base for this algorithm is the RSA public key standard. So, to use this algorithm we need a pair of RSA keys. There are many ways to generate these keys in different environments and is outside the scope of this library. Here is one of these ways just for an example:

➜  joken git:(main) openssl genrsa -out mykey.pem 4096
Generating RSA private key, 4096 bit long modulus (2 primes)
.............++++
...........................................................................................................++++

This will generate a private RSA key in PEM (privacy enhanced mail) format on a file named mykey.pem. With this key we can sign and verify a token signature.

To use it with Joken we can call one of the Joken.Signer.create variants:

With the RAW PEM contents:

signer = Joken.Signer.create("RS256", %{"pem" => pem_contents})

With the pem file in the configuration:

use Mix.Config

config :joken,
  my_rsa_key: [
    signer_alg: "RS256",
    key_pem: """
    -----BEGIN RSA PRIVATE KEY-----
    MIICWwIBAAKBg
    ...
    -----END RSA PRIVATE KEY-----
    """
  ]

signer = Joken.Signer.parse_config(:my_rsa_key)

With the key in JWK format:

# example of key parameters from https://tools.ietf.org/html/rfc7517#appendix-A.1
# This is for demonstration purposes. We don't allow those parameters in the map like
# "alg", "kid", "kty". Although they are part of the JWK Set specification.

key = %{
  "alg" => "RS256",
  "e" => "AQAB",
  "kid" => "2011-04-29",
  "kty" => "RSA",
  "n" => "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"
}

signer = Joken.Signer.create(key)

With the key in JWK format on the config:

use Mix.Config

config :joken,
  my_rsa_public_key: [
    signer_alg: "RS256",
    key_map: %{
      "alg" => "RS256",
      "e" => "AQAB",
      "kid" => "2011-04-29",
      "kty" => "RSA",
      "n" => "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"
    }
  ]

signer = Joken.Signer.parse_config(:my_rsa_public_key)

other-algorithms
Other algorithms

Joken has a test suite that runs all supported algorithms. Please have a look at other algorithms from our test suite.

Also, check :erlang-jose documentation about keys: https://github.com/potatosalad/erlang-jose/blob/master/examples/KEY-GENERATION.md

← Previous Page Signers

Next Page → Testing your app with Joken

Settings View Source Asymmetric cryptography signers

using-asymmetric-algorithms Using asymmetric algorithms

key-formats KEY formats

rsxxx-keys RSxxx keys

other-algorithms Other algorithms

View Source Asymmetric cryptography signers

using-asymmetric-algorithms
Using asymmetric algorithms

key-formats
KEY formats

rsxxx-keys
RSxxx keys

other-algorithms
Other algorithms