Przejdź do głównej zawartości

Certificate Pinning

Certificate Pinning to zaawansowana technika bezpieczeństwa, która wykracza poza standardową walidację Certificate Authority. Polega na "przypięciu" (pinning) konkretnego klucza publicznego serwera do Twojej aplikacji, co znacząco zwiększa bezpieczeństwo komunikacji z API Paymentic.

Dlaczego to jest ważne?​

Certificate Pinning zapewnia dodatkową warstwę ochrony przed zaawansowanymi atakami Man-in-the-Middle (MitM), w tym:

  • Atakami wykorzystującymi skompromitowane urzędy certyfikacji (CA)
  • Atakami z wykorzystaniem fałszywych certyfikatów, które mogłyby zostać uznane za zaufane przez system operacyjny

SPKI (Subject Public Key Info) — rekomendowana metoda​

Rekomendujemy wyłącznie pinning klucza publicznego (SPKI), a nie pinning całego certyfikatu. Powody:

  • Klucz publiczny przeżywa rotację certyfikatu. Certyfikaty wygasają i są odnawiane (zwykle co 3–12 miesięcy). Dopóki nie zmieniamy pary kluczy, ten sam pin pozostaje ważny po odnowieniu certyfikatu — integracja nie wymaga zmian.
  • Pinning odcisku certyfikatu (SHA-256 fingerprint całego certyfikatu) łamie się przy każdej rotacji, co w praktyce prowadzi do nieplanowanych awarii integracji albo — co gorsza — do wyłączania pinningu przez zespoły, które mają dość "naprawiania" go co kwartał.
  • SPKI jest standardem wspieranym natywnie przez cURL (--pinnedpubkey), libcurl (CURLOPT_PINNEDPUBLICKEY), OkHttp (CertificatePinner), a także RFC 7469 (HPKP, obecnie wycofany w przeglądarkach, ale wzorzec pozostaje kanoniczny dla integracji backend-to-backend).

Pin SPKI to Base64 z SHA-256 pola SubjectPublicKeyInfo certyfikatu serwera, podawany w formacie sha256//<base64>.

Jak to działa?​

  1. Zapisujesz w konfiguracji swojej aplikacji hash SPKI klucza publicznego serwera API Paymentic
  2. Przy każdym połączeniu TLS Twoja aplikacja liczy SHA-256 z SPKI certyfikatu prezentowanego przez serwer i porównuje z zapisanym pinem
  3. Jeśli pin się zgadza, połączenie jest kontynuowane
  4. Jeśli pin się nie zgadza, połączenie jest natychmiast przerywane — nawet jeśli certyfikat jest podpisany przez zaufany urząd certyfikacji

Wartości do Certificate Pinning​

Środowisko produkcyjne​

SPKI (SHA-256, Base64) api.paymentic.com:

xxx9PnZsipChLPI3SbJxQ7AAF1B/JWyeT0AJ2A3FfWc=
RsFFgzVxEeRLzmkKvysFtRJmaxe0xB4L7+BzNWXNw74=
ZadpKX9TholfNjrzBRnqAMEvGKsSg7mUNrTzFS1YspA=

Środowisko sandbox​

SPKI (SHA-256, Base64) api.sandbox.paymentic.com:

bKe+lcLC8zh1jS+caIVxV0sitH2ysTCg2CM7lvWb6s0=

Jak samodzielnie zweryfikować pin​

Zanim zaczniesz używać powyższych wartości w produkcji, zalecamy samodzielne wyliczenie pinu z certyfikatu serwera i porównanie go z wartością powyżej. Do tego wystarczy OpenSSL:

openssl s_client -servername api.paymentic.com -connect api.paymentic.com:443 </dev/null 2>/dev/null \
  | openssl x509 -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256 -binary \
  | openssl enc -base64

Wynik powinien być identyczny z wartością pinu podaną powyżej dla danego środowiska. Jeżeli się różni — nie ignoruj tego, skontaktuj się z nami przed dalszą integracją.

Przykłady implementacji​

cURL​

curl --pinnedpubkey 'sha256//nQcbBTz5/I4nYfdTYrO/i4cN+FjVY/eTDIKa7E0+AKg=' \
  https://api.paymentic.com/endpoint

Jeśli pin się nie zgadza, cURL zwraca błąd curl: (90) SSL: public key does not match pinned public key i połączenie zostaje zerwane jeszcze przed wysłaniem żądania.

PHP (GuzzleHTTP)​

Guzzle nie ma natywnej opcji pinningu SPKI, ale ponieważ pod spodem używa libcurl, wystarczy przekazać CURLOPT_PINNEDPUBLICKEY przez opcję curl:

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://api.paymentic.com',
    'verify'   => true,
    'curl'     => [
        CURLOPT_PINNEDPUBLICKEY => 'sha256//xxx9PnZsipChLPI3SbJxQ7AAF1B/JWyeT0AJ2A3FfWc=',
    ],
]);

try {
    $response = $client->request('GET', '/endpoint');
} catch (\GuzzleHttp\Exception\RequestException $e) {
    echo $e->getMessage();
}

Uwaga: opcja curl wymaga, aby Guzzle używał CurlHandler lub CurlMultiHandler (domyślnie tak jest, gdy rozszerzenie cURL jest dostępne). Dla StreamHandler ta opcja jest ignorowana.

Polityka rotacji kluczy​

Nie rotujemy klucza publicznego przy standardowym odnowieniu certyfikatu — pin SPKI pozostaje stabilny. Rotację klucza planujemy i komunikujemy z odpowiednim wyprzedzeniem (co najmniej 30 dni) kanałami administracyjnymi. W okresie przejściowym udostępnimy zarówno stary, jak i nowy pin, abyś mógł skonfigurować obie wartości równolegle i uniknąć przerwy w integracji.

W konfiguracji produkcyjnej warto od razu przewidzieć możliwość zapięcia więcej niż jednego pinu — większość bibliotek (w tym libcurl) wspiera listę pinów rozdzielaną średnikiem:

curl --pinnedpubkey 'sha256//<pin>;sha256//<backup-pin>' https://api.paymentic.com/endpoint