Jak skonfigurować BouncyCastle do podpisywania dokumentów XAdES dla KSeF API?

KSeF API integracja z BouncyCastle

BouncyCastle to popularna biblioteka kryptograficzna dla Java używana do podpisywania dokumentów XAdES w KSeF API. Nieprawidłowa konfiguracja może powodować błędy walidacji podpisu.

Integracja BouncyCastle z KSeF API

BouncyCastle to biblioteka kryptograficzna dla Java często używana do podpisywania dokumentów XAdES w KSeF API 2.0. Biblioteka wymaga odpowiedniej konfiguracji dla certyfikatów RSA i EC oraz algorytmów podpisu.

Typowe problemy z BouncyCastle dotyczą: nieprawidłowej konfiguracji dla certyfikatów EC (krzywe eliptyczne), użycia niewłaściwych algorytmów podpisu, problemów z canonicalizacją XML oraz formatowaniem podpisu XAdES.

BouncyCastle 1.76 i nowsze wersje wspierają certyfikaty EC, ale wymagają dodatkowej konfiguracji. Dla certyfikatów RSA biblioteka działa zazwyczaj bez problemów, ale dla EC może wymagać użycia właściwego providera i algorytmów.

Instrukcja krok po kroku

1. Zainstaluj BouncyCastle

Zainstaluj bibliotekę BouncyCastle (wersja 1.76 lub nowsza) w projekcie Java. BouncyCastle jest dostępna jako zależność Maven lub można pobrać JAR bezpośrednio. Upewnij się, że używasz kompatybilnej wersji z wersją Java.

2. Skonfiguruj provider kryptograficzny

Skonfiguruj BouncyCastle jako provider kryptograficzny w aplikacji Java. Dla certyfikatów EC może być konieczne użycie właściwego providera (BCProvider lub BCECProvider). Sprawdź dokumentację BouncyCastle dotyczącą konfiguracji providera.

3. Skonfiguruj algorytmy podpisu

Skonfiguruj algorytmy podpisu zgodnie z wymaganiami KSeF: dla certyfikatów RSA użyj algorytmu RSA-SHA256, dla certyfikatów EC użyj algorytmu ECDSA z SHA-256. Upewnij się, że używasz właściwego algorytmu dla wybranego typu certyfikatu.

4. Przetestuj podpis

Przetestuj podpis w środowisku testowym KSeF. Jeśli otrzymujesz błąd 'Nieprawidłowa treść podpisu' (9105), sprawdź konfigurację: algorytm canonicalizacji, algorytm podpisu, format XAdES, provider kryptograficzny. Dla certyfikatów EC może być konieczna dodatkowa konfiguracja.

Najczęstsze problemy i rozwiązania

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

Certyfikaty EC wymagają dodatkowej konfiguracji w BouncyCastle. Upewnij się, że używasz właściwego providera (BCECProvider dla EC), algorytmu ECDSA z SHA-256 oraz krzywej secp256r1. Sprawdź dokumentację BouncyCastle dotyczącą podpisywania z certyfikatami EC. Niektóre wersje BouncyCastle mogą wymagać dodatkowej konfiguracji.

RSA działa, ale EC nie

To częsty problem wynikający z nieprawidłowej konfiguracji BouncyCastle dla certyfikatów EC. Sprawdź, czy używasz właściwego providera (BCECProvider), algorytmu ECDSA z SHA-256 oraz krzywej secp256r1. Dla certyfikatów RSA użyj algorytmu RSA-SHA256. Sprawdź dokumentację BouncyCastle dotyczącą różnic między RSA a EC.

Problemy z canonicalizacją XML

BouncyCastle wymaga poprawnej konfiguracji canonicalizacji XML. Użyj algorytmu Exclusive Canonicalization (http://www.w3.org/2001/10/xml-exc-c14n#) lub Canonical XML 1.0. Sprawdź, czy canonicalizacja jest wykonywana przed podpisaniem. Nieprawidłowa canonicalizacja może powodować błędy walidacji podpisu.

Różnice między wersjami BouncyCastle

Różne wersje BouncyCastle mogą wymagać różnych konfiguracji. BouncyCastle 1.76 i nowsze wersje wspierają certyfikaty EC, ale mogą wymagać dodatkowej konfiguracji. Sprawdź dokumentację BouncyCastle dla konkretnej wersji. Zaleca się użycie najnowszej stabilnej wersji BouncyCastle.

Konfiguracja BouncyCastle dla RSA

Dla certyfikatów RSA BouncyCastle działa zazwyczaj bez problemów. Użyj algorytmu RSA-SHA256 (http://www.w3.org/2001/04/xmldsig-more#rsa-sha256) oraz standardowego providera BouncyCastle. Certyfikat RSA musi mieć długość klucza 2048 bitów. Sprawdź dokumentację BouncyCastle dotyczącą podpisywania z certyfikatami RSA.

Konfiguracja BouncyCastle dla EC

Dla certyfikatów EC BouncyCastle wymaga dodatkowej konfiguracji. Użyj właściwego providera (BCECProvider dla EC), algorytmu ECDSA z SHA-256 oraz krzywej secp256r1 (NIST P-256). Certyfikat EC musi używać krzywej secp256r1. Sprawdź dokumentację BouncyCastle dotyczącą podpisywania z certyfikatami EC. Niektóre wersje BouncyCastle mogą wymagać dodatkowej konfiguracji.

Algorytmy i canonicalizacja

BouncyCastle wymaga poprawnej konfiguracji algorytmów i canonicalizacji: algorytm skrótu SHA-256, algorytm podpisu RSA-SHA256 (dla RSA) lub ECDSA-SHA256 (dla EC), canonicalizacja XML (Exclusive Canonicalization lub Canonical XML 1.0). Nieprawidłowa konfiguracja może powodować błędy walidacji podpisu. Sprawdź dokumentację BouncyCastle dotyczącą algorytmów.

Typowe błędy i rozwiązania

Typowe błędy: 'Nieprawidłowa treść podpisu' (9105) - sprawdź konfigurację algorytmów i canonicalizacji, problemy z certyfikatami EC - użyj właściwego providera i algorytmu, różnice między wersjami BouncyCastle - sprawdź dokumentację dla konkretnej wersji. Zaleca się użycie najnowszej stabilnej wersji BouncyCastle i przetestowanie w środowisku testowym KSeF.

FAQ

Jak skonfigurować BouncyCastle dla KSeF API?

Zainstaluj BouncyCastle (wersja 1.76 lub nowsza), skonfiguruj provider kryptograficzny (BCProvider dla RSA, BCECProvider dla EC), skonfiguruj algorytmy podpisu (RSA-SHA256 dla RSA, ECDSA-SHA256 dla EC), użyj właściwej canonicalizacji XML. Przetestuj podpis w środowisku testowym KSeF. Sprawdź dokumentację BouncyCastle dla szczegółów konfiguracji.

Dlaczego certyfikaty EC nie działają z BouncyCastle?

Jakie algorytmy są wymagane dla BouncyCastle?

Dla certyfikatów RSA użyj algorytmu RSA-SHA256 (http://www.w3.org/2001/04/xmldsig-more#rsa-sha256). Dla certyfikatów EC użyj algorytmu ECDSA z SHA-256. Algorytm skrótu musi być SHA-256. Canonicalizacja XML: Exclusive Canonicalization lub Canonical XML 1.0. Sprawdź dokumentację BouncyCastle dotyczącą algorytmów.

Która wersja BouncyCastle jest zalecana?

Zaleca się użycie najnowszej stabilnej wersji BouncyCastle (1.76 lub nowsza). Różne wersje mogą wymagać różnych konfiguracji, szczególnie dla certyfikatów EC. Sprawdź dokumentację BouncyCastle dla konkretnej wersji. Przetestuj konfigurację w środowisku testowym KSeF przed użyciem w produkcji.

Różnice między RSA a EC w BouncyCastle

Dla certyfikatów RSA BouncyCastle działa zazwyczaj bez problemów z standardowym providerem. Dla certyfikatów EC wymagany jest BCECProvider i dodatkowa konfiguracja. Algorytmy są różne: RSA-SHA256 dla RSA, ECDSA-SHA256 dla EC. Sprawdź dokumentację BouncyCastle dotyczącą różnic między RSA a EC.