Enterprise edizione

Accelerator — sidecar GPU e factory di provider KMS

In sintesi

NextPDF Enterprise aggiunge due funzionalità di accelerazione: un sidecar GPU per l’embedding del testo con un fallback su CPU e una factory di provider KMS che fornisce i metadati e la rotazione delle chiavi di cifratura dei dati a livello di collezione. Questa pagina indica il comportamento, i confini e la postura di custodia delle chiavi.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Una distribuzione priva di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Panoramica concettuale

Il sidecar GPU accelera l’embedding da testo a vettore. Il pacchetto Enterprise invia il testo a un processo sidecar separato tramite una richiesta HTTP locale. Il sidecar esegue il modello di embedding su una GPU quando disponibile. Quando una GPU non è disponibile, il sidecar esegue lo stesso modello sulla CPU e segnala di aver operato in modalità degradata. Il risultato ha la stessa forma vettoriale in entrambi i casi. Il modello di embedding viene caricato alla prima richiesta, perciò la prima richiesta è più lenta di quelle successive. Il sidecar è facoltativo; viene esposto un controllo di disponibilità e un sidecar mancante solleva un’eccezione tipizzata anziché fallire silenziosamente.

La factory di provider KMS seleziona un provider di gestione delle chiavi dalla configurazione. La factory legge una variabile d’ambiente per scegliere il provider. Il provider predefinito deriva localmente una chiave di cifratura dei dati specifica per la collezione usando HKDF-SHA256 a partire da una chiave root configurata, con l’identificatore della collezione come separatore di dominio. Il provider locale non contatta alcun servizio esterno; la derivazione è deterministica e in-process. La factory accetta inoltre una forma di configurazione esplicita per il provider locale. I provider cloud — AWS KMS, GCP Cloud KMS, Azure Key Vault e HashiCorp Vault Transit — sono nomi di provider riconosciuti; selezionarne uno senza la corrispondente integrazione installata solleva un errore di configurazione tipizzato che nomina la dipendenza mancante.

Un provider restituisce metadati della chiave, non i byte grezzi della chiave. I metadati registrano l’identificatore della chiave, una versione della chiave monotonicamente crescente, il nome dell’algoritmo di cifratura e il nome del provider. Una chiamata di rotazione fa avanzare la versione della chiave e restituisce i nuovi metadati. È responsabilità del chiamante ri-cifrare i dati della collezione con la nuova versione della chiave dopo una rotazione. Il ciclo di vita della versione e della rotazione delle chiavi segue NIST SP 800-57 Part 1 Rev.5 §4.

Perché funziona così

L’embedding viene eseguito in un processo sidecar GPU separato anziché all’interno della richiesta PHP. Il caricamento del modello su GPU è costoso, perciò il sidecar carica il modello una sola volta e ammortizza quel costo su molte richieste. Quando non è presente alcuna GPU, il sidecar esegue lo stesso modello sulla CPU e segnala una modalità degradata. Il throughput può calare, ma la correttezza no: la forma vettoriale è identica in entrambi i casi. Il sidecar resta facoltativo; un controllo di disponibilità e un’eccezione tipizzata in caso di sidecar mancante mantengono l’accelerazione un opt-in deliberato, non una dipendenza nascosta. Questa separazione consente all’embedding ad alto volume di scalare su hardware dedicato mentre la pipeline di documenti resta una semplice chiamata PHP.

Contesto di progettazione: Generazione di documenti ad alto volume.

Superficie API

Superficie pubblica	Tipo	Scopo	Stabilità	Da
Factory di provider KMS	class	Costruire un provider KMS da configurazione d’ambiente o esplicita	stable	2.1.0
Provider KMS	interface	Ottenere i metadati di una chiave, ruotare una chiave e riportare il nome del provider	stable	2.1.0
Provider KMS locale	class (implementa l’interfaccia del provider)	Derivazione locale delle chiavi HKDF-SHA256; non contatta alcun servizio esterno	stable	2.1.0
Risultato della chiave di cifratura	value object	Metadati della chiave immutabili: key id, versione, algoritmo, provider — nessun byte grezzo della chiave	stable	2.1.0
Servizio di embedding su GPU	class (implementa l’interfaccia del servizio di embedding di Core)	Embedding del testo su un sidecar GPU con fallback su CPU	stable	2.1.0

La factory di provider espone un punto di ingresso «from environment» e un punto di ingresso esplicito «create». Il valore di configurazione della chiave root è contrassegnato come sensibile nel provider locale. Il contratto autorevole di parametri e tipi è il riferimento API pubblicato per il pacchetto nextpdf/enterprise; trattare quel riferimento — non questa pagina — come il contratto.

Esempio di codice — Avvio rapido

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

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.

Esempio di codice — Produzione

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.

I nomi delle variabili d’ambiente, le chiavi di configurazione esplicite e i tipi di eccezione sono documentati nel riferimento approfondito di Accelerator.

Casi limite e insidie

Il provider KMS locale richiede una chiave root codificata in esadecimale di almeno 32 byte. Un valore più corto o non esadecimale solleva un’eccezione di argomento tipizzata in fase di costruzione.
Selezionare un nome di provider cloud senza la corrispondente integrazione installata solleva un errore di configurazione tipizzato che nomina la dipendenza mancante.
Un nome di provider sconosciuto solleva un errore tipizzato che elenca i nomi supportati.
Il sidecar GPU segnala una modalità degradata quando ricorre alla CPU. Verificare quel campo se si dipende dal throughput della GPU.
Il modello di embedding viene caricato alla prima richiesta; dimensionare di conseguenza il timeout della prima richiesta.

Prestazioni

La derivazione locale delle chiavi è un’operazione HKDF a costo costante. Non contatta alcun servizio esterno. Una richiesta di embedding su GPU aggiunge un round trip locale verso il sidecar più il tempo di inferenza del modello. La prima richiesta paga anche il costo una tantum di caricamento del modello. Il fallback su CPU è corretto ma più lento del percorso GPU per lo stesso batch.

Note di sicurezza

Un provider KMS restituisce metadati della chiave, non i byte grezzi della chiave. Il value object del risultato della chiave di cifratura non trasporta mai il materiale della chiave.
La chiave root del provider locale è un parametro sensibile del costruttore. Non viene registrata né serializzata.
Il provider locale non contatta alcun servizio esterno. La derivazione è deterministica e in-process.
L’uso di AES-GCM richiede un vettore di inizializzazione univoco per ciascuna chiave, secondo NIST SP 800-38D §5.

Residenza dei dati e mitigazioni dei dati personali (PII)

Il provider KMS locale viene eseguito in-process e non contatta alcun servizio esterno; per la derivazione locale delle chiavi nessun materiale di chiave e nessun contenuto del documento lascia l’host. Il sidecar GPU riceve il testo da sottoporre a embedding tramite una richiesta locale; non riceve contenuti di documenti non correlati. Un provider KMS cloud, quando configurato, contatta il provider cloud selezionato; valutare la postura di residenza dei dati di tale provider per la propria giurisdizione.

Telemetria sicura e sanificazione dei log

La chiave root del provider locale è un parametro sensibile del costruttore ed è esclusa dai log e dalla serializzazione. Non aggiungere la chiave root, le chiavi derivate o le credenziali del provider ai log della propria applicazione. Trattare tutto il materiale di chiave come un segreto nella propria politica di logging e tracing.

Modello di minaccia

Il provider restituisce metadati, non byte di chiave, perciò una fuga di metadati non espone materiale di chiave. La sicurezza del provider locale dipende dalla segretezza della chiave root configurata. La sicurezza di un provider cloud dipende da tale provider e dalla propria configurazione. La protezione delle chiavi dipende dal KMS o dal segreto della chiave root, dalla distribuzione e dall’operatore — non da questo software da solo. Vedere il confine di distribuzione.

Conformità

Il ciclo di vita della versione e della rotazione della chiave di cifratura dei dati è allineato a NIST SP 800-57 Part 1 Rev.5 §4.
La responsabilità di protezione delle chiavi è allineata a NIST SP 800-57 Part 1 Rev.5 §5.5.2.
L’univocità del vettore di inizializzazione di AES-GCM è allineata a NIST SP 800-38D §5.

Ogni fonte normativa è parafrasata. Nessun testo normativo è riprodotto in questa pagina. Questa pagina riguarda la gestione delle chiavi.

Comportamento in modalità FIPS

La derivazione HKDF del provider locale usa SHA-256. L’algoritmo di cifratura registrato nei metadati della chiave è AES-256-GCM. Quando l’applicazione viene eseguita rispetto a un provider crittografico convalidato FIPS, tali primitive vengono eseguite all’interno di quel confine convalidato. La factory di provider seleziona e costruisce il provider; non certifica il confine crittografico.

NextPDF Enterprise non è un modulo crittografico convalidato FIPS e non avanza alcuna rivendicazione di certificazione FIPS. Opera in modalità compatibile con FIPS solo quando è configurato con un provider crittografico convalidato FIPS o con un KMS convalidato FIPS.

Confine di edizione

Il sidecar di embedding su GPU e la factory di provider KMS sono inclusi esclusivamente nel pacchetto nextpdf/enterprise. NextPDF Pro fornisce l’integrazione KMS per le strategie di firma (AWS KMS, GCP Cloud KMS, Azure Key Vault) ma non fornisce la factory di provider KMS Enterprise né il sidecar di embedding su GPU. Il trasporto interno del sidecar e le classi interne della pipeline di embedding sono fuori ambito per la superficie pubblica e non sono qui riprodotti.

Fallback di Pro

NextPDF Pro fornisce le strategie di firma cloud-KMS — il KMS custodisce la chiave di firma e Pro invia al provider il digest degli attributi firmati. Si tratta di un’integrazione di firma. Non è la factory di provider per chiavi di cifratura dei dati a livello di collezione di Enterprise né il sidecar di embedding su GPU. Vedere Accelerator — NextPDF Pro per la superficie di accelerazione di Pro.

Fallback di Core

NextPDF Core non dispone di alcun sidecar di embedding su GPU né di alcuna factory di provider KMS. L’embedding e la gestione delle chiavi a livello di collezione sono funzionalità esclusive di Enterprise.

Nota sul confine Enterprise

Il trasporto del sidecar GPU, l’identificatore del modello di embedding e le classi interne della pipeline sono descritti solo a livello di comportamento. Il client di trasporto interno, i token di scope interni e la composizione interna della pipeline sono fuori ambito per la superficie pubblica e non sono qui riprodotti.

Confine di distribuzione

NextPDF Enterprise si integra con un KMS oppure deriva le chiavi da un segreto di chiave root configurato. Non memorizza né garantisce esso stesso la sicurezza di tale segreto di chiave root o della chiave del KMS cloud. La sicurezza delle chiavi dipende dal KMS o dal segreto della chiave root, dalla distribuzione e dall’operatore — non da NextPDF Enterprise da solo. L’operatore è responsabile del provisioning della chiave root, dell’archiviazione dei segreti, della configurazione del KMS e della pianificazione della rotazione. La responsabilità di protezione delle chiavi segue NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise non espone in questa documentazione i flussi delle credenziali KMS né i dettagli interni di gestione della chiave root.

Confine di conformità legale

Riguarda la gestione delle chiavi. La dichiarazione sulla modalità FIPS è una dichiarazione di compatibilità, non una certificazione e non un parere legale. Consultare i propri consulenti di conformità e legali per i propri obblighi normativi.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi di file dei runbook e i prefissi dei ticket sono fuori ambito.

Contratto di comportamento

La factory di provider seleziona il provider dalla configurazione e restituisce un provider che soddisfa il contratto del provider.
Un provider restituisce metadati di chiave immutabili e non restituisce mai i byte grezzi della chiave.
Una chiamata di rotazione fa avanzare la versione della chiave e restituisce i nuovi metadati; il chiamante ri-cifra i dati della collezione.
Il sidecar GPU segnala una modalità degradata in caso di fallback su CPU e solleva un’eccezione tipizzata quando non è disponibile.

Vedere anche

Riferimento di Accelerator — NextPDF Enterprise
Security — NextPDF Enterprise
Intelligence — NextPDF Enterprise
Accelerator — NextPDF Pro
KMS · DEK · HKDF — termini del glossario.