Enterprise 에디션

Contracts — 심층 참조

한눈에 보기

Contracts 모듈은 RFC 3161 Time Stamp Authority 클라이언트를 위한 Enterprise 통합 이음새입니다.

TsaClientInterface는 단일 연산을 선언합니다. 미리 계산된 문서 다이제스트에 대해 DER로 인코딩된 TimeStampToken을 요청합니다.
TsaClientAdapter는 final 클래스인 Core 타임스탬프 클라이언트를 동작 변경 없이 해당 인터페이스에 연결합니다.
LtvManager 및 DocumentTimestamp와 같은 Enterprise 컴포넌트는 이 인터페이스를 받으므로, TSA 동작은 테스트에서 주입 가능하고 대체 가능합니다.
이음새를 넘는 것은 문서 해시뿐이며, 문서 콘텐츠는 결코 넘지 않습니다.

워크플로 안내는 Contracts 기능 페이지를 먼저 읽으십시오.

제공 및 라이선싱

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 포함되어 제공되며 Enterprise 등급 라이선스 엔벨로프로 활성화됩니다. 해당 엔타이틀먼트가 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

인터페이스는 아무런 작업도 수행하지 않으며 자체적으로 어떤 것도 게이트하지 않습니다. 이를 소비하는 Enterprise 표면은 compliance-evidence 표면의 enterprise.compliance.evidence와 같은 자체 기능 코드를 적용합니다.

등급	제공 내용
Core	RFC 3161 요청을 수행하는 구체적인 `TsaClient`(`final`)
Pro	Contracts 모듈에 해당하는 것 없음
Enterprise	`TsaClientInterface` 이음새 및 `TsaClientAdapter` 브리지

composer require nextpdf/enterprise:^3

공개 API 표면

심볼	매개변수	기본 동작	반환값	예외 또는 실패 조건	참고
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	미리 계산된 문서 다이제스트에 대한 타임스탬프 토큰 요청을 선언	`string` — DER로 인코딩된 TimeStampToken	구현 정의; 인터페이스는 예외를 선언하지 않음	유일한 연산; 소스는 SHA-256 다이제스트 입력을 문서화
`TsaClientAdapter::__construct()`	`TsaClient $client`	Core 타임스탬프 클라이언트를 저장	`TsaClientAdapter`	선언된 것 없음	`final readonly`; 생성자 프로모션
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	`TsaClient::getDocumentTimestamp()`로 변경 없이 전달	`string` — DER로 인코딩된 TimeStampToken	Core 클라이언트의 `TsaException`을 변경 없이 전달	동작을 추가하지 않음; 아무것도 삼키지 않음

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

동작 계약

TsaClientInterface::getDocumentTimestamp(string $documentHash): string는 문서 해시에 대한 DER로 인코딩된 RFC 3161 TimeStampToken을 반환합니다. 외부에서 관찰 가능한 규칙은 다음과 같습니다.

인터페이스는 단일 연산을 선언합니다. 토큰을 검증하거나, TSA를 보증하거나, 법적 효력을 단언하지 않습니다.
TsaClientAdapter는 호출을 Core 타임스탬프 클라이언트로 변경 없이 전달합니다 — 추가 동작 없음, 추가 재시도 없음, 예외 삼킴 없음, 추가 보증 없음. 그 유일한 목적은 의존성 역전과 테스트를 위해 final Core 클라이언트가 Enterprise 대상 인터페이스를 충족하도록 하는 것입니다.
문서 해시만 경계를 넘으며, 문서 콘텐츠는 전달되지 않습니다.
어댑터 뒤에서 Core 클라이언트는 구성된 임프린트 알고리즘과 길이가 일치하지 않는 다이제스트를 네트워크 활동 이전에 TsaException으로 fail-closed 방식으로 거부합니다. 그렇지 않으면 잘못 레이블된 임프린트는 어떤 적합한 검증기도 바인딩할 수 없는 토큰을 생성할 것입니다.
소비 표면: LtvManager는 선택적 TsaClientInterface를 받으며 PAdES B-LTA에는 이를 필수로 요구합니다. DocumentTimestamp는 이 계약을 사용하여 /DocTimeStamp 서명 딕셔너리의 /Contents를 채웁니다. LTV 아카이브 갱신 실행기(LtvaRenewalExecutor)는 문서 타임스탬프를 갱신할 때 Core 클라이언트를 TsaClientAdapter로 감쌉니다.

엣지 케이스 및 실패 모드

어댑터는 기반 클라이언트의 예외를 변경 없이 전달합니다. TSA 실패는 호출 지점에서 처리해야 합니다.
다이제스트는 구체적인 클라이언트의 구성된 임프린트 알고리즘(기본 SHA-256, 32바이트) 하에서 원시 바이너리여야 합니다. 16진수로 인코딩된 다이제스트는 길이가 잘못되어 어떤 요청도 전송되기 전에 거부됩니다.
반환된 토큰은 판정이 아니라 바이트입니다. 필요한 곳에서 검증하십시오.
사용자 정의 구현은 자체 실패 표면을 소유합니다. 계약은 반환 형태, 즉 DER로 인코딩된 TimeStampToken만을 고정합니다.

FIPS 모드 동작

이 모듈은 어떠한 암호화 연산도 수행하지 않습니다. 알고리즘 선택과 FIPS 모드 동작은 구체적인 TSA 클라이언트와 Security 모듈이 관장합니다. FIPS 140 심층 참조를 참조하십시오.

적합성

동작	참조
타임스탬프 토큰 요청 및 바인딩	IETF RFC 3161 §2
TimeStampReq는 MessageImprint를 포함합니다: 해시 알고리즘 식별자와 타임스탬프 대상 데이터의 해시	IETF RFC 3161 §2.4.1
토큰의 messageImprint는 요청의 값과 같아야 하며, 해시 크기는 식별된 알고리즘과 일치해야 합니다	IETF RFC 3161 §2.4.2

계약은 RFC 3161을 중심으로 형성됩니다. 실제 토큰 요청과 모든 검증은 구체적인 클라이언트와 Evidence/Signature 표면이 수행합니다. 인터페이스는 어떠한 적합성 또는 증명 주장도 하지 않습니다. NextPDF는 어떠한 인증 주장도 하지 않습니다.

개발 참고 사항

두 타입 모두 @since 3.0.0을 가집니다. 이 참조는 nextpdf/enterprise 3.1.0에 포함되어 제공되는 표면을 문서화합니다.
타임스탬프가 필요한 컴포넌트에 TsaClientInterface를 주입하고, 구성 루트에서 TsaClientAdapter 또는 사용자 정의 구현을 연결하십시오. 단위 테스트에서는 실제 TSA 대신 테스트 더블을 대체하십시오.
운영자는 어댑터 뒤의 구체적인 TSA 클라이언트를 소유합니다. 레지던시, TSA 엔드포인트 신뢰 경계, 인증서 체인 검증은 이 인터페이스가 아니라 그 클라이언트에 적용됩니다.
이 계약 표면에는 수출 통제 제한이 적용되지 않습니다. 타임스탬프 토큰을 획득하는 것은 감사 및 장기 검증 워크플로를 지원합니다. 법적 증명이나 인증이 아닙니다. 이 참조는 법률 의견이 아닙니다.
내부 메커니즘 세부 사항은 소스 리포지토리의 내부 문서에 남아 있으며 이 매뉴얼의 범위를 벗어납니다.

공개 범위 경계

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