KSeF API certyfikaty szyfrowania – KsefTokenEncryption vs SymmetricKeyEncryption
Certyfikaty szyfrowania w KSeF API
KSeF API 2.0 wykorzystuje certyfikaty publiczne do szyfrowania danych przesyłanych między aplikacją a systemem KSeF. System używa dwóch typów certyfikatów, każdy do innego celu: KsefTokenEncryption do szyfrowania tokenów sesji oraz SymmetricKeyEncryption do szyfrowania kluczy symetrycznych używanych do szyfrowania faktur.
Certyfikaty są dostępne przez endpoint GET /api/v2/security/public-key-certificates i zawierają informację o przeznaczeniu w polu usage. Każdy certyfikat może mieć jedno lub więcej przeznaczeń wskazanych w tablicy usage.
Certyfikaty są regularnie rotowane przez Ministerstwo Finansów w celu zapewnienia bezpieczeństwa. Aplikacje powinny pobierać aktualne certyfikaty przed każdym szyfrowaniem lub regularnie aktualizować przechowywane certyfikaty.
W środowiskach testowych i demo dostępne są oba typy certyfikatów. W środowisku produkcyjnym certyfikaty będą dostępne od 1 lutego 2026 r.
Instrukcja krok po kroku
1. Pobierz certyfikaty z endpointu API
Wywołaj endpoint GET /api/v2/security/public-key-certificates dla odpowiedniego środowiska: https://ksef-test.mf.gov.pl/api/v2/security/public-key-certificates (test), https://ksef-demo.mf.gov.pl/api/v2/security/public-key-certificates (demo), https://ksef.mf.gov.pl/api/v2/security/public-key-certificates (produkcja). Endpoint zwraca listę certyfikatów w formacie JSON.
2. Zidentyfikuj typ certyfikatu po polu usage
Każdy certyfikat w odpowiedzi zawiera pole usage z tablicą wartości wskazujących przeznaczenie: ["KsefTokenEncryption"] dla szyfrowania tokenów, ["SymmetricKeyEncryption"] dla szyfrowania kluczy symetrycznych. Wybierz certyfikat z odpowiednim typem usage dla Twojego przypadku użycia.
3. Użyj KsefTokenEncryption do szyfrowania tokenów
Certyfikat z usage ["KsefTokenEncryption"] służy do szyfrowania tokenów KSeF przed wysłaniem do API. Użyj klucza publicznego z tego certyfikatu do zaszyfrowania tokena w formacie token|timestamp algorytmem RSA-OAEP z SHA-256. Zaszyfrowany token wyślij w polu encryptedToken do endpointu POST /api/v2/auth/ksef-token.
4. Użyj SymmetricKeyEncryption do szyfrowania kluczy AES
Certyfikat z usage ["SymmetricKeyEncryption"] służy do szyfrowania kluczy symetrycznych AES używanych do szyfrowania faktur w sesjach interaktywnych i wsadowych. Wygeneruj losowy klucz AES-256 i IV, zaszyfruj klucz AES używając klucza publicznego z certyfikatu algorytmem RSA-OAEP, wyślij zaszyfrowany klucz w polu encryptedSymmetricKey przy tworzeniu sesji.
5. Obsłuż rotację certyfikatów
Certyfikaty są regularnie rotowane przez MF. Implementuj mechanizm aktualizacji certyfikatów: pobieraj certyfikaty przed każdym szyfrowaniem lub regularnie aktualizuj przechowywane certyfikaty (np. raz dziennie). Sprawdzaj daty ważności certyfikatów i obsługuj sytuacje, gdy certyfikat wygasł lub został zmieniony.
Najczęstsze problemy i rozwiązania
W produkcji widzę tylko jeden certyfikat pod /security/pem
Endpoint /security/pem to stary endpoint dla środowiska produkcyjnego KSeF 1.0. W KSeF API 2.0 użyj endpointu GET /api/v2/security/public-key-certificates, który zwraca listę certyfikatów z informacją o usage. W środowisku produkcyjnym certyfikaty będą dostępne od 1 lutego 2026 r.
Nie widzę certyfikatów w środowisku produkcyjnym
Certyfikaty w środowisku produkcyjnym będą dostępne od 1 lutego 2026 r. Do tego czasu używaj środowiska testowego lub demo do testowania integracji. Sprawdź komunikaty techniczne MF dotyczące dostępności certyfikatów produkcyjnych.
Który certyfikat użyć do szyfrowania tokena?
Użyj certyfikatu z usage ["KsefTokenEncryption"] do szyfrowania tokenów KSeF. Certyfikat z usage ["SymmetricKeyEncryption"] służy do szyfrowania kluczy symetrycznych AES. Sprawdź pole usage w odpowiedzi z endpointu /v2/security/public-key-certificates, aby zidentyfikować właściwy certyfikat.
Certyfikat wygasł lub został zmieniony
Certyfikaty są regularnie rotowane. Pobierz aktualne certyfikaty z endpointu GET /api/v2/security/public-key-certificates. Implementuj mechanizm automatycznej aktualizacji certyfikatów (np. raz dziennie) lub pobieraj certyfikaty przed każdym szyfrowaniem. Sprawdzaj daty ważności certyfikatów w odpowiedzi API.
Różnice między KsefTokenEncryption a SymmetricKeyEncryption
KsefTokenEncryption służy wyłącznie do szyfrowania tokenów KSeF w procesie uwierzytelniania. Token jest szyfrowany w formacie token|timestamp algorytmem RSA-OAEP z SHA-256. SymmetricKeyEncryption służy do szyfrowania kluczy symetrycznych AES używanych do szyfrowania faktur w sesjach. Klucz AES jest szyfrowany algorytmem RSA-OAEP przed wysłaniem do KSeF. Oba typy certyfikatów używają tego samego algorytmu szyfrowania (RSA-OAEP), ale służą do różnych celów.
Endpoint public-key-certificates
Endpoint GET /api/v2/security/public-key-certificates zwraca listę certyfikatów publicznych w formacie JSON. Każdy certyfikat zawiera: pole usage z tablicą przeznaczeń (["KsefTokenEncryption"], ["SymmetricKeyEncryption"]), certyfikat w formacie PEM lub Base64, daty ważności. Adresy endpointów: test - https://ksef-test.mf.gov.pl/api/v2/security/public-key-certificates, demo - https://ksef-demo.mf.gov.pl/api/v2/security/public-key-certificates, produkcja - https://ksef.mf.gov.pl/api/v2/security/public-key-certificates (od 1 lutego 2026 r.).
Rotacja certyfikatów
Certyfikaty są regularnie rotowane przez Ministerstwo Finansów w celu zapewnienia bezpieczeństwa. Rotacja może nastąpić bez wcześniejszego powiadomienia, dlatego aplikacje powinny: pobierać certyfikaty przed każdym szyfrowaniem (zalecane) lub regularnie aktualizować przechowywane certyfikaty (np. raz dziennie), sprawdzać daty ważności certyfikatów, obsługiwać sytuacje, gdy certyfikat wygasł lub został zmieniony, logować informacje o rotacji certyfikatów dla celów diagnostycznych. Szczegóły dotyczące rotacji certyfikatów są dostępne w GitHub issue #221 repozytorium CIRFMF/ksef-docs.
Format odpowiedzi z endpointu
Endpoint zwraca tablicę obiektów certyfikatów. Każdy obiekt zawiera: usage - tablica stringów wskazujących przeznaczenie certyfikatu (["KsefTokenEncryption"], ["SymmetricKeyEncryption"]), certificate - certyfikat w formacie PEM lub Base64, validFrom - data rozpoczęcia ważności, validTo - data zakończenia ważności (jeśli dostępne). Przykład odpowiedzi: [{"usage": ["KsefTokenEncryption"], "certificate": "-----BEGIN CERTIFICATE-----..."}, {"usage": ["SymmetricKeyEncryption"], "certificate": "-----BEGIN CERTIFICATE-----..."}].
FAQ
Jaka jest różnica między KsefTokenEncryption a SymmetricKeyEncryption?
KsefTokenEncryption służy do szyfrowania tokenów KSeF w procesie uwierzytelniania. SymmetricKeyEncryption służy do szyfrowania kluczy symetrycznych AES używanych do szyfrowania faktur w sesjach. Oba używają algorytmu RSA-OAEP, ale służą do różnych celów.
Gdzie pobrać certyfikaty szyfrowania?
Certyfikaty są dostępne przez endpoint GET /api/v2/security/public-key-certificates dla odpowiedniego środowiska: test - https://ksef-test.mf.gov.pl/api/v2/security/public-key-certificates, demo - https://ksef-demo.mf.gov.pl/api/v2/security/public-key-certificates, produkcja - https://ksef.mf.gov.pl/api/v2/security/public-key-certificates (od 1 lutego 2026 r.).
Jak zidentyfikować typ certyfikatu?
Każdy certyfikat w odpowiedzi z endpointu zawiera pole usage z tablicą wartości wskazujących przeznaczenie: ["KsefTokenEncryption"] dla szyfrowania tokenów, ["SymmetricKeyEncryption"] dla szyfrowania kluczy symetrycznych. Wybierz certyfikat z odpowiednim typem usage dla Twojego przypadku użycia.
Czy certyfikaty są rotowane?
Tak, certyfikaty są regularnie rotowane przez Ministerstwo Finansów. Aplikacje powinny pobierać aktualne certyfikaty przed każdym szyfrowaniem lub regularnie aktualizować przechowywane certyfikaty. Szczegóły dotyczące rotacji są dostępne w GitHub issue #221 repozytorium CIRFMF/ksef-docs.
Dlaczego w produkcji widzę tylko jeden certyfikat?
Endpoint /security/pem to stary endpoint dla KSeF 1.0. W KSeF API 2.0 użyj endpointu GET /api/v2/security/public-key-certificates, który zwraca listę certyfikatów z informacją o usage. W środowisku produkcyjnym certyfikaty będą dostępne od 1 lutego 2026 r.