KSeF API podpis XAdES – wymagania i rozwiązywanie problemów
XAdES (XML Advanced Electronic Signatures) jest wymagany do uwierzytelniania w KSeF API 2.0. 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.
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.
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 oraz 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.
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.
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.
Algorytmy i standardy
KSeF wymaga: algorytmu skrótu SHA-256 (http://www.w3.org/2001/04/xmlenc#sha256), algorytmu podpisu RSA-SHA256 dla certyfikatów RSA (http://www.w3.org/2001/04/xmldsig-more#rsa-sha256), canonicalizacji XML (Exclusive Canonicalization lub Canonical XML 1.0), oraz standardu XAdES w wersji zgodnej z ETSI TS 101 903.
Certyfikaty kwalifikowane vs self-signed
W środowisku produkcyjnym wymagany jest kwalifikowany podpis elektroniczny lub pieczęć kwalifikowana. W środowisku testowym i demo można używać certyfikatów self-signed wygenerowanych zgodnie z wymaganiami KSeF (RSA 2048 bitów lub EC secp256r1, z odpowiednimi rozszerzeniami i OID organizationIdentifier).
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.