Quick start

From zero to a working system in four steps. You generate the configuration fully offline — only the deployment itself requires your own PHP hosting.

#Step 1 — Generating the configuration

Open dashboard.html and go to the Configuration tab.

#Step 2 — Splitting the password with Shamir's algorithm

Go to the Encryption tab in dashboard.html.

#Step 3 — Uploading to the server

Update the path in auth.php:

// auth.php — path to the configuration
require_once '/home/user/private/secret-key.php';

#Step 4 — Generating and distributing the cards

Open the Card generator tab in dashboard.html. Enter each person's details and their Shamir share from the secret-key-shares.txt file, then download the cards as a PDF — ready to print or laminate.

Shamir's algorithm

Shamir Secret Sharing — mathematically guarantees that fewer than the required number of fragments reveals no information about the secret.

#How secret splitting works

The secret is encoded as the free term of a polynomial over the field GF(2⁸). Each share is a point on that polynomial — knowing the required number of points, it can be uniquely reconstructed via Lagrange interpolation:

f(x) = a₀ + a₁x + a₂x² + ... + aₖ₋₁xᵏ⁻¹  (mod p)

where: a₀ = the secret (master password)
       k   = required minimum number of shares
       a₁..aₖ₋₁ = random coefficients

#Example — a 5/3 split

#Implementation parameters

#Choosing the parameters

Secret Key cards

A personalized carrier for each designated person — a printable PDF in ISO ID-1 format (85.6×54mm), like a credit card.

#Card elements

#Card generator

The generator is available as the Card generator tab in dashboard.html. It requires the card-front.js and card-back.js files in the same folder.

#Technical specification

System architecture

A multi-layer verification flow — from entering a login to reconstructing the password in the browser.

#Authorization flow

#System layers

Authorization layer (/app/)

Access layer (/app/decrypt/)

Data layer (/private/ — outside public_html)

Security

Nine independent layers of protection — compromising one does not grant access to the system.

#Protection layers

#Shamir's cryptographic guarantee

Regardless of the strength of all the other layers — without the required number of shares, reconstructing the password is mathematically impossible. Even full access to the server, the configuration file, and the logs does not reveal the master password.

#Deployment best practices

Collusion risk protection

A 48-hour timelock on file downloads with an email alert and an emergency "Panic Button", protecting against collusion among designated trustees during the owner's lifetime.

#Why this is needed

Shamir's algorithm mathematically allows the designated people to reconstruct the master password itself if they collude to do so — an unavoidable property of any threshold secret-sharing system, not just this one. Before this mechanism, the only barrier was an email notification sent after the fact — the owner would find out about a login, but nothing stopped an immediate download of the password database. The system now also blocks physical access to the files for 48 hours from the moment the password is recovered, giving the owner real time to react.

#Stronger verification of the recovered password

The earlier success condition only checked that the Shamir reconstruction didn't throw an exception — plain secret sharing has no built-in integrity, so wrong or insufficient shares almost always still return some non-empty, random-looking string instead of an error. The system couldn't tell a "correctly recovered password" apart from cryptographic garbage — and that's exactly the signal that arms the timelock described below. Two independent verification methods were added:

#Four states of the download panel

The panel detects state changes live (tl-status.php, polled every 10s) — the Panic Button clicked in another tab, time elapsing, or a manual config reset all refresh the view automatically, with no action needed from the user.

#Panic Button — email alert and one-time blocking link

The first confirmed, successful secret reconstruction in the panel automatically: creates the lock state (private/timelock.json, a 48h window), logs a TIMELOCK ARMED event, and sends an alert email to the owner (see Content and data configuration → Email notification). The email contains a one-time link, panic.php?token=... (a 256-bit token, no login required — the owner may not have a way to log in quickly in a crisis situation). Clicking it immediately and permanently blocks downloads, regardless of whether the 48 hours have already elapsed or not.

#Reset after a Panic Button — automatic, no manual work

The validity of timelock.json is tied to a fingerprint (hash) of the current $people in secret-key.php. When the owner changes the master password and generates a new config after an incident (which they need to do anyway), the old timelock automatically loses validity on the panel's next refresh — with no need to manually delete the file over FTP/SSH in a stressful post-incident situation.

File structure

The complete project file tree — both server files and local offline tools.

#Files on the server

#Files outside public_html

#Local files (offline tools)

Requirements

What you need to run Secret Key on your own server.

#Server

#SMSPlanet account

The system sends 2FA codes via the SMSPlanet API. Required:

SMS content and code autofill (WebOTP)

The SMS message body is made of two parts from separate sources: the code text itself comes from lang.php (the twofa_sms_body key, via t() — the same vsprintf mechanism used for verify_attempts_left_*), while the WebOTP autofill suffix is built in auth.php from a constant set in secret-key.php:

// secret-key.php
define('SMS_AUTOFILL_DOMAIN', '@moja-domena.pl');

// private/lang.php — %s = code, %d = validity in minutes
'twofa_sms_body' => 'Kod weryfikacyjny: %s. Wazny %d min. Nie udostepniaj go nikomu.',

// auth.php — text from lang.php + WebOTP suffix from secret-key.php
$msg = t('twofa_sms_body', $code, $ttlMin) . "\n\n" . SMS_AUTOFILL_DOMAIN . " #$code";

The last part (@domain #code) isn't a typo or decoration — it's the format required by the WebOTP API. Thanks to it, the browser on the phone (Chrome/Android, Safari/iOS) recognizes the code in the incoming SMS on its own and fills the field automatically on the login page, without copying it manually from the SMS app.

#Local tools (offline)

Step-by-step installation

A complete guide from downloading the files to a working system on your own server.

#1. Offline configuration

Download the project files and open dashboard.html locally in Chrome.

Configuration tab

Encryption tab

#2. Uploading files to the server

# Upload the /app/ folder to public_html (it also contains /decrypt/ inside)
scp -r ./app/ user@server:~/public_html/

# Upload the configuration and interface texts OUTSIDE public_html
scp ./secret-key.php ./lang.php user@server:~/private/

#2a. CDN/cache exception (if you use Cloudflare or similar)

If your domain has site-wide caching enabled (e.g. a "Cache Everything" rule in Cloudflare, or a similar mechanism with another CDN provider), you must add an exception for the directory the system lives in before you start testing anything.

Example for Cloudflare (Caching → Cache Rules):

#3. Path configuration

In the app/auth.php file, update the path to the configuration file:

// Change this to the actual path to /private/ on your server
require_once '/home/twoj_uzytkownik/private/secret-key.php';

#3a. SMS test mode

Before deploying, it's worth checking that the system works correctly — without sending real SMS messages or spending SMSPlanet tokens. The app/auth.php file has a built-in test mode.

// ── TEST MODE — remove before deploying to production! ──
// $smsResult = true; $code = '123456';
// ────────────────────────────────────────────────────────

$smsResult = sendSmsCode($phoneFull, $code);

To enable test mode — uncomment the $smsResult = true line and comment out the sendSmsCode() call:

// ── TEST MODE — remove before deploying to production! ──
$smsResult = true; $code = '123456';  // ← uncomment
// ────────────────────────────────────────────────────────

// $smsResult = sendSmsCode($phoneFull, $code);  // ← comment out

Once test mode is enabled, the SMS verification code will always be 123456, regardless of the phone number. You can safely test the whole login flow without any cost.

#4. Generating and distributing the cards

Content and data configuration

Everything on this page is generated by dashboard.html (Configuration tab) into a single file — secret-key.php. Below is a description of what actually goes into the config and why, so you know what you're filling in on the form (or what to change if you'd rather edit secret-key.php by hand).

#1. People ($people)

$people is a single array with one record per person — login, password, contact details, and panel visibility, all in one place.

$people = [
  [
    'login'         => 'anna',
    'password'      => '$2y$10$...',  // bcrypt hash — generated by the dashboard
    'first_name'    => 'Anna',
    'last_name'     => 'Nowak',
    'phone_cc'      => '+48',          // country code — separate, any country
    'phone'         => '123456789',   // local number only, no country code
    'show_in_panel' => true,
  ],
  // more people...
];

#2. Downloadable files ($downloads)

$downloads is a single source for both the download buttons in the panel and the whitelist in download.php — it's literally the same array, so the two are always in sync.

$downloads = [
  ['key' => 'baza-hasel', 'label' => 'Pobierz bazę haseł',     'filename' => 'moja-baza-hasel.kdbx'],
  ['key' => 'aegis',      'label' => 'Pobierz bazę Aegis 2FA', 'filename' => 'moja-baza-aegis.json'],
  ['key' => 'program',    'label' => 'Pobierz KeePassXC',      'filename' => 'KeePassXC-2.7.9-Win64.msi', 'name' => 'KeePassXC'],
];

Alongside the file list itself, three additional variables control the texts of this panel section:

$download_heading = 'Pliki i program do odzyskania dostępu';  // plain text, <h3> heading
$download_intro = 'Pobierz bazę haseł, bazę kodów 2FA oraz program...';  // plain text, paragraph above the buttons
$alert_box_text = 'Pamiętaj: bez fizycznego klucza YubiKey...';  // plain text, blue box with an icon

#3. Instructions ($instructions)

The instruction steps in the panel are also data, not HTML code. Each step is a single text field with simple formatting — markdown-lite.

$instructions = [
  ['num' => '01', 'text' => '**Get together.** Contact the people on the list — you need a minimum of **3 out of 5 people**.'],
  ['num' => '02', 'text' => '**Open this page together.** Each person needs their own card (e.g. *8015c7c4...*).'],
  // more steps...
];

#4. Email notification ($email_notify)

The panel can send an email after every successful login — with the IP address, browser, and time. All the sender/recipient data lives in one array, so the domain isn't repeated separately across the From, Reply-To, Return-Path, X-Sender, and Message-ID headers.

$email_notify = [
  'enabled'    => true,
  'to'         => 'jan@moja-domena.pl',
  'from_email' => 'no-reply@moja-domena.pl',
  'from_name'  => 'Secret Key',
  'panel_url'  => 'https://moja-domena.pl',
];

Subject: 🔐 Secret Key Panel login — Jan Kowalski

New login to the Secret Key panel.

─────────────────────────────
User:       Jan Kowalski (jan)
Date/time:  01.05.2026 14:32:17
IP address: 89.123.45.67
Browser:    Mozilla/5.0 (Windows NT 10.0...)
─────────────────────────────

Panel: https://moja-domena.pl

#5. SMS code autofill

The domain shown in the SMS content (for automatic code entry on Android/iOS — see the Requirements page) is also part of the config now, not a manual edit to auth.php:

define('SMS_AUTOFILL_DOMAIN', '@moja-domena.pl');

#6. Required recovery threshold (SHARES_REQUIRED)

The recovery panel (/decrypt/index.php) needs to know how many card codes are required to reconstruct the password — the same threshold (K) you set in the dashboard's "Encryption" tab when splitting the master password into shares:

define('SHARES_REQUIRED', 4); // e.g. 4 of 7

Interface texts (lang.php)

All visible interface text — buttons, labels, error messages — is separated out of the code into a single file, private/lang.php.

#How it works

If you want to run the system in a language other than Polish, you edit lang.php by hand — the whole thing, once — and rewrite the content in secret-key.php ($instructions, $download_intro, etc.) in the same language. This is a deliberate choice of simplicity over a full i18n layer that nobody would be switching on the fly here anyway.

#Keys and the t() function

lang.php defines the $lang array — a snake_case-style key mapped to a text value. The code reads it through the t() function defined in auth.php:

// private/lang.php
$lang = [
  'login_submit_btn'   => 'Zaloguj się',
  'login_empty_fields' => 'Wpisz login i hasło.',
  // ...
];

// auth.php
function t(string $key, ...$args): string {
    global $lang;
    $text = $lang[$key] ?? $key;
    return $args ? vsprintf($text, $args) : $text;
}

t() also supports sprintf-style placeholders — e.g. for correct Polish plural declension of the remaining-attempts count:

// in lang.php
'verify_attempts_left_1'    => 'Pozostało %d próba.',
'verify_attempts_left_few'  => 'Pozostało %d próby.',
'verify_attempts_left_many' => 'Pozostało %d prób.',

// call
t('verify_attempts_left_few', $remaining);

#Changing the system's language

To run the system in a different language:

FAQ

Frequently asked questions about the security, operation, and deployment of the system.

#What if I lose my Secret Key card?

The card by itself is useless without access to the phone assigned to that account — logging in requires SMS verification. The risk is limited, but the owner should be informed and consider generating a new configuration with a new set of shares. Once the secret-key.php file on the server is replaced, the old cards stop working.

#Can I read the password on my own with just one card?

No. It's mathematically impossible. A single share reveals no information about the secret — this is a property of Shamir's algorithm called information-theoretic security. Only gathering the required number of shares allows the master password to be reconstructed.

#What if one of the designated people dies or becomes unavailable?

The system is designed with redundancy — it's enough to gather the minimum required number of shares (e.g. 3 of 5). One or two people being unavailable doesn't block the emergency procedure.

#Does the password reach the server during decryption?

No. Reconstructing the password from the Shamir shares happens entirely on the browser side (JavaScript). The server is only used to authenticate the user — the secret itself never leaves it.

#What if trustees collude and recover the password during my lifetime, without my knowledge?

The password alone isn't enough for them. The database files live outside the server's public directory, and access to them is controlled by download.php. The moment the password is first successfully reconstructed in the panel, the system automatically blocks file downloads for 48 hours and sends you an alert email with a one-time "Panic Button" link — one click permanently cuts off access, giving you time to calmly change the master password. Details: Collusion risk protection. If you also secure the password database with a hardware key (e.g. YubiKey), knowing the password alone isn't enough to open it, even after the files are unblocked.

#Can I use the system with a password manager other than KeePassXC?

Yes. Secret Key stores and reconstructs any master password — regardless of the manager used. Compatible with KeePassXC, Bitwarden, 1Password, and any other program that supports a master password.

#How do I choose the threshold — how many shares should be required?

The higher the threshold, the greater the security — but also the harder it is to gather everyone in a crisis situation. The recommended compromise is 3 of 5 — it tolerates two people being unavailable while keeping a good level of protection. Enter the same threshold as SHARES_REQUIRED in the config (the "Required codes" field in the dashboard's Configuration tab) — see Content and data configuration — otherwise the recovery panel will ask for a different number of codes than what's actually needed.

#How long are the login credentials from a card valid?

Indefinitely — as long as the owner doesn't generate a new configuration. Once the secret-key.php file on the server is replaced, the old cards stop working, and new ones need to be distributed to all the designated people.

#Why does the security alert email (Panic Button) sometimes land in spam?

This alert is sent automatically after the first successful password reconstruction in the panel — see Collusion risk protection. That email contains a one-time link with a long, random token (panic.php?token=...) — automated spam filters often flag links shaped like this regardless of the email's content, since structurally they resemble phishing links. This only affects the alert email — regular login notifications (which don't contain a clickable token link) usually reach the inbox without issue.

Fix: add the sender address (by default no-reply@your-domain, configured in $email_notify['from_email']) to the whitelist in the mail panel that receives the notifications — in cPanel this is the "Whitelist" section (Email → Whitelist), where you can add a trusted sender for a specific mailbox. Once the exception is added, the Panic Button email lands directly in the inbox.

Security policy

How to report security vulnerabilities and what you can expect in response.

Regular bugs, documentation typos, or improvement suggestions should be reported normally as an Issue on GitHub — that's the standard way, nothing secret about it. This page covers security vulnerabilities only (see reporting scope below) — please don't report those publicly.

#How to report a vulnerability

Send a detailed description to: dev@secretkey.website

#Response time

#Report scope

Dashboard overview

The dashboard is Secret Key's local configuration panel — an HTML file opened directly in the browser, no server needed. It has a Home page and three tool tabs: Configuration, Encryption, and Card generator, plus a PL/EN language switch.

#Main interface

Main view of dashboard.html with the four navigation tabs visible

#Required files

All the files must be in the same folder:

#Recommended browser

Tab: Configuration

Generates the secret-key.php file — the heart of the system. Contains the bcrypt-hashed passwords, the data for all designated people, the downloadable files, the panel instructions, and the email notification settings. Fully offline — nothing is sent anywhere.

#Tab view

Configuration tab — the form for designated people's data, downloadable files, instructions, and email notifications

#Interface elements

#Step by step

Tab: Encryption

Splits the master password to the password database into shares using Shamir's algorithm. Generates the secret-key-shares.txt file with the key fragments to distribute to the designated people.

#Tab view

Encryption tab with the password field, parameter sliders, and a preview of the generated shares

#Interface elements

#Step by step

Tab: Card generator

Creates personalized Secret Key cards in ISO ID-1 format (85.6×54mm), ready to print or laminate. Each card contains the login credentials, a Shamir share, and a QR code.

#Tab view

Card generator with global settings, a list of people, and a preview of the card front and back

#Interface elements

#Step by step