================ File Encryption ================ .. role:: bash(code) :language: bash 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 =========== .. code-block:: bash 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 ================= .. contents:: :local: :depth: 1 ---- 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 :bash:`jaws keys list`. | **Save it immediately!** .. code-block:: bash $ 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. .. code-block:: bash $ 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 :bash:`.enc` file is written alongside it with the same permissions. .. code-block:: bash $ jaws encrypt --help Usage: jaws encrypt [OPTIONS] INPUT_FILE Options: -h, --help Show this message and exit. .. list-table:: :header-rows: 1 :widths: 35 65 * - Error - Message * - File not found - Encryption Failed. Input file ```` not found. * - No active key - Encryption Failed. Could not retrieve key for encryption. ```` * - JAWS Central unreachable - Encryption Failed. Could not retrieve key for encryption. Please contact JAWS support. ---- Decrypt --------------------------- | Decrypting a :bash:`.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. .. code-block:: bash $ jaws decrypt --help Usage: jaws decrypt INPUT_FILE .. list-table:: :header-rows: 1 :widths: 35 65 * - Error - Message * - File not found - Decryption Failed. Input file ```` not found. * - Missing ``.enc`` extension - Decryption Failed. ````. Make sure the file was encrypted with a JAWS DEK. * - Key inactivated or unreachable - Decryption Failed. ````. 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. .. code-block:: bash $ jaws keys inactivate --help Usage: jaws keys inactivate [OPTIONS] KEY_ID Options: -h, --help Show this message and exit. .. list-table:: :header-rows: 1 :widths: 35 65 * - Error - Message * - Key ID not found - Key Inactivation Failed. Key ID ```` not found. * - JAWS Central error - Key Inactivation Failed. ````. Please contact JAWS support. ---- Example ============================= .. code-block:: bash # list existing keys $ jaws keys list [] # create a DEK $ jaws keys create { "created_at": "2026-06-26T10:47:31", "key": , "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 .'} # 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 ============================= .. list-table:: :widths: 30 70 :class: borderless * - **Inactivation is permanent** - Verify you no longer need files encrypted with a key before running :bash:`jaws keys inactivate`, or back up the raw key string first. * - **Key string is shown once** - Store the ``key`` value from :bash:`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** - :bash:`jaws encrypt` leaves the original file in place. Delete it manually if needed.