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.
[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.
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
Matching strings include:
Non-matching strings include:
If JWT is used, these routes should be as specific as possible to avoid accidentally exposing unintended routes.
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:
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.