# Authentication

Usage of the Chronicle API can be protected using JWT, by setting the following configuration settings under the [api] table in config.toml.

• password_hash - The argon2 hash of your chosen password.
• password_salt - The salt used to hash the above password.
• identity_path - The path to an EdDSA secret key.
• jwt_expiration - The duration for which the JWT token is valid.
• public_routes - A list of routes that can be accessed without providing a token. These can include the wildcard (*) symbol to allow any sequence of characters to match.

The [api.argon_config] sub-table can be used to configure the argon2 hash generation, using the following settings:

• hash_length - The length of the resulting hash in bytes.
• parallelism - The number of threads used.
• mem_cost - The memory used.
• iterations - The number of iterations to perform.
• variant - One of three variants: argon2d, argon2i, or argon2id.
• version - The argon version (currently 0x13).

All JWT interactions should be performed via HTTPS.

## Public Routes​

When a route is configured to be public, it can be accessed freely without providing a JWT. Thus, you should take care when specifying these routes, as a mis-configured route can open the application up to attacks. The only accepted special character is the wildcard (*), which will be converted to a regex .* and match against the original URI.

For instance, a request GET https://localhost:XXXX/api/core/v2/milestones/by-index/10000 will check the set of public routes against the segment /api/core/v2/milestones/by-index/10000.

Matching strings include:

• /api/*
• /api/core/*/milestones/by-index/*
• *10000

Non-matching strings include:

• /core/v2/milestones/by-index/*
• /api/core/v2/milestones/by-index
• /api/core/v1/*

If JWT is used, these routes should be as specific as possible to avoid accidentally exposing unintended routes.

## Keys​

Chronicle uses an EdDSA secret key to create tokens, which can be generated by the application at startup or provided as an identity file using the identity_path config. Currently, this file must be a PKCS8 secret key (RFC 5208) PEM file. The location of this file can also optionally be specified using the IDENTITY_PATH env variable, which will be overridden by the config file value. If no such file is provided, a secret key is randomly generated for use while the application is running.

## Generating a Token​

A special route at the root (/login) is provided for generating a new token. This token will use the password config as well as the jwt_expiration and the secret key. This token can be manually generated by the client, if desired, by using the same identity and claims.

Static claims used by Chronicle are:

• iss: "chronicle"
• aud: "api"

The sub (subject) claim is filled using a unique UUID, however it is not currently stored or validated by Chronicle.

## Providing a Token​

To provide a token when making a request, include it in an Authorization header using the Bearer authentication scheme.