KSeF API generowanie certyfikatu testowego
Java.Generowanie certyfikatów testowych dla KSeF
W środowisku testowym i demo KSeF możesz używać certyfikatów self-signed wygenerowanych lokalnie. Certyfikaty muszą spełniać określone wymagania dotyczące algorytmu, rozmiaru klucza i rozszerzeń.
Certyfikaty testowe mogą być generowane za pomocą PowerShell (Windows), OpenSSL (Linux/Mac/Windows) lub bibliotek Java. Każda metoda wymaga odpowiedniej konfiguracji parametrów.
Certyfikaty wygenerowane dla środowiska testowego nie działają w środowisku produkcyjnym, gdzie wymagane są kwalifikowane podpisy elektroniczne lub pieczęcie kwalifikowane.
Instrukcja krok po kroku
1. Wybierz narzędzie do generowania
Wybierz narzędzie: PowerShell dla Windows, OpenSSL dla wszystkich platform lub biblioteki Java (BouncyCastle, keytool). Każde narzędzie wymaga odpowiedniej konfiguracji.
2. Przygotuj parametry certyfikatu
Dla RSA: długość klucza 2048 bitów. Dla EC: krzywa secp256r1 (prime256v1). Certyfikat musi zawierać: organizationIdentifier z NIP (format VATPL-XXXXXXXXXX), keyUsage (digitalSignature, nonRepudiation, keyEncipherment), extendedKeyUsage (clientAuth).
3. Wygeneruj certyfikat
Użyj wybranego narzędzia do wygenerowania certyfikatu z odpowiednimi parametrami. Zapisz certyfikat w formacie .pfx (PKCS#12) z hasłem lub w formacie PEM z kluczem prywatnym.
4. Zweryfikuj certyfikat
Sprawdź, czy certyfikat zawiera wszystkie wymagane rozszerzenia i czy klucz ma odpowiednią długość. Przetestuj certyfikat w środowisku testowym KSeF.
Najczęstsze problemy i rozwiązania
Certyfikat wygenerowany w PowerShell nie działa
Sprawdź, czy używasz właściwego formatu organizationIdentifier (VATPL-XXXXXXXXXX) i czy certyfikat zawiera wszystkie wymagane rozszerzenia. Upewnij się, że używasz algorytmu SHA-256 i że klucz ma odpowiednią długość (2048 bitów dla RSA lub secp256r1 dla EC).
Błąd przy generowaniu certyfikatu w OpenSSL
Sprawdź konfigurację OpenSSL (plik .cnf) i upewnij się, że zawiera wszystkie wymagane sekcje: req_distinguished_name z organizationIdentifier, v3_req z keyUsage i extendedKeyUsage. Zweryfikuj, czy używasz właściwego algorytmu i długości klucza.
Certyfikat działa z pliku .pfx, ale nie po instalacji w Windows
Upewnij się, że certyfikat jest zainstalowany jako certyfikat osobisty (CurrentUser\My), nie komputerowy. Sprawdź, czy klucz prywatny jest dostępny i czy certyfikat ma odpowiednie uprawnienia. Niektóre biblioteki wymagają dodatkowej konfiguracji dla certyfikatów z magazynu systemowego.
Różnice między certyfikatami wygenerowanymi różnymi narzędziami
Różne narzędzia mogą generować nieco różne formaty certyfikatów, ale wszystkie powinny działać, jeśli spełniają wymagania KSeF. Główne różnice mogą dotyczyć kolejności atrybutów w distinguished name lub formatowania rozszerzeń. KSeF akceptuje różne warianty, o ile są zgodne ze standardem X.509.
Generowanie certyfikatu w PowerShell
Użyj polecenia New-SelfSignedCertificate z odpowiednimi parametrami:
New-SelfSignedCertificate `
-Subject "O=Test KSeF, OID.2.5.4.97=VATPL-XXXXXXXXXX, CN=Test KSeF, C=PL" `
-KeyAlgorithm RSA `
-KeyLength 2048 `
-HashAlgorithm `SHA`256 `
-KeyExportPolicy Exportable `
-CertStoreLocation "Cert:\CurrentUser\My" `
-NotAfter (Get-Date).AddYears(5) `
-TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3,1.3.6.1.4.1.311.10.3.13")
Dla certyfikatów EC użyj -KeyAlgorithm ECDSA i -Curve secp256r1.
Generowanie certyfikatu w OpenSSL
Przygotuj plik konfiguracyjny openssl.cnf z sekcjami [req], [req_distinguished_name] i [v3_req]. Użyj polecenia:
openssl req -new -x509 -keyout key.pem -out cert.pem -days 365 -nodes -config openssl.cnf
Plik konfiguracyjny musi zawierać organizationIdentifier w formacie VATPL-XXXXXXXXXX oraz odpowiednie rozszerzenia keyUsage i extendedKeyUsage.
Generowanie certyfikatu w Java
Użyj biblioteki BouncyCastle lub keytool. Dla BouncyCastle przygotuj generator certyfikatu z odpowiednimi parametrami: algorytm RSA (2048 bitów) lub EC (secp256r1), rozszerzenia keyUsage i extendedKeyUsage, oraz organizationIdentifier w distinguished name. Eksportuj certyfikat do formatu PKCS#12 (.pfx) z hasłem.
Wymagane rozszerzenia certyfikatu
Certyfikat testowy dla KSeF musi zawierać: organizationIdentifier (OID 2.5.4.97) z wartością w formacie VATPL-XXXXXXXXXX, keyUsage z wartościami digitalSignature, nonRepudiation, keyEncipherment, extendedKeyUsage z wartością clientAuth (1.3.6.1.5.5.7.3.2), oraz opcjonalnie TextExtension z wartościami 1.3.6.1.5.5.7.3.3 i 1.3.6.1.4.1.311.10.3.13.
FAQ
Jak wygenerować certyfikat testowy dla KSeF w PowerShell?
Użyj polecenia New-SelfSignedCertificate z parametrami: -Subject zawierający OID.2.5.4.97=VATPL-XXXXXXXXXX, -KeyAlgorithm RSA (lub ECDSA dla EC), -KeyLength 2048 (lub -Curve secp256r1 dla EC), -HashAlgorithm SHA256, oraz -TextExtension z odpowiednimi wartościami OID. Certyfikat zapisz w magazynie CurrentUser\My.
Jak wygenerować certyfikat testowy w OpenSSL?
Przygotuj plik konfiguracyjny openssl.cnf z sekcjami [req], [req_distinguished_name] zawierającą organizationIdentifier, oraz [v3_req] z keyUsage i extendedKeyUsage. Użyj polecenia openssl req z parametrami -new -x509 -keyout -out -config. Upewnij się, że używasz algorytmu SHA-256 i odpowiedniej długości klucza.
Czy certyfikaty testowe działają w środowisku produkcyjnym?
Nie, certyfikaty testowe (self-signed) działają tylko w środowisku testowym i demo KSeF. W środowisku produkcyjnym wymagane są kwalifikowane podpisy elektroniczne lub pieczęcie kwalifikowane wydawane przez kwalifikowanych dostawców usług zaufania.
Jakie są wymagania dotyczące organizationIdentifier?
organizationIdentifier (OID 2.5.4.97) musi zawierać wartość w formacie VATPL-XXXXXXXXXX, gdzie XXXXXXXXXX to numer NIP podmiotu. Wartość musi być poprzedzona prefiksem VATPL- i zawierać 10 cyfr NIP.
Czy mogę użyć tego samego certyfikatu dla wielu podmiotów?
Nie, każdy certyfikat jest powiązany z konkretnym numerem NIP poprzez organizationIdentifier. Dla każdego podmiotu należy wygenerować osobny certyfikat z odpowiednim NIP w organizationIdentifier.