Accelerator — Deep Reference (Gated)
Gated content notice. This page is part of the gated reference surface. Distribution restricted by NDA. Do not mirror to public channels.
At a glance
This deep reference describes the KMS provider factory, the local key-derivation provider, and the GPU embedding sidecar at the public API level. It states behavior and boundaries. It does not reproduce internal transport, internal scope tokens, internal environment-codename strings, or the internal pipeline composition.
Edition gate
Requires NextPDF Enterprise. Get a license.
License feature flag
The enterprise tier gates this surface. Install the Enterprise package next to the Core package. The KMS provider is selected at runtime; calling code depends on the provider contract, not the concrete provider.
Conceptual overview
The KMS provider factory builds a provider from environment configuration or from explicit configuration. The default provider derives a collection-specific data-encryption key locally with HKDF-SHA256 from a configured master key, using the collection identifier as the domain separator. The local provider contacts no external service; the derivation is deterministic and in-process. The master key must be a hex-encoded value of at least 32 bytes; a shorter or non-hex value raises a typed argument exception at construction.
Cloud provider names — AWS KMS, GCP Cloud KMS, Azure Key Vault, and HashiCorp Vault Transit — are recognized. Selecting one 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.
A provider returns an immutable key-metadata value object: key identifier, a monotonically increasing key version, the encryption algorithm name, and the provider name. It never returns raw key bytes. A rotation call advances the key version and returns the new metadata; the caller re-encrypts collection data with the new version. The key version and lifecycle state follows NIST SP 800-57 Part 1 Rev.5 §4; the rotation and re-keying model follows the same clause family.
The GPU embedding service implements the Core embedding-service interface. It sends the text to a separate GPU sidecar process over a local request and parses the returned vectors. The sidecar runs the embedding model on a GPU when one is available and falls back to the CPU otherwise, reporting a degraded mode in that case. The model is loaded on the first request. An availability check is exposed; an unavailable sidecar raises a typed exception rather than failing silently.
Public API surface
composer require nextpdf/enterprise:^3| Public surface | Type | Notes |
|---|---|---|
| KMS provider factory | class | fromEnvironment and create entry points; selects and constructs a provider. |
| KMS provider | interface | getEncryptionKey, rotateKey, providerName. |
| Local KMS provider | class implementing the provider interface | HKDF-SHA256 derivation; sensitive master-key constructor parameter. |
| Encryption-key result | immutable value object | Key id, version, algorithm, provider name; no raw key bytes. |
| GPU embedding service | class implementing the Core embedding-service interface | embed, batchEmbed, getDimension; CPU fallback with degraded-mode reporting. |
Class names above are the public, supported integration surface. The internal sidecar transport client, internal scope tokens, internal environment-codename strings, internal namespace paths, and internal pipeline composition are out of scope and are not listed.
Edge cases & FIPS-mode behavior
- The local provider master key must be hex-encoded and at least 32 bytes; otherwise a typed argument exception is raised at construction.
- Selecting a cloud provider name without its integration installed raises a typed configuration error naming the missing dependency.
- The GPU sidecar reports a degraded mode on CPU fallback; the vector shape is unchanged.
- The embedding model is loaded on the first request; the first request is slower than later ones.
The local provider’s HKDF uses SHA-256 and the recorded encryption algorithm is AES-256-GCM. When the application runs against a FIPS-validated cryptographic provider, those primitives run in that validated boundary. AES-GCM use requires a unique initialization vector per key, per NIST SP 800-38D §5.
NextPDF Enterprise is not a FIPS-validated cryptographic module and makes no FIPS certification claim. It operates in a FIPS-compatible mode only when configured with a FIPS-validated cryptographic provider or a FIPS-validated KMS. No FIPS certification artifact exists in this repository.
Deployment boundary
NextPDF Enterprise integrates with a KMS or derives keys from a configured master-key secret. It does not store or guarantee the security of that secret or the cloud KMS key. Key security depends on the KMS or the master-key secret, on the deployment, and on the operator — not on NextPDF Enterprise alone. The operator owns master-key provisioning, secret storage, KMS configuration, and rotation scheduling. Key-protection responsibility follows NIST SP 800-57 Part 1 Rev.5 §5.5.2. This page does not expose KMS credential flows or master-key handling internals.
Legal-compliance boundary
This page is marked export_control_class: legal-review-required. The FIPS-mode statement is a compatibility statement, not a certification and not a legal opinion. Consult your own compliance and legal advisers.
NDA scan status
This gated page references public API class names only. It contains no internal namespace paths, no internal transport-client class names, no internal environment-codename strings, no runbook filenames, and no internal ticket prefixes. Attested in the co-located NDA checklist.