Skip to content

Protected Action Encryption Model

Jump to bottom
Abdul Ahad edited this page Jun 25, 2026 · 1 revision

Goal

Protect sensitive action execution data in SQLite, especially:

  • start folder
  • command
  • arguments

Normal action metadata can stay plain so Action Desk can still list actions quickly.

Core idea

We use a two-key model:

User password
  -> derives wrapping key
  -> unlocks master key
  -> master key decrypts protected actions

The user password does not directly encrypt every action.

Acronyms / Terms

Password

The secret the user remembers.

It is never stored in the database.

PBKDF2

PBKDF2 = Password-Based Key Derivation Function 2

It turns the user password into a real encryption key.

PBKDF2(password + salt + iterations) = wrapping key

It is intentionally slow, so password guessing becomes expensive.

Salt

Random non-secret data used with the password.

Purpose:

  • makes the derived key unique
  • prevents reusable/precomputed password attacks
  • same password + different salt = different key

Salt is stored in the database.

Iterations

How many times PBKDF2 repeats its work.

Purpose:

  • slows down brute-force guessing
  • makes each attacker password attempt more expensive

Iterations are stored in the database.

Wrapping Key

The key derived from the user password using PBKDF2.

Purpose:

  • encrypts/decrypts the master key
  • does not directly encrypt action commands

Master Key

A random strong key generated by Action Desk.

Purpose:

  • encrypts/decrypts protected action payloads
  • allows password changes without re-encrypting every action

The master key is never stored in plaintext.

AES

AES = Advanced Encryption Standard

The actual encryption algorithm.

Purpose:

  • turns readable data into unreadable ciphertext
  • decrypts it back only with the correct key

GCM

GCM = Galois/Counter Mode

A safe AES mode.

Purpose:

  • encrypts the data
  • also detects tampering

We use:

AES-GCM

IV

IV = Initialization Vector

A fresh random value used for each AES-GCM encryption.

Purpose:

  • makes repeated encryption safe
  • ensures the same data encrypted twice gives different output

IV is not secret and is stored with the encrypted data.

Authentication Tag

A tamper-check value produced by AES-GCM.

Purpose:

  • proves the encrypted data was not modified
  • proves the correct key/password was used

If the password is wrong or data is changed, tag validation fails.

Ciphertext

Encrypted unreadable data.

Example plaintext:

{
  "command": "pwsh",
  "arguments": "-File backup.ps1"
}

becomes unreadable ciphertext in the database.

Base64

Text encoding for binary encrypted bytes.

Purpose:

  • lets us store encrypted bytes safely inside JSON/SQLite text fields

Base64 is not encryption.

Global Security Config

When the user creates a security password:

1. Generate random salt
2. Generate random master key
3. Generate random IV
4. Use PBKDF2(password, salt, iterations) to create wrapping key
5. Use AES-GCM(wrapping key, IV) to encrypt the master key
6. Store only salt, iterations, IV, and encrypted master key

We do not store:

plain password
plain wrapping key
plain master key

Protected Action Payload

For protected actions, sensitive fields are stored inside encrypted payload:

{
  "startFolder": "C:/project",
  "command": "pwsh",
  "arguments": "-File backup.ps1"
}

This JSON is encrypted using:

AES-GCM(master key, fresh IV)

The database stores:

protected = true
secure_payload_iv
secure_payload_ciphertext

Plain command/start folder/arguments should be empty or ignored.

Running a Protected Action

1. User runs protected action
2. Ask for password
3. PBKDF2 recreates wrapping key
4. Wrapping key decrypts master key
5. Master key decrypts action payload
6. Action Desk runs the command
7. Decrypted data stays only in memory

Changing Password

This is why the master key exists.

Actions are encrypted with the master key, not the password.

So password change only does this:

1. Old password decrypts master key
2. New password creates new wrapping key
3. Same master key is encrypted again with new wrapping key
4. Protected action payloads remain unchanged

No need to decrypt/re-encrypt every action.

What This Protects

Protects against:

  • someone opening/copying the SQLite database
  • exposed database backups
  • casual inspection of commands/arguments
  • manual tampering with encrypted command data

Does not protect against:

  • malware/keyloggers
  • someone controlling the running Windows session
  • memory inspection while Action Desk is unlocked
  • weak user passwords being guessed

Final Summary

Password protects wrapping key creation.
Wrapping key protects master key.
Master key protects protected action payloads.
AES-GCM encrypts and detects tampering.
Salt and iterations make password guessing harder.
IV keeps each encryption unique.

Clone this wiki locally