2.7 Encrypting Configuration Data
How to encrypt and decrypt configuration data for storage in JSONAir.
Configuration data stored in the JSONAir database may contain sensitive information — credentials, internal hostnames, API keys, and so on. JSONAir encrypts all config_data at rest using AES-256-GCM (authenticated encryption). The server decrypts transparently on every request — agents see no difference.
The jsonair-encrypt tool handles the encryption step when you insert data into the database by hand. You do not need it if you use jsonair-admin (2.8) or jsonair-write (2.9); both base64-encode and encrypt for you, in exactly the same form.
How It Works
1
Admin
Base64-encodes the raw configuration
2
Admin
Pipes the Base64 value through jsonair-encrypt
3
Admin
Inserts the encrypted output into config_data
4
Server
Decrypts config_data on every /config request
5
Agent
Receives Base64-encoded config — no change from its perspective
The encryption key is derived from CONFIG_ENCRYPT_SECRET using SHA-256, producing a 32-byte AES-256 key. Each encryption uses a randomly generated nonce (IV), so two encryptions of the same data produce different ciphertext. The GCM authentication tag ensures any tampering with the stored value is detected and rejected by the server.
The jsonair-encrypt Tool
jsonair-encrypt reads from stdin and writes to stdout. It requires CONFIG_ENCRYPT_SECRET to be set — either as an environment variable or in a .env file in the same directory.
(none)
Encrypt: reads plaintext, writes encrypted Base64
-d
Decrypt: reads encrypted Base64, writes plaintext
Building
Encrypting
Decrypting
Encrypting a file
Or as a single pipeline:
Using a .env file
If you place a .env file in the same directory as jsonair-encrypt, it will be loaded automatically:
Then simply:
Full Workflow — Adding a New Configuration
1. Base64-encode your configuration
2. Encrypt the output
Copy the output — it is the value for config_data.
3. Insert into the database
Key Management
CONFIG_ENCRYPT_SECRET must be the same value everywhere configuration data is written or read: the jsonair-encrypt tool, jsonair-admin, jsonair-write and the jsonair server. If they differ, the server will fail to decrypt and return a 500 error.
Best practices:
Generate a strong secret:
openssl rand -hex 32Keep
CONFIG_ENCRYPT_SECRETseparate from every other secret (TOKEN_HMAC_SECRET,JWT_TOKEN_SECRET,ADMIN_SESSION_SECRET,WRITE_TOKEN_HMAC_SECRET,WRITE_JWT_TOKEN_SECRET) — use a distinct value for eachStore the secret in a secrets manager (Vault, AWS Secrets Manager, etc.) in production rather than in a
.envfileTreat key rotation as a migration (see below)
Migrating Existing (Unencrypted) Data
If you have existing config_data rows that were stored as plain Base64 (before encryption was introduced), you must re-encrypt them before deploying the new server version. The server expects all config_data to be encrypted — it will return a 500 on any row that is not.
Migration steps
Set
CONFIG_ENCRYPT_SECRETin your environment.For each existing row, retrieve the current
config_datavalue and pipe it throughjsonair-encrypt:
Repeat for every row, then deploy the new server.
Key Rotation
To rotate CONFIG_ENCRYPT_SECRET:
Decrypt every
config_datarow using the old key (pass-d).Re-encrypt each row using the new key.
Update
CONFIG_ENCRYPT_SECRETon the server,jsonair-adminandjsonair-write(whichever you run) and restart them.
Until step 3 is complete, keep the old server running — it cannot read rows encrypted with the new key. Stop jsonair-admin and jsonair-write for the duration, so nothing is written with the old key while you rotate.
Last updated