Enterprise edition

Accelerator — GPU sidecar and KMS provider factory

At a glance

NextPDF Enterprise adds two acceleration features: a GPU sidecar for text embedding with a CPU fallback, and a KMS provider factory that supplies collection-level data-encryption-key metadata and rotation. This page states behavior, boundaries, and the key-custody stance.

Availability & licensing

This capability ships in NextPDF Enterprise (nextpdf/enterprise) and activates with an Enterprise-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

Conceptual overview

The GPU sidecar accelerates text-to-vector embedding. The Enterprise package sends the text to a separate sidecar process over a local HTTP request. The sidecar runs the embedding model on a GPU when one is available. When a GPU is not available, the sidecar runs the same model on the CPU and reports that it ran in a degraded mode. The result is the same vector shape in both cases. The embedding model is loaded on the first request, so the first request is slower than later ones. The sidecar is optional; an availability check is exposed, and a missing sidecar raises a typed exception rather than a silent failure.

The KMS provider factory selects a key-management provider from configuration. The factory reads an environment variable to choose the provider. The default provider derives a collection-specific data-encryption key locally using HKDF-SHA256 from a configured root key, with the collection identifier as the domain separator. The local provider contacts no external service; the derivation is deterministic and in-process. The factory also accepts an explicit configuration form for the local provider. Cloud providers — AWS KMS, GCP Cloud KMS, Azure Key Vault, and HashiCorp Vault Transit — are recognized provider names; selecting one without the corresponding integration installed raises a typed configuration error that names the missing dependency.

A provider returns key metadata, not raw key bytes. The metadata records the key identifier, a monotonically increasing key version, the encryption algorithm name, and the provider name. A rotation call advances the key version and returns the new metadata. The caller is responsible for re-encrypting collection data with the new key version after a rotation. The key version and rotation lifecycle follows NIST SP 800-57 Part 1 Rev.5 §4.

Why it works this way

Embedding runs in a separate GPU sidecar process rather than inside the PHP request. GPU model loading is expensive, so the sidecar loads the model once and amortizes that cost across many requests. When no GPU is present, the sidecar runs the same model on the CPU and reports a degraded mode. Throughput can drop, but correctness does not: the vector shape is identical either way. The sidecar stays optional; an availability check and a typed exception on a missing sidecar keep acceleration a deliberate opt-in, not a hidden dependency. That separation lets high-volume embedding scale on dedicated hardware while the document pipeline stays a plain PHP call.

Design background: High-volume document generation.

API surface

Public surface	Type	Purpose	Stability	Since
KMS provider factory	class	Build a KMS provider from environment or explicit configuration	stable	2.1.0
KMS provider	interface	Get key metadata, rotate a key, and report the provider name	stable	2.1.0
Local KMS provider	class (implements the provider interface)	Local HKDF-SHA256 key derivation; contacts no external service	stable	2.1.0
Encryption-key result	value object	Immutable key metadata: key id, version, algorithm, provider — no raw key bytes	stable	2.1.0
GPU embedding service	class (implements the Core embedding-service interface)	Embed text on a GPU sidecar with a CPU fallback	stable	2.1.0

The provider factory exposes a “from environment” entry point and an explicit “create” entry point. The root key configuration value is marked sensitive in the local provider. The authoritative parameter and type contract is the published API reference for the nextpdf/enterprise package; treat that reference — not this page — as the contract.

Code sample — Quick start

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.

Code sample — Production

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.

The environment variable names, the explicit configuration keys, and the exception types are documented in the Accelerator deep reference.

Edge cases & gotchas

The local KMS provider requires a hex-encoded root key of at least 32 bytes. A shorter or non-hex value raises a typed argument exception at construction.
Selecting a cloud provider name without the corresponding integration installed raises a typed configuration error that names the missing dependency.
An unknown provider name raises a typed error that lists the supported names.
The GPU sidecar reports a degraded mode when it falls back to the CPU. Check that field if you depend on GPU throughput.
The embedding model is loaded on the first request; size the first-request timeout accordingly.

Performance

Local key derivation is a constant-cost HKDF operation. It contacts no external service. A GPU embedding request adds one local round trip to the sidecar plus the model inference time. The first request also pays the one-time model-load cost. CPU fallback is correct but slower than the GPU path for the same batch.

Security notes

A KMS provider returns key metadata, not raw key bytes. The encryption-key result value object never carries the key material.
The local provider root key is a sensitive constructor parameter. It is not logged and not serialized.
The local provider contacts no external service. Derivation is deterministic and in-process.
AES-GCM use requires a unique initialization vector per key, per NIST SP 800-38D §5.

Data Residency & PII Mitigations

The local KMS provider runs in-process and contacts no external service; no key material and no document content leaves the host for local key derivation. The GPU sidecar receives the text to embed over a local request; it does not receive unrelated document content. A cloud KMS provider, when configured, contacts the cloud provider you select; review that provider’s data-residency posture for your jurisdiction.

Safe Telemetry & Log Scrubbing

The local-provider root key is a sensitive constructor parameter and is excluded from logs and serialization. Do not add the root key, derived keys, or provider credentials to your own application logs. Treat all key material as a secret in your logging and tracing policy.

Threat model

The provider returns metadata, not key bytes, so a metadata leak does not expose key material. The local provider’s security depends on the secrecy of the configured root key. A cloud provider’s security depends on that provider and your configuration. Key protection depends on the KMS or the root-key secret, the deployment, and the operator — not on this software alone. See the deployment boundary.

Conformance

The data-encryption-key version and rotation lifecycle aligns with NIST SP 800-57 Part 1 Rev.5 §4.
Key-protection responsibility aligns with NIST SP 800-57 Part 1 Rev.5 §5.5.2.
AES-GCM initialization-vector uniqueness aligns with NIST SP 800-38D §5.

Every normative source is paraphrased. No normative text is reproduced on this page. This page concerns key management.

FIPS-mode behavior

The local provider’s HKDF derivation uses SHA-256. The encryption algorithm recorded in the key metadata is AES-256-GCM. When the application runs against a FIPS-validated cryptographic provider, those primitives run in that validated boundary. The provider factory itself selects and constructs the provider; it does not certify the cryptographic boundary.

NextPDF Enterprise operates in a FIPS-compatible mode only when it is configured with a FIPS-validated cryptographic provider or a FIPS-validated KMS.

Edition boundary

The GPU embedding sidecar and the KMS provider factory ship in the nextpdf/enterprise package only. NextPDF Pro provides KMS integration for signing strategies (AWS KMS, GCP Cloud KMS, Azure Key Vault) but does not provide the Enterprise KMS provider factory or the GPU embedding sidecar. The internal sidecar transport and the internal embedding-pipeline classes are out of scope for the public surface and are not reproduced here.

Pro fallback

NextPDF Pro provides cloud-KMS signing strategies — the KMS holds the signing key, and Pro sends the signed-attributes digest to the provider. That is a signing integration. It is not the Enterprise collection-level data-encryption-key provider factory and not the GPU embedding sidecar. See Accelerator — NextPDF Pro for the Pro acceleration surface.

Core fallback

NextPDF Core has no GPU embedding sidecar and no KMS provider factory. Embedding and collection-level key management are Enterprise-only features.

Enterprise boundary note

The GPU sidecar transport, the embedding model identifier, and the internal pipeline classes are described at the behavior level only. The internal transport client, the internal scope tokens, and the internal pipeline composition are out of scope for the public surface and are not reproduced here.

Deployment boundary

NextPDF Enterprise integrates with a KMS or derives keys from a configured root-key secret. It does not itself store or guarantee the security of that root-key secret or the cloud KMS key. Key security depends on the KMS or the root-key secret, on the deployment, and on the operator — not on NextPDF Enterprise alone. The operator is responsible for root-key provisioning, secret storage, KMS configuration, and rotation scheduling. Key-protection responsibility follows NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise does not expose KMS credential flows or root-key handling internals in this documentation.

Legal-compliance boundary

It concerns key management. The FIPS-mode statement is a compatibility statement. Consult your own compliance and legal advisers for your regulatory obligations.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

Behavior contract

The provider factory selects the provider from configuration and returns a provider that satisfies the provider contract.
A provider returns immutable key metadata and never returns raw key bytes.
A rotation call advances the key version and returns the new metadata; the caller re-encrypts collection data.
The GPU sidecar reports a degraded mode on CPU fallback and raises a typed exception when it is unavailable.