Security and trust Key management

Key management

Data encryption uses age, a free, open-source encryption tool. You create your keys on your own computer. Oxelone is not involved, and ships no key tool of its own.

Create a key pair

Install age, or download it from the project's releases.

System Command
Windows winget install --id FiloSottile.age
macOS brew install age
Ubuntu 22.04 or later, Debian 12 or later apt install age
Generate a key pair:
```
age-keygen -o key.txt
```
It prints your public key, the line starting with age1. key.txt holds your private key, starting with AGE-SECRET-KEY-1.
Move key.txt to your secrets manager.
Paste the public key on the Data encryption page.

System	Command
Windows	`winget install --id FiloSottile.age`
macOS	`brew install age`
Ubuntu 22.04 or later, Debian 12 or later	`apt install age`

Store the private key

If you lose the private key, nobody can read what it protects. Oxelone cannot recover it. Keep a copy somewhere your team can reach if the person who created it leaves.

Anyone with the private key and permission to read content in your workspace can read what it protects. Oxelone staff will never ask for it.

Prove you hold it

Whenever you set a public key, we encrypt a code with it. Save the code as code.age and run:

age --decrypt -i key.txt code.age

Then enter the code on the page. You can also enter the private key on the page instead, and the browser decrypts the code. It is never sent to Oxelone.

Batch keys

Oxelone does not encrypt each record with your key directly. Each hour, the server creates a new random batch key for your workspace, encrypts that hour's data with it, and stores it only as an age file locked to your public key. The readable copy stays in memory for that hour, and then is gone.

Your private key opens a batch key, and the batch key opens the records. This is why changing key never rewrites your data, and why reading a page of interactions takes so few steps.

Records: XChaCha20-Poly1305, under a 256-bit batch key, with a new random nonce for each record. Each record is bound to its workspace, table and row, so ciphertext copied elsewhere does not open.
Batch keys: a standard age file: X25519, HKDF-SHA256 and ChaCha20-Poly1305.

Change key

Create a new key pair, and paste the new public key after choosing Change key.
Prove you hold the new private key, as above.
Choose where it runs.

	In this browser tab	In the background on Oxelone
Batch keys reach Oxelone's servers	Never	Opened ones, for this job, then destroyed
You can close the page	No. Closing it pauses the change	Yes. We tell you when it finishes
Needs in the browser	Both private keys	The current private key, or nothing if you use age

With age on your computer, for the background route, download batch-keys.zip, unzip it next to key.txt, then:

for f in *.age; do age --decrypt -i key.txt "$f"; done > opened-keys.txt

On Windows PowerShell:

Get-ChildItem *.age | ForEach-Object { age --decrypt -i key.txt $_.FullName } | Set-Content -Encoding ascii opened-keys.txt

Upload opened-keys.txt, then delete it. Every key is checked before anything starts, so a wrong file changes nothing.

A key change cannot lose your data. New copies of the batch keys sit beside the old ones. The in-browser route ends with a final check: your new private key opens 20 batch keys chosen at random, and only then does one database transaction switch the key. Until then, your current key opens everything. New data written meanwhile opens with either key.

The old public key can never be used in this workspace again.

If you lost the private key

Choose I no longer have this key, then Start over. New data uses your new key from then on. Everything encrypted under the old key stays locked until retention deletes it, unless the key turns up. All workspace admins are emailed. This cannot be undone.