Enterprise 에디션

Accelerator — GPU 사이드카 및 KMS 공급자 팩토리

한눈에 보기

NextPDF Enterprise는 두 가지 가속 기능을 추가합니다. CPU 폴백을 갖춘 텍스트 임베딩용 GPU 사이드카, 그리고 컬렉션 수준 데이터 암호화 키 메타데이터와 회전을 제공하는 KMS 공급자 팩토리입니다. 이 페이지는 동작, 경계, 키 보관 입장을 명시합니다.

가용성 및 라이선싱

이 기능은 NextPDF Enterprise(nextpdf/enterprise)로 제공되며 Enterprise 계층 라이선스 엔벨로프로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션을 비교하고 라이선스를 받으십시오.

개념 개요

GPU 사이드카는 텍스트-투-벡터 임베딩을 가속합니다. Enterprise 패키지는 로컬 HTTP 요청을 통해 텍스트를 별도의 사이드카 프로세스로 전송합니다. 사이드카는 GPU가 사용 가능할 때 GPU에서 임베딩 모델을 실행합니다. GPU가 사용 불가능하면 사이드카는 동일한 모델을 CPU에서 실행하고 격하 모드로 실행되었음을 보고합니다. 두 경우 모두 결과는 동일한 벡터 형태입니다. 임베딩 모델은 첫 요청에서 로드되므로 첫 요청은 이후 요청보다 느립니다. 사이드카는 선택 사항입니다. 가용성 검사가 노출되며, 사이드카가 없으면 조용한 실패가 아니라 타입이 지정된 예외가 발생합니다.

KMS 공급자 팩토리는 구성으로부터 키 관리 공급자를 선택합니다. 팩토리는 환경 변수를 읽어 공급자를 선택합니다. 기본 공급자는 컬렉션 식별자를 도메인 구분자로 삼아, 구성된 마스터 키로부터 HKDF-SHA256을 사용해 컬렉션별 데이터 암호화 키를 로컬에서 파생합니다. 로컬 공급자는 외부 서비스에 연결하지 않습니다. 파생은 결정적이며 인프로세스로 수행됩니다. 팩토리는 로컬 공급자에 대한 명시적 구성 형태도 받습니다. 클라우드 공급자 — AWS KMS, GCP Cloud KMS, Azure Key Vault, HashiCorp Vault Transit —는 인식되는 공급자 이름입니다. 해당 통합이 설치되지 않은 상태에서 하나를 선택하면 누락된 의존성을 명시하는 타입이 지정된 구성 오류가 발생합니다.

공급자는 원시 키 바이트가 아니라 키 메타데이터를 반환합니다. 메타데이터는 키 식별자, 단조 증가하는 키 버전, 암호화 알고리즘 이름, 공급자 이름을 기록합니다. 회전 호출은 키 버전을 진행시키고 새 메타데이터를 반환합니다. 회전 후 새 키 버전으로 컬렉션 데이터를 다시 암호화하는 것은 호출자의 책임입니다. 키 버전 및 회전 수명 주기는 NIST SP 800-57 Part 1 Rev.5 §4를 따릅니다.

이렇게 작동하는 이유

임베딩은 PHP 요청 내부가 아니라 별도의 GPU 사이드카 프로세스에서 실행됩니다. GPU 모델 로딩은 비용이 크므로, 사이드카는 모델을 한 번 로드하고 그 비용을 많은 요청에 걸쳐 분산합니다. GPU가 없을 때 사이드카는 동일한 모델을 CPU에서 실행하고 격하 모드를 보고합니다. 처리량은 떨어질 수 있지만 정확성은 그렇지 않습니다. 벡터 형태는 어느 쪽이든 동일합니다. 사이드카는 선택 사항으로 유지됩니다. 가용성 검사와 사이드카가 없을 때의 타입이 지정된 예외는 가속을 숨겨진 의존성이 아니라 의도적인 옵트인으로 유지합니다. 이 분리 덕분에 고용량 임베딩은 전용 하드웨어에서 확장할 수 있으면서, 문서 파이프라인은 평범한 PHP 호출로 유지됩니다.

설계 배경: 고용량 문서 생성.

API 표면

공개 표면	종류	목적	안정성	도입 버전
KMS 공급자 팩토리	클래스	환경 또는 명시적 구성으로부터 KMS 공급자를 빌드합니다	안정	2.1.0
KMS 공급자	인터페이스	키 메타데이터를 가져오고, 키를 회전하며, 공급자 이름을 보고합니다	안정	2.1.0
로컬 KMS 공급자	클래스 (공급자 인터페이스 구현)	로컬 HKDF-SHA256 키 파생; 외부 서비스에 연결하지 않습니다	안정	2.1.0
암호화 키 결과	값 객체	불변 키 메타데이터: 키 id, 버전, 알고리즘, 공급자 — 원시 키 바이트 없음	안정	2.1.0
GPU 임베딩 서비스	클래스 (Core 임베딩 서비스 인터페이스 구현)	CPU 폴백을 갖춘 GPU 사이드카에서 텍스트를 임베딩합니다	안정	2.1.0

공급자 팩토리는 “환경으로부터” 진입점과 명시적 “생성” 진입점을 노출합니다. 마스터 키 구성 값은 로컬 공급자에서 민감 항목으로 표시됩니다. 권위 있는 매개변수 및 타입 계약은 nextpdf/enterprise 패키지의 발행된 API 레퍼런스입니다. 이 페이지가 아니라 해당 레퍼런스를 계약으로 취급하십시오.

코드 샘플 — 빠른 시작

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.

코드 샘플 — 프로덕션

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.

환경 변수 이름, 명시적 구성 키, 예외 타입은 Accelerator 심층 레퍼런스에 문서화되어 있습니다.

엣지 케이스 및 함정

로컬 KMS 공급자는 최소 32바이트의 16진수 인코딩된 마스터 키를 요구합니다. 더 짧거나 16진수가 아닌 값은 생성 시점에 타입이 지정된 인자 예외를 발생시킵니다.
해당 통합이 설치되지 않은 상태에서 클라우드 공급자 이름을 선택하면 누락된 의존성을 명시하는 타입이 지정된 구성 오류가 발생합니다.
알 수 없는 공급자 이름은 지원되는 이름을 나열하는 타입이 지정된 오류를 발생시킵니다.
GPU 사이드카는 CPU로 폴백할 때 격하 모드를 보고합니다. GPU 처리량에 의존한다면 해당 필드를 확인하십시오.
임베딩 모델은 첫 요청에서 로드됩니다. 첫 요청 타임아웃을 그에 맞게 설정하십시오.

성능

로컬 키 파생은 상수 비용의 HKDF 연산입니다. 외부 서비스에 연결하지 않습니다. GPU 임베딩 요청은 사이드카로의 로컬 왕복 1회와 모델 추론 시간을 추가합니다. 첫 요청은 일회성 모델 로드 비용도 부담합니다. CPU 폴백은 정확하지만 동일한 배치에 대해 GPU 경로보다 느립니다.

보안 참고

KMS 공급자는 원시 키 바이트가 아니라 키 메타데이터를 반환합니다. 암호화 키 결과 값 객체는 키 자료를 결코 담지 않습니다.
로컬 공급자 마스터 키는 민감한 생성자 매개변수입니다. 로그에 기록되지 않으며 직렬화되지 않습니다.
로컬 공급자는 외부 서비스에 연결하지 않습니다. 파생은 결정적이며 인프로세스로 수행됩니다.
AES-GCM 사용은 NIST SP 800-38D §5에 따라 키마다 고유한 초기화 벡터를 요구합니다.

데이터 레지던시 및 PII 완화

로컬 KMS 공급자는 인프로세스로 실행되며 외부 서비스에 연결하지 않습니다. 로컬 키 파생을 위해 어떤 키 자료나 문서 콘텐츠도 호스트를 벗어나지 않습니다. GPU 사이드카는 임베딩할 텍스트를 로컬 요청을 통해 수신합니다. 관련 없는 문서 콘텐츠는 수신하지 않습니다. 클라우드 KMS 공급자는 구성되면 선택한 클라우드 공급자에 연결합니다. 해당 공급자의 데이터 레지던시 태세를 귀하의 관할권에 대해 검토하십시오.

안전한 텔레메트리 및 로그 스크러빙

로컬 공급자 마스터 키는 민감한 생성자 매개변수이며 로그 및 직렬화에서 제외됩니다. 마스터 키, 파생된 키, 공급자 자격 증명을 자체 애플리케이션 로그에 추가하지 마십시오. 모든 키 자료를 로깅 및 추적 정책에서 비밀로 취급하십시오.

위협 모델

공급자는 키 바이트가 아니라 메타데이터를 반환하므로, 메타데이터 누출이 키 자료를 노출하지 않습니다. 로컬 공급자의 보안은 구성된 마스터 키의 기밀성에 달려 있습니다. 클라우드 공급자의 보안은 해당 공급자와 귀하의 구성에 달려 있습니다. 키 보호는 이 소프트웨어 단독이 아니라 KMS 또는 마스터 키 비밀, 배포, 그리고 운영자에 달려 있습니다. 배포 경계를 참조하십시오.

적합성

데이터 암호화 키 버전 및 회전 수명 주기는 NIST SP 800-57 Part 1 Rev.5 §4에 부합합니다.
키 보호 책임은 NIST SP 800-57 Part 1 Rev.5 §5.5.2에 부합합니다.
AES-GCM 초기화 벡터 고유성은 NIST SP 800-38D §5에 부합합니다.

모든 규범적 출처는 의역되었습니다. 이 페이지에는 규범 텍스트를 재현하지 않습니다. 이 페이지는 키 관리에 관한 것입니다.

FIPS 모드 동작

로컬 공급자의 HKDF 파생은 SHA-256을 사용합니다. 키 메타데이터에 기록되는 암호화 알고리즘은 AES-256-GCM입니다. 애플리케이션이 FIPS 검증 암호화 공급자에 대해 실행되면, 해당 프리미티브는 그 검증된 경계 안에서 실행됩니다. 공급자 팩토리 자체는 공급자를 선택하고 생성할 뿐, 암호화 경계를 인증하지 않습니다.

NextPDF Enterprise는 FIPS 검증 암호화 모듈이 아니며 어떠한 FIPS 인증 주장도 하지 않습니다. FIPS 검증 암호화 공급자 또는 FIPS 검증 KMS와 함께 구성된 경우에만 FIPS 호환 모드로 작동합니다.

에디션 경계

GPU 임베딩 사이드카와 KMS 공급자 팩토리는 nextpdf/enterprise 패키지로만 제공됩니다. NextPDF Pro는 서명 전략을 위한 KMS 통합(AWS KMS, GCP Cloud KMS, Azure Key Vault)을 제공하지만 Enterprise KMS 공급자 팩토리나 GPU 임베딩 사이드카는 제공하지 않습니다. 내부 사이드카 전송과 내부 임베딩 파이프라인 클래스는 공개 표면의 범위 밖이며 여기에서 재현하지 않습니다.

Pro 폴백

NextPDF Pro는 클라우드 KMS 서명 전략을 제공합니다 — KMS가 서명 키를 보관하고, Pro는 서명된 속성 다이제스트를 공급자로 전송합니다. 이는 서명 통합입니다. Enterprise 컬렉션 수준 데이터 암호화 키 공급자 팩토리가 아니며 GPU 임베딩 사이드카도 아닙니다. Pro 가속 표면은 Accelerator — NextPDF Pro를 참조하십시오.

Core 폴백

NextPDF Core에는 GPU 임베딩 사이드카가 없고 KMS 공급자 팩토리도 없습니다. 임베딩과 컬렉션 수준 키 관리는 Enterprise 전용 기능입니다.

Enterprise 경계 참고

GPU 사이드카 전송, 임베딩 모델 식별자, 내부 파이프라인 클래스는 동작 수준에서만 설명됩니다. 내부 전송 클라이언트, 내부 스코프 토큰, 내부 파이프라인 구성은 공개 표면의 범위 밖이며 여기에서 재현하지 않습니다.

배포 경계

NextPDF Enterprise는 KMS와 통합되거나 구성된 마스터 키 비밀로부터 키를 파생합니다. 그 자체가 해당 마스터 키 비밀이나 클라우드 KMS 키를 저장하거나 보안을 보장하지는 않습니다. 키 보안은 NextPDF Enterprise 단독이 아니라 KMS 또는 마스터 키 비밀, 배포, 그리고 운영자에 달려 있습니다. 운영자는 마스터 키 프로비저닝, 비밀 저장, KMS 구성, 회전 일정을 책임집니다. 키 보호 책임은 NIST SP 800-57 Part 1 Rev.5 §5.5.2를 따릅니다. NextPDF Enterprise는 이 문서에서 KMS 자격 증명 흐름이나 마스터 키 처리 내부를 노출하지 않습니다.

법률 준수 경계

이 페이지는 키 관리에 관한 내용입니다. FIPS 모드 진술은 호환성 진술이며, 인증이나 법률 의견이 아닙니다. 규제 의무는 자체 준수 담당자 및 법률 자문에게 확인하십시오.

발행 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.

동작 계약

공급자 팩토리는 구성으로부터 공급자를 선택하고, 공급자 계약을 충족하는 공급자를 반환합니다.
공급자는 불변 키 메타데이터를 반환하며 원시 키 바이트를 결코 반환하지 않습니다.
회전 호출은 키 버전을 진행시키고 새 메타데이터를 반환합니다. 호출자가 컬렉션 데이터를 다시 암호화합니다.
GPU 사이드카는 CPU 폴백 시 격하 모드를 보고하며, 사용 불가능할 때 타입이 지정된 예외를 발생시킵니다.