Authentication and master key

Authentication in Passwork consists of two stages: basic authentication and master password verification (when CSE is enabled).

Two-stage authentication

Stage	Purpose	Where executed
Basic authentication	Credential verification	Server
Master password verification	Access to encrypted data	Client + Server

---

Stage 1: Basic authentication

Local authentication

1. User enters username and password
2. Server verifies password (PBKDF2, 600,000 iterations, SHA-512)
3. On success, Access Token and Refresh Token are issued
4. Client stores tokens for subsequent requests

Server password hashing parameters:

Parameter	Value
Algorithm	PBKDF2
Hash function	SHA-512
Iterations	600,000
Key length	512 bits

SSO / LDAP authentication

With SSO or LDAP:

1. User is redirected to external provider
2. After successful authentication, returns to Passwork
3. System creates session and issues tokens
4. If CSE is enabled — master password entry is requested

---

Stage 2: Master password verification

With client-side encryption enabled, master password entry is required after basic authentication.

Getting parameters

Client requests parameters from server for master key computation:

• Salt — unique per user
• Iteration count — 300,000
• Algorithm type — PBKDF2

Computing master key

Key derivation is performed on the client:

Parameter	Value
Algorithm	PBKDF2
Hash function	SHA-256
Iterations	300,000
Key length	512 bits
Input	Master password + Salt
Output	Master key (Base64)

Computing verification hash

To confirm correct entry, a hash of the master key is computed:

Parameter	Value
Algorithm	SHA-256
Input	Master key (512 bits)
Output	Hash (256 bits, hex string)

Server verification

Server compares the received hash with the stored value.

Why simple hash comparison?

• Hash is computed on client from a cryptographically strong 512-bit key
• Server doesn't know the original master key
• Additional server-side hashing doesn't add security in this Zero-Knowledge model

---

Complete authentication sequence

Phase 1 — Basic authentication:

1. User enters username and password
2. Server verifies credentials (PBKDF2, SHA-512, 600K iterations)
3. Server returns access tokens and CSE flag

Phase 2 — Master password (if CSE enabled):

4. Client requests PBKDF2 parameters (salt, iterations)
5. User enters master password
6. Client computes master key: PBKDF2(password, salt, 300K, SHA-256) → 512 bits
7. Client computes hash: SHA-256(master key) → 256 bits
8. Client sends hash to server
9. Server compares hashes
10. On success, server returns encrypted private RSA key

Phase 3 — Key decryption:

11. Client decrypts private RSA key with master key (AES-256-CBC)
12. Client is ready to work with encrypted data

Zero-Knowledge principle

Master password never leaves the client. Server sees only the master key hash. Private RSA key is transmitted only in encrypted form.

---

Salt parameters

Parameter	Value
Length	20 characters
Alphabet	A-Z, a-z, 0-9, @, ! (64 characters)
Entropy	~120 bits
Generation	Server, when creating/changing master password
Storage	In user profile on server

Salt properties:

• Each user has unique salt
• New salt is generated when master password changes
• Salt is not secret, but ensures hash uniqueness

---

Authentication scenarios

First login (setting master password)

1. User completes basic authentication
2. System determines master password is not set
3. Server generates new salt
4. User enters new master password
5. Client performs cryptographic operations:
   • Computes master key (PBKDF2)
   • Generates RSA key pair (2048 bits)
   • Encrypts private RSA key with master key (AES-256-CBC)
   • Computes master key hash (SHA-256)
6. Client sends to server:
   • Public RSA key (open)
   • Encrypted private RSA key
   • Master key hash

Subsequent login

1. Basic authentication
2. Get PBKDF2 parameters (salt, iterations)
3. Enter master password
4. Compute master key and hash
5. Verify hash on server
6. Decrypt private RSA key (AES-256-CBC)

Changing master password

1. User enters current master password
2. Correctness verification (hash comparison)
3. Enter new master password
4. New salt generated on server
5. Recalculate master key and hash
6. Decrypt private RSA key with old master key
7. Re-encrypt private RSA key with new master key (AES-256-CBC)
8. Save new data to server

Master password reset (by administrator)

Data loss

When administrator resets master password:

• New RSA key pair is generated
• User loses access to previously encrypted data
• Re-granting vault access is required

1. Administrator initiates reset
2. User's cryptographic data is deleted
3. User sets new master password
4. New RSA keys are generated
5. Vault administrators must re-grant access

---

Threat model and protection

Master password protection

Threat	Protection
Interception during entry	Master password processed only in browser
Interception during transmission	Only master key hash sent to server
Brute-force attack	PBKDF2 with 300,000 iterations
Rainbow tables	Unique salt per user
Server compromise	Server doesn't store master password or master key

Master key hash protection

Threat	Protection
Hash leak	Hash computed from 512-bit key (not from password)
Hash-based guessing	PBKDF2 makes each attempt computationally expensive
Password recovery	Must first guess the key, then the password

Session protection

Parameter	Access Token	Refresh Token
Lifetime	~2.8 hours	36 hours
Purpose	Request authentication	Access Token renewal
Storage	Secure browser storage	Secure browser storage

---

Error handling

Incorrect master password

1. Computed hash doesn't match stored value
2. Server returns error
3. Client prompts for re-entry
4. Attempt limits possible (configured by administrator)

Missing PBKDF2 parameters

If parameters not found — master password not set, initial setup required.

Cannot decrypt RSA key

If private RSA key decryption fails — incorrect master password or corrupted data.

---

Cryptographic summary

Operation	Algorithm	Parameters
Password hashing (server)	PBKDF2-SHA512	600,000 iterations
Master key derivation (client)	PBKDF2-SHA256	300,000 iterations, 512 bits
Verification hash	SHA-256	256 bits
RSA key encryption	AES-256-CBC	Master key
RSA key generation	RSA-OAEP	2048 bits, SHA-256

LLM version