Configuration

Configuration data is stored in various JSON files in the data directory (~/.indie).

server-secret.json

{
    "serverSecret": "<server secret">
}

This file contains a secret.

  • Generated on first run of the app.
  • Never replaced/updated.
  • Used when signing JSON Web Tokens (JWTs)

Secret scope: The secret must be secret to clients connecting to the server. It is known to the web host hosting the Indie Site and to anyone who access to the server.

installer-secret.json (Optional)

{
    "secretSignUpCode": "<secret sign-up code>"
}

This file contains a secret.

This file is generated by the Magic Website Factory when an Indie Site instance is deployed by an Indie Site Installer (like Hallo.gent).

If this file exists, the secret sign-up code that it contains is used to authenticate calls when an Indie Site is not yet configured to control access to the configuration functionality. For more information, see Indie Site Deployment.

owner-keys.json

{
  "derivedKeySalt": "…",
  "encryptedPrivateSigningKeyNonce": "…",
  "encryptedPrivateSigningKey": "…",
  "publicSigningKey": "…"
}

This file does not contain any secrets.

Contains the following non-secret key information:

Derived key salt (derivedKeySalt)

The salt used for deriving a secret key from the site owner’s chosen password using the crypto_pwhash() function from the Sodium crypto library (libsodium). The key derivation algorithm used is the default libsodium algorithm (the Argon2 memory-hard function).

The key derivation happens on the client. Unless the host/server/source has been compromised, the host/server does not know what the site owner’s password is and does not have access to the private key that is derived from it.

The derived key is used is encrypt the owner’s private signing key. The encrypted private signing key can then be safely persisted on the server and communicated in the future to untrusted clients.

On first access from an untrusted client, the owner must enter their password to decrypt the encrypted private key. To derive the same key as before, we must use the same salt, the same algorithm, and the same values for the opslimit and memlimit properties (these are hard-coded in the source) that were originally used to create the derived key.

The salt should be unpredictable but it’s not a secret. (The purpose of the salt is to thwart an attacker’s ability to match passwords across services as the same password on two different services that use different salts will result in different derived keys. For more information, read up on rainbow tables).

Encrypted private signing key (encryptedPrivateSigningKey)

This is an encrypted copy of the site owner’s private signing key.

It is encrypted with the key derived from the site owner’s password using the crypto_secretbox_easy() function from the Sodium crypto library (libsodium).

This encrypted key can safely be stored on the server and communicated to untrusted clients as it cannot be decrypted without the site owner’s password.

Encrypted private signing key nonce (encryptedPrivateSigningKeyNonce)

This number used only once is used when:

  • Encrypting the site owner’s private signing key with the key derived from their password.
  • Decrypting the site owner’s private signing key with the key derived from their password.

Public signing key (publicSigningKey)

This is the site owner’s public signing key. It is created during registration along with the site owner’s private signing key using the crypto_secretbox_easy() function from the Sodium crypto library (libsodium).

Life-cycle and uses

  • Generated during initial registration.
  • Currently does not support being pathed/updated.
  • Used for public-key authentication.
  • Used to generate private and public encryption keys. We generate Curve25519 keys from Ed25519 keys using the crypto_sign_ed25519_sk_to_curve25519() and crypto_sign_ed25519_pk_to_curve25519() functions from the Sodium crypto library (libsodium), respectively.
  • To be used for end-to-end-encrypted private messages.

owner-settings.json

This file does not contain any secrets.

Contains the owner’s site-related settings like name, bio, profile image, background image, theme colour, etc.

Author: Aral Balkan Last modified: 07/04/2018 Words: ~700 Reading time: 3 min