Oasis.Token behaviour (oasis v0.5.2)

View Source

A simple wrapper of Plug.Crypto to provide a way to generate and verify bearer token for use in the bearer security scheme of the OpenAPI Specification.

When we use sign/2 and verify/2, the data stored in the token is signed to prevent tampering but not encrypted, in this scenario, we can store identification information (such as user NON-PII data), but SHOULD NOT be used to store confidential information (such as credit card numbers, PIN code).

  • "NON-PII" means Non Personally Identifiable Information.

If you don't want clients to be able to determine the value of the token, you may use encrypt/2 and decrypt/2 to generate and verify the token.

Callback

There are two callback functions reserved for use in the generated modules when we use the bearer security scheme of the OpenAPI Specification.

  • crypto_config/2, provides a way to define the crypto-related key information for the high level usage, it required to return an Oasis.Token.Crypto struct.
  • verify/3, an optional function to provide a way to custom the verification of the token, you may want to use encrypt/decrypt to the token, or other more rules to verify it.

Summary

Callbacks

Avoid using the application enviroment as the configuration mechanism for this library, and make crypto-related key information configurable when use bearer authentication.

An optional callback function to decode the original data from the token, and verify its integrity.

Functions

A wrapper of Plug.Crypto.decrypt/4 to use Oasis.Token.Crypto to decrypt the original data from the token and verify its integrity, please see Plug.Crypto.decrypt/4 for details.

A wrapper of Plug.Crypto.encrypt/4 to use Oasis.Token.Crypto to encode, encrypt and sign data into a token you can send to clients, please see Plug.Crypto.encrypt/4 for details.

Generates a random string in N length via :crypto.strong_rand_bytes/1.

A wrapper of Plug.Crypto.sign/4 to use Oasis.Token.Crypto to sign data into a token you can send to clients, please see Plug.Crypto.sign/4 for details.

A wrapper of Plug.Crypto.verify/4 to use Oasis.Token.Crypto to decode the original data from the token and verify its integrity, please see Plug.Crypto.verify/4 for details.

Types

opts()

@type opts() :: Plug.opts()

verify_error()

@type verify_error() :: {:error, :expired} | {:error, :invalid}

Callbacks

crypto_config(conn, opts)

@callback crypto_config(conn :: Plug.Conn.t(), opts :: Keyword.t()) ::
  Oasis.Token.Crypto.t()

Avoid using the application enviroment as the configuration mechanism for this library, and make crypto-related key information configurable when use bearer authentication.

The Oasis.Plug.BearerAuth module invokes this callback function to fetch a predefined Oasis.Token.Crypto struct, and then use it to verify the bearer token of the request.

verify(conn, token, opts)

(optional)
@callback verify(conn :: Plug.Conn.t(), token :: String.t(), opts()) ::
  {:ok, term()} | verify_error()

An optional callback function to decode the original data from the token, and verify its integrity.

If we use sign/2 to create a token, sign it, then provide it to a client application, the client will then use this token to authenticate requests for resources from the server, in this scenario, as a common use case, the Oasis.Plug.BearerAuth module uses verify/2 to finish the verification of the bearer token, so we do not need to implement this callback function in general.

But if we use encrypt/2 or other encryption methods to encode, encrypt, and sign data into a token and send to clients, we need to implement this callback function to custom the way to decrypt the token and verify its integrity.

Functions

decrypt(crypto, token)

A wrapper of Plug.Crypto.decrypt/4 to use Oasis.Token.Crypto to decrypt the original data from the token and verify its integrity, please see Plug.Crypto.decrypt/4 for details.

encrypt(crypto, data)

@spec encrypt(crypto :: Oasis.Token.Crypto.t(), data :: term()) :: String.t()

A wrapper of Plug.Crypto.encrypt/4 to use Oasis.Token.Crypto to encode, encrypt and sign data into a token you can send to clients, please see Plug.Crypto.encrypt/4 for details.

random_string(length)

@spec random_string(length :: non_neg_integer()) :: String.t()

Generates a random string in N length via :crypto.strong_rand_bytes/1.

sign(crypto, data)

@spec sign(crypto :: Oasis.Token.Crypto.t(), data :: term()) :: String.t()

A wrapper of Plug.Crypto.sign/4 to use Oasis.Token.Crypto to sign data into a token you can send to clients, please see Plug.Crypto.sign/4 for details.

verify(crypto, token)

@spec verify(crypto :: Oasis.Token.Crypto.t(), token :: String.t()) ::
  {:ok, term()} | {:error, term()}

A wrapper of Plug.Crypto.verify/4 to use Oasis.Token.Crypto to decode the original data from the token and verify its integrity, please see Plug.Crypto.verify/4 for details.