File Encryption

JAWS supports file encryption using per-user Data Encryption Keys (DEKs). Files are encrypted locally with the Fernet algorithm.

The primary use case is protecting secrets passed to WDL workflows via input files such as passwords, API tokens, and database credentials that command stanzas read at runtime. Because input files are staged to shared scratch storage and may be visible to other users or retained in run folders after a job completes, encrypting them with a DEK protects those secrets at rest.

This feature is designed for small credential files; it is not intended for bulk data encryption.

Quick Start

jaws keys create                           # 1. Create a DEK
jaws encrypt sensitive_data.tsv            # 2. Encrypt a file
jaws decrypt sensitive_data.tsv.enc        # 3. Decrypt when needed
jaws keys list                             # 4. Check key status
jaws keys inactivate ks_abcdefgh1234       # 5. Retire a key

Command Reference

Create 

Create a new Data Encryption Key (DEK) for file encryption.

Warning

The key string is shown only once and is not retrievable later via jaws keys list.

Save it immediately!

$ jaws keys create --help
Usage: jaws keys create [OPTIONS]

Options:
  -h, --help  Show this message and exit.

List 

List metadata for all your DEKs.

Warning

The raw key string is not included.

$ jaws keys list --help
Usage: jaws keys list [OPTIONS]

Options:
  -h, --help  Show this message and exit.

Encrypt 

Encrypt a file using your active DEK.
The original file is not modified.
A new .enc file is written alongside it with the same permissions.

$ jaws encrypt --help
Usage: jaws encrypt [OPTIONS] INPUT_FILE

Options:
  -h, --help  Show this message and exit.

Error	Message
File not found	Encryption Failed. Input file `<path>` not found.
No active key	Encryption Failed. Could not retrieve key for encryption. `<detail>`
JAWS Central unreachable	Encryption Failed. Could not retrieve key for encryption. Please contact JAWS support.

Decrypt 

Decrypting a .enc file requires an active DEK.

Writes the plaintext alongside the encrypted file. If a file with the output name already exists, it will be overwritten.

$ jaws decrypt --help
Usage: jaws decrypt INPUT_FILE

Error	Message
File not found	Decryption Failed. Input file `<path>` not found.
Missing `.enc` extension	Decryption Failed. `<detail>`. Make sure the file was encrypted with a JAWS DEK.
Key inactivated or unreachable	Decryption Failed. `<detail>`. Please contact JAWS support.

Inactivate 

Permanently delete a DEK.

Warning

This cannot be undone. Files encrypted with the inactivated key will no longer be decryptable.

$ jaws keys inactivate --help
Usage: jaws keys inactivate [OPTIONS] KEY_ID

Options:
  -h, --help  Show this message and exit.

Error	Message
Key ID not found	Key Inactivation Failed. Key ID `<key_id>` not found.
JAWS Central error	Key Inactivation Failed. `<detail>`. Please contact JAWS support.

Example

# list existing keys
$ jaws keys list
[]

# create a DEK
$ jaws keys create
{
  "created_at": "2026-06-26T10:47:31",
  "key": <key-plaintext>,
  "key_id": "ks_36cd2caf-95a9-49ec-aa51-9b8c877ed611",
  "status": "active"
}

# list existing keys: new key now seen
$ jaws keys list
[
  {
    "created_at": "2026-06-26T10:47:31",
    "key_id": "ks_36cd2caf-95a9-49ec-aa51-9b8c877ed611",
    "status": "active"
  }
]

# encrypt file with secrets with your active key
$ jaws encrypt test_secret_msg.txt
✅ Successfully encrypted 'test_secret_msg.txt' to 'test_secret_msg.txt.enc'

# decrypt an encrypted file with your active key
$ jaws decrypt test_secret_msg.txt.enc
✅ Successfully decrypted 'test_secret_msg.txt.enc' to 'test_secret_msg.txt'

# trying to create a new DEK when you already have an active DEK fails
$ jaws keys create
[ ✖ ] Key Creation Failed

  {'detail': 'Active data encryption key already exists for user <username>.'}

# permanently delete a specific DEK
# make sure there are no files that need to be decrypted with this DEK
$ jaws keys inactivate ks_36cd2caf-95a9-49ec-aa51-9b8c877ed611
✅ Successfully inactivated key 'ks_36cd2caf-95a9-49ec-aa51-9b8c877ed611'
{
  "key_id": "ks_36cd2caf-95a9-49ec-aa51-9b8c877ed611",
  "status": "inactive",
  "updated_at": "2026-06-26T10:50:59"
}

# list existing keys: status updated to inactive
$ jaws keys list
[
  {
    "created_at": "2026-06-26T10:47:31",
    "key_id": "ks_36cd2caf-95a9-49ec-aa51-9b8c877ed611",
    "status": "inactive"
  }
]

Limitations & Best Practices

Inactivation is permanent	Verify you no longer need files encrypted with a key before running `jaws keys inactivate`, or back up the raw key string first.
Key string is shown once	Store the `key` value from `jaws keys create` in a secrets manager or encrypted vault if long-term recovery is needed.
Keys are per-user	A file encrypted with your DEK cannot be decrypted by a colleague without a copy of your raw key string.
Plaintext is not removed	`jaws encrypt` leaves the original file in place. Delete it manually if needed.

File Encryption

Quick Start

Command Reference

Create

List

Encrypt

Decrypt

Inactivate

Example

Limitations & Best Practices

Create 

List 

Encrypt 

Decrypt 

Inactivate 