KSeF API podpis XAdES – wymagania i rozwiązywanie problemów

Podpis XAdES (XML Advanced Electronic Signatures) jest wymagany do uwierzytelniania w KSeF API 2.0. Podpisany dokument AuthTokenRequest wysyła się do systemu, a po weryfikacji można odebrać token dostępowy. Prawidłowe sformatowanie podpisu jest kluczowe dla pomyślnej autoryzacji.

Co musisz wiedzieć o podpisach XAdES w KSeF

KSeF API 2.0 wymaga podpisu XAdES dla dokumentu AuthTokenRequest podczas uwierzytelniania. Podpis musi być zgodny z określonymi wymaganiami formatu i algorytmów.

Proces jest asynchroniczny: po wysłaniu podpisanego XML do systemu otrzymujesz tymczasowy token operacji oraz numer referencyjny. Na ich podstawie sprawdzasz status uwierzytelnienia, a po zakończeniu sukcesem odbierasz token dostępowy (accessToken) i token odświeżania (refreshToken).

Najczęstsze problemy z podpisami XAdES wynikają z nieprawidłowego formatu canonicalizacji, użycia niewłaściwych algorytmów skrótu lub błędów w strukturze XML podpisu.

Dokument AuthTokenRequest musi być podpisany kwalifikowanym podpisem elektronicznym lub pieczęcią kwalifikowaną w formacie XAdES zgodnym z wymaganiami KSeF. Do podpisu można użyć m.in. certyfikatu kwalifikowanego osoby lub firmy, Profilu Zaufanego (ePUAP) lub certyfikatu KSeF. W środowisku testowym dopuszcza się certyfikaty samopodpisane.

Więcej informacji (pełna lista dopuszczalnych formatów, transformat, profili XAdES i algorytmów) znajduje się w: https://github.com/CIRFMF/ksef-docs/blob/main/auth/podpis-xades.md .

Instrukcja krok po kroku

1. Przygotuj dokument AuthTokenRequest

Utwórz dokument XML zgodny ze schematem AuthTokenRequest zawierający challenge, ContextIdentifier (NIP) oraz SubjectIdentifierType. Dokument musi być w kodowaniu UTF-8 bez znaku BOM.

2. Wybierz algorytm canonicalizacji

Użyj algorytmu canonicalizacji XML: http://www.w3.org/2001/10/xml-exc-c14n# (Exclusive Canonicalization) lub http://www.w3.org/TR/2001/REC-xml-c14n-20010315 (Canonical XML 1.0). KSeF akceptuje oba warianty.

3. Skonfiguruj algorytm podpisu

Użyj algorytmu podpisu: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 dla certyfikatów RSA lub odpowiedniego algorytmu dla certyfikatów EC. Algorytm skrótu musi być SHA-256.

4. Podpisz dokument

Podpisz dokument kwalifikowanym podpisem elektronicznym lub pieczęcią kwalifikowaną. Upewnij się, że podpis zawiera wszystkie wymagane elementy:

  • SignedInfo
  • SignatureValue
  • KeyInfo z certyfikatem
  • XAdES QualifyingProperties

5. Zweryfikuj strukturę podpisu

Sprawdź, czy podpis zawiera wszystkie wymagane referencje: referencję do głównego dokumentu (URI="") z transformacją enveloped-signature oraz referencję do SignedProperties z typem http://uri.etsi.org/01903#SignedProperties.

6. Wyślij podpisany dokument do KSeF

Podpisany dokument XML wyślij do systemu KSeF przez endpoint POST /auth/xades-signature. W odpowiedzi otrzymasz tymczasowy token uwierzytelnienia (authenticationToken) oraz numer referencyjny (referenceNumber). Na ich podstawie sprawdzasz status operacji (GET /auth/{referenceNumber}), a po zakończeniu sukcesem odbierasz token dostępowy i token odświeżania (POST /auth/token/redeem).

Najczęstsze problemy i rozwiązania

Błąd 'Nieprawidłowa treść podpisu' (9105)

Sprawdź algorytm canonicalizacji i podpisu. Upewnij się, że używasz SHA-256 dla wszystkich skrótów. Dla certyfikatów RSA użyj algorytmu rsa-sha256, dla EC sprawdź konfigurację biblioteki podpisującej. Zweryfikuj, czy podpis nie zawiera nieprawidłowych znaków lub białych znaków w wartościach Base64.

Błąd walidacji certyfikatu

Upewnij się, że certyfikat jest kwalifikowany i ważny. Sprawdź, czy certyfikat zawiera odpowiednie rozszerzenia (keyUsage: digitalSignature, nonRepudiation). W środowisku testowym możesz użyć certyfikatów self-signed wygenerowanych zgodnie z wymaganiami KSeF.

Podpis działa z pliku .pfx, ale nie z magazynu Windows

Sprawdź, czy certyfikat jest zainstalowany jako certyfikat osobisty (nie komputerowy) w magazynie Windows. Upewnij się, że klucz prywatny jest dostępny i że używasz właściwego magazynu certyfikatów. Niektóre biblioteki wymagają dodatkowej konfiguracji dla certyfikatów z magazynu systemowego.

Błąd przy użyciu certyfikatów EC (krzywe eliptyczne)

Certyfikaty EC są wspierane, ale wymagają użycia krzywej secp256r1 (NIST P-256). Upewnij się, że biblioteka podpisująca poprawnie obsługuje ECDSA z SHA-256. Niektóre biblioteki (np. BouncyCastle) wymagają dodatkowej konfiguracji dla certyfikatów EC.

Różnice w formatowaniu XML między bibliotekami

Różne biblioteki mogą generować nieco różne formaty XML podpisu (np. obecność lub brak prefiksów namespace, kolejność atrybutów). KSeF akceptuje różne warianty, o ile są one zgodne ze standardem XAdES. Użyj canonicalizacji XML, aby znormalizować dokument przed podpisaniem.

Status uwierzytelniania długo pokazuje "w toku"

Na środowiskach przedprodukcyjnym i produkcyjnym system weryfikuje status certyfikatu u wystawcy (usługi OCSP/CRL). Do czasu otrzymania odpowiedzi status operacji może pozostawać "Uwierzytelnianie w toku" – to normalne i nie oznacza błędu. Odpytywanie statusu należy powtarzać do zakończenia. Aby uniknąć oczekiwania na weryfikację u dostawcy certyfikatu, zaleca się uwierzytelnianie certyfikatem KSeF – jego weryfikacja odbywa się wewnątrz systemu i następuje od razu.

Wymagania formatu XAdES dla KSeF

Podpis XAdES w KSeF musi zawierać: SignedInfo z canonicalization method (Exclusive Canonicalization lub Canonical XML 1.0), signature method (RSA-SHA256 dla RSA lub odpowiedni dla EC), referencję do dokumentu z transformacją enveloped-signature, referencję do SignedProperties, SignatureValue, KeyInfo z certyfikatem X.509 oraz XAdES QualifyingProperties z SignedSignatureProperties zawierającymi SigningTime i SigningCertificate.

Dopuszczalne formaty i profile XAdES

Zgodnie z oficjalną dokumentacją KSeF dopuszczalne formaty podpisu to otaczany (enveloped) i otaczający (enveloping). Podpis w formacie zewnętrznym (detached) nie jest akceptowany. Akceptowane profile XAdES:

  • XAdES-BES
  • XAdES-EPES
  • XAdES-T
  • XAdES-LT
  • XAdES-C
  • XAdES-X
  • XAdES-XL
  • XAdES-A
  • XAdES-ERS
  • XAdES-BASELINE-B
  • XAdES-BASELINE-T
  • XAdES-BASELINE-LT
  • XAdES-BASELINE-LTA

Dopuszczalne transformaty:

Pełna specyfikacja parametrów technicznych jest w: https://github.com/CIRFMF/ksef-docs/blob/main/auth/podpis-xades.md .

Algorytmy i standardy

Zgodnie z oficjalną dokumentacją KSeF (https://github.com/CIRFMF/ksef-docs/blob/main/auth/podpis-xades.md) algorytmy podpisu (ds:SignatureMethod) są następujące.

  • RSA, minimalna długość klucza 2048 bitów:
    • RSASSA-PKCS1-v1_5 – rsa-sha1, rsa-sha256, rsa-sha384, rsa-sha512
    • RSASSA-PSS – sha1-rsa-MGF1, sha256-rsa-MGF1, sha384-rsa-MGF1, sha512-rsa-MGF1, sha3-256-rsa-MGF1, sha3-384-rsa-MGF1, sha3-512-rsa-MGF1
  • ECDSA, minimalny rozmiar krzywej 256 bitów:
    • ecdsa-sha1, ecdsa-sha256, ecdsa-sha384, ecdsa-sha512, ecdsa-sha3-256, ecdsa-sha3-384, ecdsa-sha3-512
    • wartość SignatureValue w ECDSA kodowana jest jako R||S zgodnie z XMLDSIG 1.1 / RFC 4050

Algorytmy skrótu (DigestMethod w referencjach i w SigningCertificate): sha1, sha256, sha384, sha512, sha3-256, sha3-384, sha3-512. Uwaga bezpieczeństwa: algorytmy oparte na SHA-1 (np. sha1, rsa-sha1, ecdsa-sha1) są w dokumentacji KSeF dopuszczone, ale uznawane za przestarzałe i podatne na kolizje; nie powinny być używane w środowiskach produkcyjnych. Zalecane są SHA-256 i mocniejsze. KSeF wymaga m.in. SHA-256 oraz RSA-SHA256 dla RSA; canonicalizacja XML: Exclusive Canonicalization lub Canonical XML 1.0. Standard XAdES zgodny z ETSI TS 101 903.

Certyfikaty kwalifikowane vs self-signed

Dozwolone typy certyfikatów w podpisie XAdES: certyfikat kwalifikowany osoby fizycznej (z PESEL lub NIP osoby uprawnionej do działania w imieniu firmy), certyfikat kwalifikowany organizacji – pieczęć firmowa (z NIP), Profil Zaufany (ePUAP) – dla osób fizycznych, certyfikat wewnętrzny KSeF (wystawiany przez system KSeF; nie jest kwalifikowany, ale honorowany przy uwierzytelnianiu). Certyfikat kwalifikowany to certyfikat wydany przez kwalifikowanego dostawcę usług zaufania z rejestru EU Trusted List (eIDAS), akceptowane są certyfikaty z Polski i UE. Dla certyfikatów podpisu kwalifikowanego (osoba fizyczna) wymagane atrybuty podmiotu to:

  • givenName (2.5.4.42)
  • surname (2.5.4.4)
  • serialNumber (2.5.4.5) – wzorce PNOPL/PESEL lub TINPL/NIP z 11 lub 10 cyframi
  • commonName (2.5.4.3)
  • countryName (2.5.4.6)

Dla pieczęci kwalifikowanej (organizacja): organizationName (2.5.4.10), organizationIdentifier (2.5.4.97) – wzorzec VATPL + 10 cyfr NIP, commonName, countryName; niedopuszczalne są givenName i surname. Certyfikaty kwalifikowane bez właściwych identyfikatorów w OID 2.5.4.5 można uwierzytelnić po nadaniu uprawnień na skrót SHA-256 (odcisk palca) certyfikatu. W środowisku testowym i demo dopuszcza się certyfikaty self-signed (RSA 2048 bitów lub EC secp256r1, z odpowiednimi rozszerzeniami i organizationIdentifier).

Wysłanie podpisanego dokumentu i dalszy przebieg

Podpisany dokument AuthTokenRequest wysyła się do KSeF przez endpoint POST /auth/xades-signature. W odpowiedzi system zwraca tymczasowy token operacji (authenticationToken) oraz numer referencyjny (referenceNumber). Status uwierzytelnienia sprawdza się asynchronicznie (GET /auth/{referenceNumber} z tokenem w nagłówku Authorization). Po zakończeniu operacji sukcesem token dostępowy i token odświeżania odbiera się jednorazowo przez POST /auth/token/redeem. Na środowiskach przedprodukcyjnym i produkcyjnym system weryfikuje ponadto status certyfikatu u wystawcy – do otrzymania odpowiedzi status może pozostawać "Uwierzytelnianie w toku".

Rozwiązywanie problemów z bibliotekami

Różne biblioteki (BouncyCastle, node-forge, SecureBlackBox, OpenSSL) mogą wymagać różnych konfiguracji. Dla BouncyCastle upewnij się, że używasz właściwego providera i algorytmów. Dla node-forge sprawdź konfigurację RSA-OAEP. Dla bibliotek .NET sprawdź użycie SignedXml z odpowiednimi ustawieniami canonicalizacji.

FAQ

Jakie algorytmy są wymagane dla podpisu XAdES w KSeF?

KSeF wymaga algorytmu skrótu SHA-256 oraz algorytmu podpisu RSA-SHA256 dla certyfikatów RSA. Dla certyfikatów EC wymagany jest algorytm ECDSA z SHA-256. Canonicalizacja może być Exclusive Canonicalization lub Canonical XML 1.0.

Czy mogę użyć podpisu XAdES z certyfikatem EC?

Tak, KSeF wspiera certyfikaty EC z krzywą secp256r1 (NIST P-256). Wymagane jest użycie algorytmu ECDSA z SHA-256. Niektóre biblioteki mogą wymagać dodatkowej konfiguracji dla certyfikatów EC.

Dlaczego podpis działa z pliku .pfx, ale nie z magazynu Windows?

Certyfikat musi być zainstalowany jako certyfikat osobisty (CurrentUser\My), nie komputerowy. Niektóre biblioteki wymagają dodatkowej konfiguracji do dostępu do klucza prywatnego z magazynu systemowego. Sprawdź uprawnienia i konfigurację biblioteki podpisującej.

Jak zweryfikować, czy podpis XAdES jest poprawny?

Możesz zweryfikować podpis lokalnie przed wysłaniem do KSeF używając narzędzi do walidacji XAdES lub bibliotek kryptograficznych. Sprawdź strukturę XML, obecność wszystkich wymaganych elementów, poprawność skrótów i podpisu cyfrowego. KSeF zwróci szczegółowy błąd, jeśli podpis jest nieprawidłowy.

Czy różnice w formatowaniu XML między bibliotekami są problemem?

Nie, KSeF akceptuje różne warianty formatowania XML podpisu, o ile są one zgodne ze standardem XAdES. Canonicalizacja XML normalizuje dokument, więc różnice w białych znakach, kolejności atrybutów czy prefiksach namespace nie powinny powodować problemów.

Co robić po podpisaniu dokumentu AuthTokenRequest?

Podpisany dokument XML wyślij do KSeF przez POST /auth/xades-signature. Z odpowiedzi weź authenticationToken i referenceNumber. Używając ich, sprawdzaj status operacji (GET /auth/{referenceNumber}). Gdy status wskaże zakończenie sukcesem, wywołaj POST /auth/token/redeem z authenticationToken, aby jednorazowo odebrać accessToken i refreshToken.

Czy podpis XAdES w formacie detached (zewnętrzny) jest akceptowany?

Nie. KSeF akceptuje tylko format otaczany (enveloped) i otaczający (enveloping). Podpis w formacie zewnętrznym (detached) nie jest akceptowany.

Czy mogę uwierzytelnić się certyfikatem bez numeru PESEL/NIP w atrybucie serialNumber?

Dla certyfikatów kwalifikowanych bez właściwych identyfikatorów w atrybucie podmiotu OID 2.5.4.5 możliwe jest uwierzytelnienie po uprzednim nadaniu uprawnień na skrót SHA-256 (odcisk palca) tego certyfikatu. Szczegóły w dokumentacji uwierzytelniania KSeF.

Powiązane tematy

Przydatne serwisy

Status i komunikaty

API i narzędzia

Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.

Dalsze korzystanie z tej witryny oznacza akceptację Polityki prywatności . Używamy plików cookie, aby zapewnić najlepszą jakość korzystania z naszej witryny internetowej. Przeczytaj naszą Politykę plików cookie .
Akceptuj Odrzuć