Accelerator — sidecar GPU i fabryka dostawców KMS

W skrócie

NextPDF Enterprise dodaje dwie funkcje akceleracji: sidecar GPU do osadzania tekstu z rozwiązaniem zastępczym na CPU oraz fabrykę dostawców KMS, która dostarcza metadane i rotację kluczy szyfrowania danych na poziomie kolekcji. Ta strona opisuje zachowanie, granice oraz stanowisko wobec pieczy nad kluczami.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie wczytuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Przegląd koncepcyjny

Sidecar GPU przyspiesza osadzanie tekstu w postaci wektorów. Pakiet Enterprise wysyła tekst do oddzielnego procesu sidecar przez lokalne żądanie HTTP. Sidecar uruchamia model osadzania na GPU, gdy jest on dostępny. Gdy GPU nie jest dostępny, sidecar uruchamia ten sam model na CPU i zgłasza, że zadziałał w trybie zdegradowanym. W obu przypadkach wynik ma ten sam kształt wektora. Model osadzania jest wczytywany przy pierwszym żądaniu, więc pierwsze żądanie jest wolniejsze niż kolejne. Sidecar jest opcjonalny; udostępniono sprawdzenie dostępności, a brak sidecara zgłasza typowany wyjątek zamiast cichej awarii.

Fabryka dostawców KMS wybiera dostawcę zarządzania kluczami na podstawie konfiguracji. Fabryka odczytuje zmienną środowiskową, aby wybrać dostawcę. Domyślny dostawca lokalnie wyprowadza klucz szyfrowania danych właściwy dla kolekcji za pomocą HKDF-SHA256 ze skonfigurowanego klucza głównego, używając identyfikatora kolekcji jako separatora domeny. Dostawca lokalny nie kontaktuje się z żadną usługą zewnętrzną; wyprowadzanie jest deterministyczne i odbywa się w procesie. Fabryka akceptuje także jawną formę konfiguracji dostawcy lokalnego. Dostawcy chmurowi — AWS KMS, GCP Cloud KMS, Azure Key Vault oraz HashiCorp Vault Transit — to rozpoznawane nazwy dostawców; wybranie jednego z nich bez zainstalowanej odpowiedniej integracji zgłasza typowany błąd konfiguracji wskazujący brakującą zależność.

Dostawca zwraca metadane klucza, a nie surowe bajty klucza. Metadane zapisują identyfikator klucza, monotonicznie rosnącą wersję klucza, nazwę algorytmu szyfrowania oraz nazwę dostawcy. Wywołanie rotacji zwiększa wersję klucza i zwraca nowe metadane. Za ponowne zaszyfrowanie danych kolekcji nową wersją klucza po rotacji odpowiada wywołujący. Wersja klucza oraz cykl życia rotacji są zgodne z NIST SP 800-57 Part 1 Rev.5 §4.

Dlaczego działa to w ten sposób

Osadzanie działa w oddzielnym procesie sidecar GPU, a nie wewnątrz żądania PHP. Wczytywanie modelu GPU jest kosztowne, więc sidecar wczytuje model raz i rozkłada ten koszt na wiele żądań. Gdy nie ma GPU, sidecar uruchamia ten sam model na CPU i zgłasza tryb zdegradowany. Przepustowość może spaść, ale poprawność nie: kształt wektora jest identyczny w obu przypadkach. Sidecar pozostaje opcjonalny; sprawdzenie dostępności oraz typowany wyjątek przy braku sidecara sprawiają, że akceleracja jest świadomym wyborem, a nie ukrytą zależnością. To rozdzielenie pozwala skalować osadzanie o dużej objętości na dedykowanym sprzęcie, podczas gdy potok dokumentów pozostaje zwykłym wywołaniem PHP.

Tło projektowe: Generowanie dokumentów o dużej objętości.

Powierzchnia API

Powierzchnia publiczna	Typ	Cel	Stabilność	Od wersji
Fabryka dostawców KMS	klasa	Zbudowanie dostawcy KMS na podstawie konfiguracji środowiskowej lub jawnej	stabilny	2.1.0
Dostawca KMS	interfejs	Pobranie metadanych klucza, rotacja klucza oraz zgłoszenie nazwy dostawcy	stabilny	2.1.0
Lokalny dostawca KMS	klasa (implementuje interfejs dostawcy)	Lokalne wyprowadzanie klucza HKDF-SHA256; nie kontaktuje się z żadną usługą zewnętrzną	stabilny	2.1.0
Wynik klucza szyfrowania	obiekt wartości	Niezmienne metadane klucza: identyfikator klucza, wersja, algorytm, dostawca — bez surowych bajtów klucza	stabilny	2.1.0
Usługa osadzania GPU	klasa (implementuje interfejs usługi osadzania Core)	Osadzanie tekstu na sidecarze GPU z rozwiązaniem zastępczym na CPU	stabilny	2.1.0

Fabryka dostawców udostępnia punkt wejścia „z środowiska” oraz jawny punkt wejścia „create”. Wartość konfiguracyjna klucza głównego jest oznaczona jako wrażliwa w dostawcy lokalnym. Wiążącym kontraktem parametrów i typów jest opublikowana dokumentacja API pakietu nextpdf/enterprise; traktuj tę dokumentację — a nie tę stronę — jako kontrakt.

Przykład kodu — Szybki start

composer require nextpdf/core
composer require nextpdf/enterprise:^3

Build the local KMS provider and read key metadata

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

// Selects the provider from environment configuration; defaults to the
// local HKDF-based provider. Supply the root key through your secret
// manager, never from source or logs.
$provider = KmsProviderFactory::fromEnvironment();

$key = $provider->getEncryptionKey('collection-1');
// $key is metadata only: key id, version, algorithm, provider name.

Przykład kodu — Produkcja

Rotate a collection key, then re-encrypt collection data

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

$provider = KmsProviderFactory::fromEnvironment();

$rotated = $provider->rotateKey('collection-1');
// The version advanced. Re-encrypt the collection's data files with the
// new key version. The provider returns metadata only; it never returns
// raw key bytes.

Nazwy zmiennych środowiskowych, jawne klucze konfiguracji oraz typy wyjątków są udokumentowane w szczegółowej referencji Accelerator.

Przypadki brzegowe i pułapki

• Lokalny dostawca KMS wymaga zakodowanego szesnastkowo klucza głównego o długości co najmniej 32 bajtów. Krótsza lub nieszesnastkowa wartość zgłasza przy konstrukcji typowany wyjątek argumentu.
• Wybranie nazwy dostawcy chmurowego bez zainstalowanej odpowiedniej integracji zgłasza typowany błąd konfiguracji wskazujący brakującą zależność.
• Nieznana nazwa dostawcy zgłasza typowany błąd, który wymienia obsługiwane nazwy.
• Sidecar GPU zgłasza tryb zdegradowany, gdy przechodzi na rozwiązanie zastępcze CPU. Sprawdzaj to pole, jeśli zależy ci na przepustowości GPU.
• Model osadzania jest wczytywany przy pierwszym żądaniu; odpowiednio dobierz limit czasu pierwszego żądania.

Wydajność

Lokalne wyprowadzanie klucza to operacja HKDF o stałym koszcie. Nie kontaktuje się z żadną usługą zewnętrzną. Żądanie osadzania GPU dodaje jeden lokalny obieg do sidecara plus czas wnioskowania modelu. Pierwsze żądanie ponosi także jednorazowy koszt wczytania modelu. Rozwiązanie zastępcze na CPU jest poprawne, lecz wolniejsze od ścieżki GPU dla tej samej partii.

Uwagi dotyczące bezpieczeństwa

• Dostawca KMS zwraca metadane klucza, a nie surowe bajty klucza. Obiekt wartości wyniku klucza szyfrowania nigdy nie przenosi materiału klucza.
• Klucz główny dostawcy lokalnego jest wrażliwym parametrem konstruktora. Nie jest logowany ani serializowany.
• Dostawca lokalny nie kontaktuje się z żadną usługą zewnętrzną. Wyprowadzanie jest deterministyczne i odbywa się w procesie.
• Użycie AES-GCM wymaga unikatowego wektora inicjującego dla każdego klucza, zgodnie z NIST SP 800-38D §5.

Rezydencja danych i środki ograniczające PII

Lokalny dostawca KMS działa w procesie i nie kontaktuje się z żadną usługą zewnętrzną; przy lokalnym wyprowadzaniu klucza żaden materiał klucza ani żadna treść dokumentu nie opuszczają hosta. Sidecar GPU otrzymuje tekst do osadzenia przez lokalne żądanie; nie otrzymuje niezwiązanej treści dokumentu. Dostawca chmurowego KMS, gdy jest skonfigurowany, kontaktuje się z wybranym przez ciebie dostawcą chmurowym; przeanalizuj stanowisko tego dostawcy wobec rezydencji danych dla swojej jurysdykcji.

Bezpieczna telemetria i czyszczenie logów

Klucz główny dostawcy lokalnego jest wrażliwym parametrem konstruktora i jest wykluczony z logów oraz serializacji. Nie dodawaj klucza głównego, kluczy pochodnych ani poświadczeń dostawcy do własnych logów aplikacji. W swojej polityce logowania i śledzenia traktuj cały materiał klucza jak sekret.

Model zagrożeń

Dostawca zwraca metadane, a nie bajty klucza, więc wyciek metadanych nie ujawnia materiału klucza. Bezpieczeństwo dostawcy lokalnego zależy od tajności skonfigurowanego klucza głównego. Bezpieczeństwo dostawcy chmurowego zależy od tego dostawcy i od twojej konfiguracji. Ochrona klucza zależy od KMS lub sekretu klucza głównego, od wdrożenia oraz od operatora — a nie wyłącznie od tego oprogramowania. Zobacz granicę wdrożenia.

Zgodność

• Wersja klucza szyfrowania danych oraz cykl życia rotacji są zgodne z NIST SP 800-57 Part 1 Rev.5 §4.
• Odpowiedzialność za ochronę kluczy jest zgodna z NIST SP 800-57 Part 1 Rev.5 §5.5.2.
• Unikatowość wektora inicjującego AES-GCM jest zgodna z NIST SP 800-38D §5.

Każde źródło normatywne jest parafrazowane. Na tej stronie nie odtwarza się żadnego tekstu normatywnego. Ta strona dotyczy zarządzania kluczami.

Zachowanie w trybie FIPS

Wyprowadzanie HKDF dostawcy lokalnego korzysta z SHA-256. Algorytmem szyfrowania zapisanym w metadanych klucza jest AES-256-GCM. Gdy aplikacja działa z dostawcą kryptograficznym zwalidowanym zgodnie z FIPS, te prymitywy działają w tej zwalidowanej granicy. Sama fabryka dostawców wybiera i konstruuje dostawcę; nie certyfikuje granicy kryptograficznej.

NextPDF Enterprise nie jest modułem kryptograficznym zwalidowanym zgodnie z FIPS i nie wysuwa żadnej deklaracji certyfikacji FIPS. Działa w trybie zgodnym z FIPS wyłącznie wtedy, gdy jest skonfigurowany z dostawcą kryptograficznym zwalidowanym zgodnie z FIPS lub z KMS zwalidowanym zgodnie z FIPS.

Granica edycji

Sidecar osadzania GPU oraz fabryka dostawców KMS są dostarczane wyłącznie w pakiecie nextpdf/enterprise. NextPDF Pro zapewnia integrację KMS dla strategii podpisywania (AWS KMS, GCP Cloud KMS, Azure Key Vault), ale nie zapewnia fabryki dostawców KMS Enterprise ani sidecara osadzania GPU. Wewnętrzny transport sidecara oraz wewnętrzne klasy potoku osadzania są poza zakresem powierzchni publicznej i nie są tutaj odtwarzane.

Rozwiązanie zastępcze Pro

NextPDF Pro zapewnia chmurowe strategie podpisywania KMS — KMS przechowuje klucz podpisujący, a Pro wysyła do dostawcy skrót atrybutów podpisanych. To integracja podpisywania. Nie jest to fabryka dostawców kluczy szyfrowania danych na poziomie kolekcji Enterprise ani sidecar osadzania GPU. Zobacz Accelerator — NextPDF Pro, aby poznać powierzchnię akceleracji Pro.

Rozwiązanie zastępcze Core

NextPDF Core nie ma sidecara osadzania GPU ani fabryki dostawców KMS. Osadzanie oraz zarządzanie kluczami na poziomie kolekcji to funkcje wyłącznie Enterprise.

Uwaga o granicy Enterprise

Transport sidecara GPU, identyfikator modelu osadzania oraz wewnętrzne klasy potoku są opisane wyłącznie na poziomie zachowania. Wewnętrzny klient transportu, wewnętrzne tokeny zakresu oraz wewnętrzna kompozycja potoku są poza zakresem powierzchni publicznej i nie są tutaj odtwarzane.

Granica wdrożenia

NextPDF Enterprise integruje się z KMS lub wyprowadza klucze ze skonfigurowanego sekretu klucza głównego. Sam nie przechowuje ani nie gwarantuje bezpieczeństwa tego sekretu klucza głównego ani klucza chmurowego KMS. Bezpieczeństwo klucza zależy od KMS lub sekretu klucza głównego, od wdrożenia oraz od operatora — a nie wyłącznie od NextPDF Enterprise. Operator odpowiada za udostępnianie klucza głównego, przechowywanie sekretów, konfigurację KMS oraz harmonogram rotacji. Odpowiedzialność za ochronę kluczy jest zgodna z NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise nie ujawnia w tej dokumentacji przepływów poświadczeń KMS ani wewnętrznych mechanizmów obsługi klucza głównego.

Granica zgodności prawnej

Dotyczy zarządzania kluczami. Stwierdzenie o trybie FIPS jest stwierdzeniem o zgodności, a nie certyfikacją ani opinią prawną. W sprawie obowiązków regulacyjnych skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Kontrakt zachowania

• Fabryka dostawców wybiera dostawcę na podstawie konfiguracji i zwraca dostawcę spełniającego kontrakt dostawcy.
• Dostawca zwraca niezmienne metadane klucza i nigdy nie zwraca surowych bajtów klucza.
• Wywołanie rotacji zwiększa wersję klucza i zwraca nowe metadane; wywołujący ponownie szyfruje dane kolekcji.
• Sidecar GPU zgłasza tryb zdegradowany przy przejściu na rozwiązanie zastępcze CPU oraz zgłasza typowany wyjątek, gdy jest niedostępny.

Zobacz też

• Referencja Accelerator — NextPDF Enterprise
• Security — NextPDF Enterprise
• Intelligence — NextPDF Enterprise
• Accelerator — NextPDF Pro
• KMS · DEK · HKDF — terminy glosariusza.