Verified Commit ad10f18e authored by Aral Balkan's avatar Aral Balkan
Browse files

Add information on the cryptography used to the configuration section.

parent 2e18da34
......@@ -9,6 +9,12 @@ Configuration data is stored in various JSON files in the data directory (_~/.in
## server-secret.json
```json
{
"serverSecret": "<server secret">
}
```
**This file contains a secret.**
* Generated on first run of the app.
......@@ -17,53 +23,74 @@ Configuration data is stored in various JSON files in the data directory (_~/.in
**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)
```json
{
"serverSecret": "<server secret">
"secretSignUpCode": "<secret sign-up code>"
}
```
## installer-secret.json (Optional)
**This file contains a secret.**
This file is generated by the [Magic Website Factory](/hallo.gent/magic-website-factory) when an Indie Site instance is deployed by an Indie Site Installer (like [Hallo.gent](/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](/hallo.gent/indie-site-deployment).
## owner-keys.json
```json
{
"secretSignUpCode": "<secret sign-up code>"
"derivedKeySalt": "…",
"encryptedPrivateSigningKeyNonce": "…",
"encryptedPrivateSigningKey": "…",
"publicSigningKey": "…"
}
```
## owner-keys.json
<em>This file does <strong>not</strong> contain any secrets.</em>
Contains the following _non-secret_ key information:
* Derived private key salt
* Encrypted private signing key
* Encrypted private signing key nonce
* Public signing key
### 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).
This information is:
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](https://en.wikipedia.org/wiki/Rainbow_table)).
### 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.
```json
{
"derivedKeySalt": "…",
"encryptedPrivateSigningKeyNonce": "…",
"encryptedPrivateSigningKey": "…",
"publicSigningKey": "…"
}
```
## owner-settings.json
<em>This file does <strong>not</strong> contain any secrets.</em>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment