Authentication Flow

This page explains how BlokSec’s passwordless authentication works at a technical level. Understanding the flow helps you design better integrations and troubleshoot issues.

What makes BlokSec different

Traditional authentication relies on shared secrets — passwords that both the user and the server know. BlokSec replaces this with public-key cryptography and a three-factor model where no single party holds enough information to forge an authentication.

Instead of verifying “does the user know the password?”, BlokSec verifies “can the user produce a valid digital signature?” The private key needed to sign is split across three parties and only assembled momentarily during authentication.

The three-factor model

BlokSec’s security model distributes trust across three components:

Factor	Holder	What it stores
Encrypted key envelope	BlokSec server (database)	The user’s Ed25519 private key, encrypted with AES-256-GCM. Also stores a server salt used in key derivation.
Device salt	User’s device or QR code	A random value embedded in the QR code or stored on the mobile device. Required for key derivation but never stored on the server.
PIN / passphrase	User’s memory	A PIN or passphrase known only to the user. Required for key derivation.

All three factors must be present to decrypt the private key and produce a signature. The server stores the encrypted envelope and server salt. The QR code contains the device salt. The user provides the PIN. None of these alone is sufficient.

Key derivation

When the three factors come together, BlokSec derives the decryption key using a dual-salt key derivation function:

1. PBKDF2 — Derive an intermediate key from the user’s PIN and the server salt (100,000 iterations of SHA-256)
2. HKDF — Derive the final key-encryption-key (KEK) from the intermediate key and the device salt

PIN + Server Salt → PBKDF2 (100k iterations) → Intermediate Key
Intermediate Key + Device Salt → HKDF-SHA256 → Key-Encryption-Key (KEK)

The KEK is used to decrypt the AES-256-GCM encrypted private key envelope. The decrypted private key exists in memory only for the duration of the signing operation.

Note

The dual-salt design means that even if an attacker compromises the database (which contains the encrypted envelope and server salt), they cannot perform offline key derivation without the device salt. And even with both salts, they still need the user’s PIN.

QR code authentication (BlokCode)

The QR code authentication flow is BlokSec’s primary method:

1. User initiates sign-in — The user enters their identifier on the login page
2. Server generates QR code — The server creates a QR code containing the device salt and authentication URL
3. User scans QR code — The BlokSec app scans the QR code and extracts the device salt
4. User enters PIN — The app prompts for the user’s PIN
5. Server decrypts and signs — The server receives the device salt and PIN, derives the KEK, decrypts the private key, signs the authentication data, and immediately discards the private key from memory
6. Server verifies signature — The server verifies the signature using the stored public key
7. Authentication completes — The protocol-specific response (OIDC token, SAML assertion, etc.) is issued

The private key never leaves the server. The user’s PIN never leaves the authentication request. The device salt is transmitted over HTTPS but is not stored on the server (only a hash is stored for verification).

Push notification authentication (BlokKey)

Push notification authentication is the most common flow for users who have already enrolled:

1. User initiates sign-in — The user enters their identifier on the login page
2. Server sends push notification — A push notification is sent to the user’s registered device (via APNs for iOS or FCM for Android)
3. User approves or denies — The user sees the sign-in request on their phone, including the application name, location, and device information. They tap Approve or Deny.
4. Server records response — The user’s response is recorded and the authentication completes (or fails if denied)

The login page polls the server while waiting for the user’s response. If the user doesn’t respond within 120 seconds, the request expires.

Tip

Push authentication doesn’t require QR scanning, making it faster for day-to-day sign-ins. QR authentication is primarily used for initial device setup or when push notifications aren’t available.

DID-based identity

BlokSec uses Decentralized Identifiers (DIDs) as the primary identity anchor for users and applications. Each user has a master DID derived from their cryptographic key pair, and each application has its own DID derived from its database identifier.

DIDs appear in OIDC tokens as the sub (subject) claim and in SAML assertions as part of the internal identifiers. Your application doesn’t need to understand or process DIDs directly — they’re used internally by BlokSec for identity management.

Security properties

Property	How it’s achieved
No shared secrets	Authentication uses Ed25519 digital signatures, not passwords
Phishing-resistant	Users approve on their own device — there’s no password to type into a fake page
Offline cracking resistance	Dual-salt KDF requires both server salt and device salt; database compromise alone is insufficient
Forward secrecy	Each authentication produces a unique signature; compromising one doesn’t help with others
Key never persisted in plaintext	Private key exists in memory only during the signing operation