Szybki start

Od zera do działającego systemu w czterech krokach. Konfigurację generujesz w pełni offline — samo wdrożenie wymaga własnego hostingu z PHP.

#Krok 1 — Generowanie konfiguracji

Otwórz dashboard.html i przejdź do zakładki Konfiguracja.

#Krok 2 — Podział hasła algorytmem Shamira

Przejdź do zakładki Szyfrowanie w dashboard.html.

#Krok 3 — Wgranie na serwer

Zaktualizuj ścieżkę w auth.php:

// auth.php — ścieżka do konfiguracji
require_once '/home/user/private/secret-key.php';

#Krok 4 — Generowanie i dystrybucja kart

Otwórz zakładkę Generator kart w dashboard.html. Wprowadź dane każdej osoby i udziały Shamira z pliku secret-key-shares.txt, a następnie pobierz karty jako PDF — gotowe do wydruku lub laminowania.

Algorytm Shamira

Shamir Secret Sharing — matematycznie gwarantuje, że mniejsza niż wymagana liczba fragmentów nie ujawnia żadnej informacji o sekrecie.

#Jak działa podział sekretu

Sekret kodowany jest jako wyraz wolny wielomianu nad ciałem GF(2⁸). Każdy udział to punkt na tym wielomianie — znając wymaganą liczbę punktów, można go jednoznacznie odtworzyć interpolacją Lagrange'a:

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

gdzie: a₀ = sekret (hasło główne)
       k   = wymagane minimum udziałów
       a₁..aₖ₋₁ = losowe współczynniki

#Przykład — podział 5/3

#Parametry implementacji

#Dobór parametrów

Karty Secret Key

Spersonalizowany nośnik dla każdej wyznaczonej osoby — drukowany PDF w formacie ISO ID-1 (85.6×54mm), jak karta kredytowa.

#Elementy karty

#Generator kart

Generator dostępny jest jako zakładka Generator kart w dashboard.html. Wymaga plików card-front.js i card-back.js w tym samym folderze.

#Specyfikacja techniczna

Architektura systemu

Wielowarstwowy przepływ weryfikacji — od wpisania loginu do odtworzenia hasła w przeglądarce.

#Przepływ autoryzacji

#Warstwy systemu

Warstwa autoryzacji (/app/)

Warstwa dostępu (/app/decrypt/)

Warstwa danych (/private/ — poza public_html)

Bezpieczeństwo

Dziewięć niezależnych warstw ochrony — kompromitacja jednej nie daje dostępu do systemu.

#Warstwy ochrony

#Gwarancja kryptograficzna Shamira

Niezależnie od siły wszystkich pozostałych warstw — bez wymaganej liczby udziałów odtworzenie hasła jest matematycznie niemożliwe. Nawet pełny dostęp do serwera, pliku konfiguracyjnego i logów nie ujawnia hasła głównego.

#Dobre praktyki wdrożeniowe

Ochrona przed zmową powierników

48-godzinna blokada czasowa pobierania plików z alertem e-mail i przyciskiem awaryjnym („Panic Button"), chroniąca przed zmową wyznaczonych powierników za życia właściciela.

#Dlaczego to potrzebne

Algorytm Shamira matematycznie pozwala wyznaczonym osobom odtworzyć samo hasło główne, jeśli się w tym celu zmówią — to nieunikniona własność każdego progowego systemu dzielenia sekretu, nie tylko tego. Do wersji z tym mechanizmem jedyną barierą przed nadużyciem były powiadomienia email wysyłane po fakcie — właściciel dowiadywał się o logowaniu, ale nic nie stało na przeszkodzie natychmiastowemu pobraniu bazy haseł. System dodatkowo blokuje fizyczny dostęp do plików na 48 godzin od momentu odzyskania hasła, dając właścicielowi realny czas na reakcję.

#Silniejsza weryfikacja odzyskanego hasła

Wcześniejszy warunek sukcesu sprawdzał tylko, czy rekonstrukcja Shamira nie rzuciła wyjątku — czyste dzielenie sekretu nie ma wbudowanej integralności, więc błędne lub niewystarczające udziały i tak niemal zawsze zwracają jakiś niepusty, losowy ciąg zamiast błędu. System nie odróżniał więc „poprawnie odzyskanego hasła" od kryptograficznego śmiecia — a to właśnie ten sygnał uzbraja blokadę czasową opisaną niżej. Dodane zostały dwie niezależne metody weryfikacji:

#Cztery stany panelu pobierania

Panel na żywo wykrywa zmianę stanu (tl-status.php, odpytywanie co 10s) — Panic Button kliknięty w innej karcie, upływ czasu czy ręczny reset configu odświeżają widok automatycznie, bez akcji użytkownika.

#Panic Button — alert e-mail i jednorazowy link blokujący

Pierwsza potwierdzona udana rekonstrukcja sekretu w panelu automatycznie: tworzy stan blokady (private/timelock.json, 48h okno), loguje zdarzenie TIMELOCK ARMED i wysyła e-mail alarmowy do właściciela (patrz Konfiguracja treści i danych → Powiadomienie email). Mail zawiera jednorazowy link panic.php?token=... (token 256-bitowy, bez wymogu logowania — właściciel może nie mieć jak się szybko zalogować w sytuacji kryzysowej). Kliknięcie natychmiast i trwale blokuje pobieranie, niezależnie od tego, czy 48h już minęło, czy nie.

#Reset po Panic Button — automatyczny, bez ręcznej ingerencji

Ważność timelock.json jest powiązana z odciskiem (hashem) aktualnego $people w secret-key.php. Gdy właściciel po incydencie zmieni hasło główne i wygeneruje nowy config (co i tak musi zrobić), stary timelock automatycznie traci ważność przy najbliższym odświeżeniu panelu — bez potrzeby ręcznego kasowania pliku przez FTP/SSH w stresującej, powypadkowej sytuacji.

Struktura plików

Kompletne drzewo plików projektu — zarówno pliki serwera jak i lokalnych narzędzi offline.

#Pliki na serwerze

#Pliki poza public_html

#Pliki lokalne (narzędzia offline)

Wymagania

Co potrzebujesz, żeby uruchomić Secret Key na własnym serwerze.

#Serwer

#Konto SMSPlanet

System wysyła kody 2FA przez SMSPlanet API. Wymagane:

Treść SMS-a i autouzupełnianie kodu (WebOTP)

Treść wiadomości SMS składa się z dwóch części z osobnych źródeł: sam tekst kodu pochodzi z lang.php (klucz twofa_sms_body, przez t() — dokładnie ten sam mechanizm vsprintf co przy verify_attempts_left_*), a przyrostek do autouzupełniania WebOTP budowany jest w auth.php ze stałej ustawionej w secret-key.php:

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

// private/lang.php — %s = kod, %d = ważność w minutach
'twofa_sms_body' => 'Kod weryfikacyjny: %s. Wazny %d min. Nie udostepniaj go nikomu.',

// auth.php — treść z lang.php + przyrostek WebOTP z secret-key.php
$msg = t('twofa_sms_body', $code, $ttlMin) . "\n\n" . SMS_AUTOFILL_DOMAIN . " #$code";

Ostatni fragment (@domena #kod) to nie literówka ani ozdobnik — to format wymagany przez WebOTP API. Dzięki niemu przeglądarka na telefonie (Chrome/Android, Safari/iOS) sama rozpoznaje kod w przychodzącym SMS-ie i automatycznie wypełnia pole na stronie logowania, bez kopiowania go ręcznie z aplikacji SMS.

#Narzędzia lokalne (offline)

Instalacja krok po kroku

Kompletny przewodnik od pobrania plików do działającego systemu na własnym serwerze.

#1. Konfiguracja offline

Pobierz pliki projektu i otwórz dashboard.html lokalnie w Chrome.

Zakładka Konfiguracja

Zakładka Szyfrowanie

#2. Wgranie plików na serwer

# Wgraj folder /app/ do public_html (zawiera też /decrypt/ wewnątrz)
scp -r ./app/ user@serwer:~/public_html/

# Wgraj konfigurację i teksty interfejsu POZA public_html
scp ./secret-key.php ./lang.php user@serwer:~/private/

#2a. Wyjątek w CDN/cache (jeśli używasz Cloudflare lub podobnego)

Jeśli Twoja domena ma włączony cache na poziomie całej strony (np. reguła typu „Cache Everything" w Cloudflare, albo podobny mechanizm u innego dostawcy CDN), musisz dodać wyjątek dla katalogu, w którym stoi system, zanim zaczniesz cokolwiek testować.

Przykład dla Cloudflare (Caching → Cache Rules):

#3. Konfiguracja ścieżki

W pliku app/auth.php zaktualizuj ścieżkę do pliku konfiguracyjnego:

// Zmień na rzeczywistą ścieżkę do /private/ na Twoim serwerze
require_once '/home/twoj_uzytkownik/private/secret-key.php';

#3a. Tryb testowy SMS

Przed wdrożeniem warto sprawdzić czy system działa poprawnie — bez wysyłania prawdziwych SMS-ów i zużywania tokenów SMSPlanet. Plik app/auth.php zawiera wbudowany tryb testowy.

// ── TRYB TESTOWY — usuń przed wdrożeniem na produkcję! ──
// $smsResult = true; $code = '123456';
// ────────────────────────────────────────────────────────

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

Aby włączyć tryb testowy — odkomentuj linię z $smsResult = true i zakomentuj wywołanie sendSmsCode():

// ── TRYB TESTOWY — usuń przed wdrożeniem na produkcję! ──
$smsResult = true; $code = '123456';  // ← odkomentuj
// ────────────────────────────────────────────────────────

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

Po włączeniu trybu testowego — kod weryfikacyjny SMS będzie zawsze wynosił 123456, niezależnie od numeru telefonu. Możesz spokojnie przetestować cały przepływ logowania bez kosztów.

#4. Generowanie i dystrybucja kart

Konfiguracja treści i danych

Wszystko na tej stronie generuje dashboard.html (zakładka Konfiguracja) do jednego pliku — secret-key.php. Poniżej opisane jest, co faktycznie trafia do configu i po co, żebyś wiedział, co wypełniasz w formularzu (albo co zmieniasz, jeśli wolisz poprawić secret-key.php ręcznie).

#1. Osoby ($people)

$people to jedna tablica z jednym rekordem na osobę — login, hasło, dane kontaktowe i widoczność w panelu w jednym miejscu.

$people = [
  [
    'login'         => 'anna',
    'password'      => '$2y$10$...',  // hash bcrypt — generowany przez dashboard
    'first_name'    => 'Anna',
    'last_name'     => 'Nowak',
    'phone_cc'      => '+48',          // kierunkowy — osobno, dowolny kraj
    'phone'         => '123456789',   // sam numer lokalny, bez kierunkowego
    'show_in_panel' => true,
  ],
  // kolejne osoby...
];

#2. Pliki do pobrania ($downloads)

$downloads to jedno źródło zarówno dla przycisków pobierania w panelu, jak i białej listy w download.php — to dosłownie ta sama tablica, więc oba miejsca są zawsze zgodne ze sobą.

$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'],
];

Obok samej listy plików, trzy dodatkowe zmienne kontrolują teksty tej sekcji panelu:

$download_heading = 'Pliki i program do odzyskania dostępu';  // zwykły tekst, nagłówek <h3>
$download_intro = 'Pobierz bazę haseł, bazę kodów 2FA oraz program...';  // zwykły tekst, akapit nad przyciskami
$alert_box_text = 'Pamiętaj: bez fizycznego klucza YubiKey...';  // zwykły tekst, niebieski box z ikoną

#3. Instrukcja ($instructions)

Kroki instrukcji w panelu też są danymi, nie kodem HTML. Każdy krok to jedno pole tekstowe z prostym formatowaniem — markdown-lite.

$instructions = [
  ['num' => '01', 'text' => '**Zbierzcie się razem.** Skontaktujcie się z osobami z listy — potrzebujecie minimum **3 osoby z 5**.'],
  ['num' => '02', 'text' => '**Wejdźcie na tę stronę razem.** Każda osoba potrzebuje swojej karty (np. *8015c7c4...*).'],
  // kolejne kroki...
];

#4. Powiadomienie email ($email_notify)

Panel może wysyłać email po każdym udanym logowaniu — z adresem IP, przeglądarką i czasem. Wszystkie dane nadawcy/odbiorcy trzyma jedna tablica, żeby domena nie powtarzała się osobno w nagłówkach From, Reply-To, Return-Path, X-Sender i Message-ID.

$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',
];

Temat: 🔐 Logowanie do Secret Key Panel — Jan Kowalski

Nowe logowanie do panelu Secret Key.

─────────────────────────────
Użytkownik:   Jan Kowalski (jan)
Data i czas:  01.05.2026 14:32:17
Adres IP:     89.123.45.67
Przeglądarka: Mozilla/5.0 (Windows NT 10.0...)
─────────────────────────────

Panel: https://moja-domena.pl

#5. Autouzupełnianie kodu SMS

Domena widoczna w treści SMS-a (do automatycznego wypełniania kodu na Android/iOS — patrz strona Wymagania) też jest teraz configiem, nie ręczną edycją auth.php:

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

#6. Wymagany próg odzyskiwania (SHARES_REQUIRED)

Panel odzyskiwania (/decrypt/index.php) musi wiedzieć, ile kodów z kart wymaganych jest do złożenia hasła — czyli ten sam próg (K), który ustawiasz w zakładce dashboardu „Szyfrowanie" przy dzieleniu hasła głównego na udziały:

define('SHARES_REQUIRED', 4); // np. 4 z 7

Teksty interfejsu (lang.php)

Cały widoczny tekst interfejsu — przyciski, etykiety, komunikaty błędów — jest wydzielony z kodu do jednego pliku, private/lang.php.

#Zasada działania

Jeśli chcesz uruchomić system w innym języku niż polski, edytujesz lang.php ręcznie — całość, jednorazowo — oraz przepisujesz treść w secret-key.php ($instructions, $download_intro, itd.) na ten sam język. To świadomy wybór prostoty zamiast rozbudowanej warstwy i18n, której i tak nikt by tu nie przełączał w locie.

#Klucze i funkcja t()

lang.php definiuje tablicę $lang — klucz w stylu snake_case na wartość tekstową. Kod odczytuje ją przez funkcję t() zdefiniowaną w 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() wspiera też placeholdery w stylu sprintf — np. do poprawnej polskiej odmiany liczby pozostałych prób:

// w 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.',

// wywołanie
t('verify_attempts_left_few', $remaining);

#Zmiana języka systemu

Żeby uruchomić system w innym języku:

FAQ

Najczęściej zadawane pytania dotyczące bezpieczeństwa, działania i wdrożenia systemu.

#Co jeśli zgubię kartę Secret Key?

Sama karta jest bezużyteczna bez dostępu do telefonu przypisanego do danego konta — logowanie wymaga weryfikacji SMS. Ryzyko jest ograniczone, jednak właściciel powinien zostać poinformowany i rozważyć wygenerowanie nowej konfiguracji z nowym zestawem udziałów. Po zastąpieniu pliku secret-key.php na serwerze, stare karty przestają działać.

#Czy posiadając kartę mogę samodzielnie odczytać hasło?

Nie. Jest to matematycznie niemożliwe. Pojedynczy udział nie ujawnia żadnej informacji o sekrecie — to własność algorytmu Shamira zwana information-theoretic security. Dopiero zebranie wymaganej liczby udziałów pozwala na odtworzenie hasła głównego.

#Co jeśli jedna z wyznaczonych osób umrze lub będzie niedostępna?

System jest zaprojektowany z nadmiarowością — wystarczy zebrać minimalną wymaganą liczbę udziałów (np. 3 z 5). Niedostępność jednej lub dwóch osób nie blokuje procedury awaryjnej.

#Czy hasło trafia na serwer podczas odszyfrowania?

Nie. Rekonstrukcja hasła z udziałów Shamira odbywa się całkowicie po stronie przeglądarki (JavaScript). Serwer służy tylko do uwierzytelnienia użytkownika — sam sekret nigdy go nie opuszcza.

#Co jeśli powiernicy zmówią się i odzyskają hasło za mojego życia, bez mojej wiedzy?

Samo hasło im nie wystarczy. Pliki bazy danych leżą poza katalogiem publicznym serwera, a dostęp do nich kontroluje download.php. W momencie pierwszej udanej rekonstrukcji hasła w panelu system automatycznie blokuje pobieranie plików na 48 godzin i wysyła Ci e-mail z alertem oraz jednorazowym linkiem „Panic Button" — jedno kliknięcie trwale odcina dostęp, dając Ci czas na zmianę hasła głównego w spokoju. Szczegóły: Ochrona przed zmową powierników. Jeśli dodatkowo zabezpieczasz bazę haseł kluczem sprzętowym (np. YubiKey), sama znajomość hasła nie wystarczy do jej otwarcia nawet po odblokowaniu plików.

#Czy mogę używać systemu z innym menedżerem haseł niż KeePassXC?

Tak. Secret Key przechowuje i odtwarza dowolne hasło główne — niezależnie od używanego menedżera. Kompatybilny z KeePassXC, Bitwarden, 1Password i każdym innym programem obsługującym hasło główne.

#Jak wybrać próg — ile udziałów jest wymaganych?

Im wyższy próg, tym większe bezpieczeństwo — ale też trudniejsze zebranie się w sytuacji kryzysowej. Rekomendowany kompromis to 3 z 5 — pozwala na niedostępność dwóch osób przy zachowaniu dobrego poziomu ochrony. Wybrany próg wpisz też jako SHARES_REQUIRED w configu (pole „Wymagane kody" w zakładce Konfiguracja dashboardu) — patrz Konfiguracja treści i danych — inaczej panel odzyskiwania będzie żądał innej liczby kodów niż realnie potrzeba.

#Jak długo ważne są dane logowania z karty?

Bezterminowo — o ile właściciel nie wygeneruje nowej konfiguracji. Po zastąpieniu pliku secret-key.php na serwerze stare karty przestają działać i konieczne jest rozdanie nowych wszystkim wyznaczonym osobom.

#Dlaczego mail z alertem bezpieczeństwa (Panic Button) czasem trafia do spamu?

Ten alert wysyłany jest automatycznie po pierwszej udanej rekonstrukcji hasła w panelu — patrz Ochrona przed zmową powierników. Taki mail zawiera jednorazowy link z długim, losowym tokenem (panic.php?token=...) — automatyczne filtry antyspamowe często oznaczają linki tego kształtu, niezależnie od treści maila, bo pod względem struktury przypominają linki phishingowe. To dotyczy tylko maila z alertem — zwykłe powiadomienia o logowaniu (bez klikalnego linku z tokenem) zwykle trafiają do odebranych bez problemu.

Rozwiązanie: dodaj adres nadawcy (domyślnie no-reply@twoja-domena, skonfigurowany w $email_notify['from_email']) do białej listy w panelu poczty, na który przychodzą powiadomienia — w cPanel jest to sekcja „Biała lista" (Email → Biała lista), gdzie można dodać zaufanego nadawcę osobno dla wybranej skrzynki. Po dodaniu wyjątku mail z Panic Buttonem trafia już bezpośrednio do odebranych.

Polityka bezpieczeństwa

Jak zgłaszać luki bezpieczeństwa i czego możesz oczekiwać w odpowiedzi.

Zwykłe błędy, literówki w dokumentacji czy propozycje ulepszeń zgłaszaj normalnie jako Issue na GitHubie — to standardowa droga i nie ma w tym nic tajnego. Ta strona dotyczy wyłącznie luk bezpieczeństwa (patrz zakres zgłoszeń niżej) — tych proszę nie zgłaszać publicznie.

#Jak zgłosić lukę

Wyślij szczegółowy opis na: dev@secretkey.website

#Czas odpowiedzi

#Zakres zgłoszeń

Przegląd dashboard

Dashboard to lokalny panel konfiguracyjny Secret Key — plik HTML otwierany bezpośrednio w przeglądarce bez serwera. Zawiera trzy zakładki: Konfiguracja, Szyfrowanie i Generator kart.

#Interfejs główny

Widok główny dashboard.html z widocznymi czterema zakładkami nawigacyjnymi

#Wymagane pliki

Wszystkie pliki muszą znajdować się w tym samym folderze:

#Zalecana przeglądarka

Zakładka: Konfiguracja

Generuje plik secret-key.php — serce systemu. Zawiera zahashowane hasła bcrypt, dane wszystkich wyznaczonych osób, pliki do pobrania, instrukcję panelu i ustawienia powiadomienia email. Operacja w pełni offline — nic nie jest nigdzie wysyłane.

#Widok zakładki

Zakładka Konfiguracja — formularz danych wyznaczonych osób, plików do pobrania, instrukcji i powiadomień email

#Elementy interfejsu

#Krok po kroku

Zakładka: Szyfrowanie

Dzieli hasło główne do bazy haseł na udziały algorytmem Shamira. Generuje plik secret-key-shares.txt z fragmentami klucza do rozdania wyznaczonym osobom.

#Widok zakładki

Zakładka Szyfrowanie z polem hasła, suwakami parametrów i podglądem wygenerowanych udziałów

#Elementy interfejsu

#Krok po kroku

Zakładka: Generator kart

Tworzy spersonalizowane karty Secret Key w formacie ISO ID-1 (85.6×54mm) gotowe do wydruku lub laminowania. Każda karta zawiera dane logowania, udział Shamira i kod QR.

#Widok zakładki

Generator kart z ustawieniami globalnymi, listą osób i podglądem przodu i tyłu karty

#Elementy interfejsu

#Krok po kroku