KSeF API sesja interaktywna – szyfrowanie AES (encryptedKey vs encryptedSymmetricKey)

Szyfrowanie AES w sesji interaktywnej

Sesja interaktywna w KSeF API 2.0 wymaga szyfrowania faktur algorytmem AES-256-CBC przed wysłaniem. Proces składa się z kilku etapów: wygenerowanie klucza AES i IV, zaszyfrowanie klucza AES kluczem publicznym KSeF (RSA-OAEP), utworzenie sesji z zaszyfrowanym kluczem, odszyfrowanie klucza AES (lokalnie), zaszyfrowanie faktury kluczem AES.

Częstym błędem jest użycie encryptedSymmetricKey (zaszyfrowanego klucza otrzymanego z sesji) bezpośrednio do szyfrowania faktury. encryptedSymmetricKey to klucz AES zaszyfrowany algorytmem RSA-OAEP, który musi być najpierw odszyfrowany, aby uzyskać oryginalny klucz AES do szyfrowania faktury.

Proces szyfrowania: wygeneruj losowy klucz AES-256 (32 bajty) i IV (16 bajtów), zaszyfruj klucz AES kluczem publicznym KSeF (RSA-OAEP) - to daje encryptedSymmetricKey, utwórz sesję z encryptedSymmetricKey i IV, odszyfruj encryptedSymmetricKey lokalnie (używając własnego klucza prywatnego), aby uzyskać oryginalny klucz AES, zaszyfruj fakturę algorytmem AES-256-CBC używając odszyfrowanego klucza AES i IV.

Typowe błędy: użycie encryptedSymmetricKey bezpośrednio do szyfrowania faktury (zamiast odszyfrowanego klucza AES), nieprawidłowy format IV (wymagane 16 bajtów), nieprawidłowe kodowanie Base64, nieprawidłowy algorytm szyfrowania (wymagane AES-256-CBC z PKCS#7 padding).

Instrukcja krok po kroku

1. Wygeneruj klucz AES i IV

Wygeneruj losowy klucz AES-256 (32 bajty) i wektor inicjalizacyjny IV (16 bajtów). Użyj kryptograficznie bezpiecznego generatora liczb losowych. Zapisz klucz AES i IV lokalnie - będą potrzebne do szyfrowania faktury.

2. Zaszyfruj klucz AES kluczem publicznym KSeF

Pobierz certyfikat z usage ["SymmetricKeyEncryption"] z endpointu GET /api/v2/security/public-key-certificates. Zaszyfruj klucz AES algorytmem RSA-OAEP z SHA-256 używając klucza publicznego z certyfikatu. Zakoduj wynik w Base64 - to jest encryptedSymmetricKey.

3. Utwórz sesję interaktywną

Wyślij żądanie POST /api/v2/sessions/online z parametrami: encryptedSymmetricKey (zaszyfrowany klucz AES w Base64), initVector (IV w Base64), formCode (np. "FA (3)"). W odpowiedzi otrzymasz referenceNumber sesji.

4. Odszyfruj klucz AES lokalnie

WAŻNE: Nie używaj encryptedSymmetricKey bezpośrednio do szyfrowania faktury. Odszyfruj encryptedSymmetricKey lokalnie (używając własnego klucza prywatnego, jeśli masz dostęp), aby uzyskać oryginalny klucz AES. Jeśli nie masz dostępu do klucza prywatnego, użyj klucza AES, który wygenerowałeś w kroku 1 (ten sam klucz, który zaszyfrowałeś).

5. Zaszyfruj fakturę algorytmem AES-256-CBC

Zaszyfruj fakturę XML algorytmem AES-256-CBC używając odszyfrowanego klucza AES (z kroku 4) i IV. Użyj PKCS#7 padding. Zakoduj zaszyfrowaną fakturę w Base64. Oblicz hash SHA-256 zaszyfrowanej faktury i zakoduj w Base64.

6. Wyślij zaszyfrowaną fakturę

Wyślij żądanie POST /api/v2/sessions/online/{referenceNumber}/invoices z parametrami: invoiceHash (hash oryginalnej faktury), invoiceSize (rozmiar oryginalnej faktury), encryptedInvoiceHash (hash zaszyfrowanej faktury), encryptedInvoiceSize (rozmiar zaszyfrowanej faktury), encryptedInvoiceContent (zaszyfrowana faktura w Base64).

Najczęstsze problemy i rozwiązania

Błąd 'Błąd odszyfrowania pliku' w aplikacji KSeF

Najczęstsza przyczyna to użycie encryptedSymmetricKey (zaszyfrowanego klucza) bezpośrednio do szyfrowania faktury. encryptedSymmetricKey to klucz AES zaszyfrowany algorytmem RSA-OAEP, który musi być najpierw odszyfrowany, aby uzyskać oryginalny klucz AES. Użyj klucza AES, który wygenerowałeś w kroku 1 (ten sam klucz, który zaszyfrowałeś), do szyfrowania faktury.

Różnica między encryptedKey a encryptedSymmetricKey

encryptedSymmetricKey to klucz AES zaszyfrowany algorytmem RSA-OAEP kluczem publicznym KSeF. To jest wartość, którą wysyłasz do KSeF przy tworzeniu sesji. Nie możesz użyć encryptedSymmetricKey bezpośrednio do szyfrowania faktury - musisz użyć oryginalnego klucza AES (który wygenerowałeś przed zaszyfrowaniem). Użyj tego samego klucza AES, który zaszyfrowałeś, do szyfrowania faktury.

Jak odszyfrować encryptedSymmetricKey?

Jeśli masz dostęp do klucza prywatnego używanego do szyfrowania, możesz odszyfrować encryptedSymmetricKey. W praktyce, ponieważ sam generujesz klucz AES, powinieneś zapisać oryginalny klucz AES lokalnie i użyć go do szyfrowania faktury. Nie musisz odszyfrowywać encryptedSymmetricKey - użyj klucza AES, który wygenerowałeś w kroku 1 (ten sam klucz, który zaszyfrowałeś).

Format IV i kodowanie Base64

IV musi mieć dokładnie 16 bajtów. Zakoduj IV w Base64 przed wysłaniem do KSeF. Upewnij się, że używasz tego samego IV do szyfrowania faktury, który wysłałeś przy tworzeniu sesji. Sprawdź, czy kodowanie Base64 jest poprawne (bez znaków nowej linii, bez padding).

Proces szyfrowania w sesji interaktywnej

Proces składa się z kilku etapów: 1) Wygeneruj losowy klucz AES-256 (32 bajty) i IV (16 bajtów), 2) Zaszyfruj klucz AES kluczem publicznym KSeF (RSA-OAEP) - to daje encryptedSymmetricKey, 3) Utwórz sesję z encryptedSymmetricKey i IV, 4) Zaszyfruj fakturę algorytmem AES-256-CBC używając oryginalnego klucza AES (z kroku 1) i IV, 5) Wyślij zaszyfrowaną fakturę do sesji. WAŻNE: Użyj tego samego klucza AES, który wygenerowałeś w kroku 1, do szyfrowania faktury - nie używaj encryptedSymmetricKey bezpośrednio.

Różnica między encryptedKey a encryptedSymmetricKey

encryptedSymmetricKey to klucz AES zaszyfrowany algorytmem RSA-OAEP kluczem publicznym KSeF. To jest wartość, którą wysyłasz do KSeF przy tworzeniu sesji (POST /api/v2/sessions/online). Nie możesz użyć encryptedSymmetricKey bezpośrednio do szyfrowania faktury - musisz użyć oryginalnego klucza AES (który wygenerowałeś przed zaszyfrowaniem). Użyj tego samego klucza AES, który zaszyfrowałeś, do szyfrowania faktury algorytmem AES-256-CBC.

Typowe błędy i rozwiązania

Błąd 'Błąd odszyfrowania pliku': najczęstsza przyczyna to użycie encryptedSymmetricKey bezpośrednio do szyfrowania faktury. Rozwiązanie: użyj oryginalnego klucza AES (który wygenerowałeś w kroku 1) do szyfrowania faktury. Nieprawidłowy format IV: IV musi mieć dokładnie 16 bajtów. Sprawdź, czy IV jest poprawnie wygenerowany i zakodowany w Base64. Nieprawidłowe kodowanie Base64: upewnij się, że wszystkie wartości są poprawnie zakodowane w Base64 (bez znaków nowej linii, bez padding). Nieprawidłowy algorytm szyfrowania: wymagane AES-256-CBC z PKCS#7 padding. Sprawdź, czy używasz poprawnego algorytmu w bibliotece kryptograficznej.

Przykładowy kod (pseudokod)

// Krok 1: Generowanie klucza AES i IV aesKey = generateRandomBytes(32); iv = generateRandomBytes(16);

// Krok 2: Szyfrowanie klucza AES kluczem publicznym KSeF encryptedSymmetricKey = rsaEncrypt(aesKey, ksefPublicKey, RSA-OAEP); encryptedSymmetricKeyBase64 = base64Encode(encryptedSymmetricKey); ivBase64 = base64Encode(iv);

// Krok 3: Utworzenie sesji sessionResponse = POST /api/v2/sessions/online { encryptedSymmetricKey: encryptedSymmetricKeyBase64, initVector: ivBase64, formCode: "FA (3)" }; referenceNumber = sessionResponse.referenceNumber;

// Krok 4: Szyfrowanie faktury (użyj oryginalnego klucza AES!) encryptedInvoice = aesEncrypt(invoiceXML, aesKey, iv, AES-256-CBC, PKCS7); encryptedInvoiceBase64 = base64Encode(encryptedInvoice);

// Krok 5: Wysłanie faktury POST /api/v2/sessions/online/{referenceNumber}/invoices { invoiceHash: sha256(invoiceXML), invoiceSize: invoiceXML.length, encryptedInvoiceHash: sha256(encryptedInvoice), encryptedInvoiceSize: encryptedInvoice.length, encryptedInvoiceContent: encryptedInvoiceBase64 };

FAQ

Powiązane tematy

• KSeF API certyfikaty szyfrowanie
• KSeF API sesja wsadowa upload
• KSeF API wysyłanie faktur