Enterprise phiên bản

Validation — tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Module Validation chạy các chính sách tuân thủ cấu trúc chỉ đọc, dựng sẵn trên các byte PDF thô. Compliance::assess() áp dụng đúng một CompliancePolicy và trả về một ComplianceReport với các kết quả phát hiện được phân vùng theo mức độ nghiêm trọng cùng một tuyên bố miễn trừ trách nhiệm pháp lý bắt buộc. Có sẵn chính sách cho PDF/A-4 (cùng các biến thể e và f), cấu trúc baseline PAdES, một hồ sơ cấu trúc eIDAS, tình trạng LTV/DSS, ZUGFeRD / Factur-X, FDA 21 CFR Part 11, và lưu trữ WORM theo SEC Rule 17a-4. Mọi chính sách là một hàm thuần túy: byte vào, kết quả phát hiện ra. Validation không bao giờ thay đổi tài liệu và không bao giờ thực hiện xác minh bằng mật mã.

Tính khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và được kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có quyền sử dụng đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Bề mặt Validation/Evidence được cấp phép bởi năng lực enterprise.compliance.evidence. Một quyền sử dụng bị từ chối sẽ từ chối tính năng thay vì âm thầm suy giảm.

Bậc	Bề mặt Validation
Core	Các trình xác thực luồng byte trong tiến trình và một kiểm tra chéo ngữ pháp; một kết quả không có phát hiện nào là một kết quả đã được kiểm tra, không phải một chứng nhận.
Pro	Xác thực EN 16931 / Factur-X / ZUGFeRD trong tiến trình ở lớp hóa đơn điện tử; không có chính sách dựng sẵn cho PDF/A-4, PAdES, LTV, FDA, hay SEC.
Enterprise	Các chính sách cấu trúc dựng sẵn cho PDF/A-4, PAdES, LTV, ZUGFeRD, FDA Part 11, và SEC 17a-4 với một báo cáo thống nhất (module này).

Gateway external-sidecar của Enterprise Compliance là một module riêng biệt, khác biệt.

Bề mặt API công khai

composer require nextpdf/enterprise:^3

Symbol	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`Compliance::__construct`	`?ClockInterface $clock = null`	Đồng hồ hệ thống khi không tiêm đồng hồ nào	—	—	Dạng thể hiện thân thiện với DI; đồng hồ đóng dấu `validatedAt`
`Compliance::run`	`string $pdfData`, `CompliancePolicy $policy`, `array $context = []`	Áp dụng đúng một chính sách và đo thời lượng wall-clock	`ComplianceReport`	Truyền tiếp các ngoại lệ từ chính sách tùy chỉnh; các chính sách dựng sẵn thu thập kết quả phát hiện thay vì ném ra	Phương thức thể hiện
`Compliance::assess` (static)	`string $pdfData`, `CompliancePolicy $policy`, `array $context = []`	Khởi tạo một thể hiện mặc định và ủy quyền cho `run()`	`ComplianceReport`	Giống như `run()`	Đường nhanh không cần cấu hình
`Policies::pdfA4` / `::pdfA4e` / `::pdfA4f` (static)	—	Chính sách cấu trúc PDF/A-4 theo ISO 19005-4:2020	`CompliancePolicy`	—	`e` cho phép chú thích 3D/rich-media; `f` bổ sung kiểm tra quan hệ tệp nhúng
`Policies::padesBaseline` (static)	—	Kiểm tra cấu trúc PAdES B-B	`CompliancePolicy`	—	Chỉ cấu trúc; không xác minh bằng mật mã
`Policies::eidasQualified` (static)	—	Kiểm tra cấu trúc PAdES dưới một hồ sơ được gán nhãn eIDAS	`CompliancePolicy`	—	Trình độ phụ thuộc vào TSP và chứng chỉ đủ điều kiện
`Policies::ltvHealth` (static)	—	Kiểm tra tình trạng cấu trúc DSS	`CompliancePolicy`	—	Sự hiện diện của DSS được phân giải từ đồ thị đối tượng đang hoạt động, fail-closed
`Policies::zugferd` (static)	`string $profile = 'BASIC'`	Chuẩn hóa bí danh hồ sơ và dựng trình xác thực ZUGFeRD	`CompliancePolicy`	`\ValueError` (hồ sơ không xác định)	Các hồ sơ: `MINIMUM`, `BASIC`, `BASIC_WL`, `EN16931`, `EXTENDED`
`Policies::fdaPart11` (static)	—	Chính sách cấu trúc FDA 21 CFR Part 11	`CompliancePolicy`	—	Bảy kiểm tra cấu trúc, bao gồm tính toàn vẹn hash-chain của dấu vết kiểm toán
`Policies::sec17a4` / `::sec17a4Compatible` / `::sec17a4Structural` / `::sec17a4PreSign` (static)	—	Chính sách WORM SEC 17a-4 ở độ nghiêm ngặt được nêu tên	`CompliancePolicy`	—	Độ nghiêm ngặt ánh xạ tới `WormComplianceLevel`
`CompliancePolicy` (interface)	—	Hợp đồng chiến lược cho một tiêu chuẩn	—	—	`getName()`, `getIdentifier()`, `getStandardReference()`, `validate()`; khách hàng có thể triển khai
`ComplianceReport`	Đối tượng giá trị chỉ đọc	Kết quả phát hiện được phân vùng theo mức độ nghiêm trọng khi khởi tạo	—	—	`passes()`, `fails()`, `totalFindings()`, `getDisclaimer()`; công khai `findings`, `errors`, `warnings`, `infos`, `policyName`, `policyId`, `standard`, `validatedAt`, `durationMs`
`ComplianceFinding`	`Severity $severity`, `string $ruleId`, `string $message`, `string $clause = ''`, `string $suggestion = ''`	Một kết quả quy tắc kèm tham chiếu điều khoản và gợi ý khắc phục	—	—	Tĩnh `error()` / `warning()` / `info()`; `isError()`
`Severity` (enum)	3 case backed bằng string	`Error`, `Warning`, `Info`	—	—	Chỉ `Error` làm một báo cáo thất bại
`WormComplianceLevel` (enum)	4 case backed bằng string	`Full`, `Compatible`, `Structural`, `PreSign`	—	—	`requiresSignature()`, `requiresDocMdp()`, `requiresLtv()`, `maxDocMdpLevel()`
`PdfAPolicy`, `PadesValidator`, `LtvHealthCheck`, `ZugferdValidator`, `Sec17a4WormPolicy`, `Fda\FdaPart11Policy`	Constructor theo từng lớp	Triển khai `CompliancePolicy` cho mỗi tiêu chuẩn	`list<ComplianceFinding>` từ `validate()`	—	Lấy qua `Policies`; `Sec17a4WormPolicy::getLevel()` phơi bày độ nghiêm ngặt đã cấu hình
`Fda\FdaSigningIntent` (enum)	6 case backed bằng string	`Authoring`, `Review`, `Approval`, `Certification`, `Verification`, `Rejection`	—	—	`toPdfReasonString()` tạo ra chuỗi `/Reason` chuẩn tắc
`Fda\FdaAuditEvent::__construct`	`DateTimeImmutable $timestamp`, `string $actor`, `FdaSigningIntent $action`, `string $documentHash`, `string $certificateSerial`, `string $previousEventHash = ''`	Tính hash chuỗi SHA-256 khi khởi tạo	—	`InvalidArgumentException` (timestamp không phải UTC)	Công khai `eventHash`; `toXmpRdf()` tuần tự hóa một mục danh sách XMP
`Fda\FdaAuditTrail::addEvent`	`FdaAuditEvent $event`	Thêm sự kiện khi liên kết chuỗi của nó khớp với đuôi của trail	`self`	`InvalidArgumentException` (hash chain bị hỏng)	Còn có `createEvent()`, `verifyChain()`, `getLastEventHash()`, `getEvents()`, `embedInMetadata()`
`Fda\FdaSignatureEnforcer::configureSeedValue`	`FdaSigningIntent $intent`, `string $tsaUrl`	Dựng một cấu hình seed-value chữ ký bị ràng buộc theo FDA	`SeedValueConfig`	—	Yêu cầu bộ lý do FDA, một timestamp, và digest SHA-256 hoặc mạnh hơn
`Fda\FdaSignatureEnforcer::applyTo`	`SequentialSigner $signer`, `SigningStrategy $strategy`, `string $signerName`, `FdaSigningIntent $intent`, `string $tsaUrl`, `string $fieldName = ''`, `?string $reason = null`	Thêm một signer bị ràng buộc theo FDA vào một `SequentialSigner` của Pro	`SequentialSigner`	—	Tuần tự hóa các ràng buộc vào trường chữ ký được tạo ra

namespace NextPDF\Enterprise\Validation;

final readonly class Compliance
{
    public function __construct(?ClockInterface $clock = null);

    /** @param array<string, mixed> $context */
    public function run(string $pdfData, CompliancePolicy $policy, array $context = []): ComplianceReport;

    /** @param array<string, mixed> $context */
    public static function assess(string $pdfData, CompliancePolicy $policy, array $context = []): ComplianceReport;
}

final class Policies
{
    public static function pdfA4(): CompliancePolicy;      // also pdfA4e(), pdfA4f()
    public static function padesBaseline(): CompliancePolicy;
    public static function eidasQualified(): CompliancePolicy;
    public static function ltvHealth(): CompliancePolicy;
    public static function zugferd(string $profile = 'BASIC'): CompliancePolicy;
    public static function fdaPart11(): CompliancePolicy;
    public static function sec17a4(): CompliancePolicy;    // also sec17a4Compatible(), sec17a4Structural(), sec17a4PreSign()
}

interface CompliancePolicy
{
    public function getName(): string;

    public function getIdentifier(): string;

    public function getStandardReference(): string;

    /**
     * @param array<string, mixed> $context
     * @return list<ComplianceFinding>
     */
    public function validate(string $pdfData, array $context = []): array;
}

final readonly class ComplianceReport
{
    public const string LEGAL_DISCLAIMER;

    public function passes(): bool;

    public function fails(): bool;

    public function totalFindings(): int;

    public function getDisclaimer(): string;
}

Hợp đồng hành vi

Compliance::assess() (static) và Compliance::run() (thể hiện, cùng một Psr\Clock\ClockInterface có thể tiêm) áp dụng đúng một chính sách và trả về một ComplianceReport. Các quy tắc có thể quan sát được từ bên ngoài:

Thuần túy chỉ đọc. Mỗi CompliancePolicy::validate() là một hàm thuần túy: byte vào, kết quả phát hiện ra. Một chính sách không bao giờ thay đổi byte PDF. Bất biến kiến trúc này giữ cho việc xác thực tách biệt với tự động sửa và với module Evidence.
Cổng mức độ nghiêm trọng. ComplianceReport::passes() chỉ true khi errors === []. Cảnh báo và info không bao giờ làm một báo cáo thất bại. fails() là phần bù.
Tuyên bố miễn trừ bắt buộc. ComplianceReport::getDisclaimer() trả về văn bản tuyên bố miễn trừ trách nhiệm pháp lý cố định. Việc hiển thị nó trong đầu ra hướng tới người dùng là yêu cầu của hợp đồng.
Xuất xứ báo cáo. Báo cáo mang theo tên chính sách, định danh, và tham chiếu tiêu chuẩn từ chính sách, timestamp xác thực từ đồng hồ được tiêm hoặc đồng hồ hệ thống, và thời lượng đo được tính bằng mili-giây.
Thu thập, không hủy bỏ. Các chính sách dựng sẵn chạy tất cả các kiểm tra áp dụng được và thu thập mọi kết quả phát hiện thay vì dừng lại ở lỗi đầu tiên.
Chỉ DSS có thể tới được từ catalog. LtvHealthCheck phân giải sự hiện diện của DSS từ đồ thị đối tượng đang hoạt động: trailer đang hoạt động, rồi catalog /Root, rồi /DSS và các sub-key của nó. Các byte đánh dấu được cài trong chú thích, chuỗi, đối tượng mồ côi, hoặc các bản sửa đổi đã bị thay thế thì không được tính. Đầu vào không phân tích cú pháp được coi như không có DSS, nên kiểm tra fail closed. Kiểm tra này ở mức cấu trúc; nó không xác minh bằng mật mã dữ liệu OCSP/CRL được nhúng.
Kiểm tra chữ ký ở mức cấu trúc. Policies::padesBaseline() và Policies::eidasQualified() chỉ xác thực cấu trúc PAdES ở mức PDF. Trình độ theo eIDAS phụ thuộc vào TSP và chứng chỉ đủ điều kiện, vốn nằm ngoài module này.
Các chính sách của ngành chịu quản lý là về cấu trúc. FdaPart11Policy kiểm tra sự hiện diện của chữ ký, ý định /Reason, thời gian ký /M, danh tính /Name, việc không có JavaScript, namespace dấu vết kiểm toán FDA, và tính toàn vẹn hash-chain. Sec17a4WormPolicy kiểm tra tới 13 quy tắc WORM; WormComplianceLevel chọn độ nghiêm ngặt. Full đòi hỏi DocMDP mức 1, Compatible chấp nhận mức 2, còn Structural / PreSign bỏ qua các quy tắc chữ ký, DocMDP, và DSS. Cả hai chính sách đều không thiết lập sự tuân thủ pháp lý.
Bối cảnh ZUGFeRD. Policies::zugferd() luôn kiểm tra các yêu cầu ở mức PDF. Nó chỉ xác thực XML hóa đơn khi bên gọi truyền ['xml' => $xmlData] trong $context; nếu không, nó phát ra kết quả phát hiện thông tin zugferd-xml-skipped.
Dấu vết kiểm toán có bằng chứng chống giả mạo. FdaAuditTrail là một hash chain SHA-256 chỉ thêm. addEvent() từ chối một liên kết bị hỏng, verifyChain() tái tạo mọi hash, và embedInMetadata() ghi trail vào XMP dưới http://ns.nextpdf.dev/fda/1.0/ với một extension schema PDF/A.

Các trường hợp ngoại lệ & chế độ thất bại

Một đầu vào không phải PDF hoặc rỗng tạo ra các kết quả phát hiện lỗi thay vì một ngoại lệ trong các chính sách dựng sẵn. Luôn kiểm tra passes() và hiển thị tuyên bố miễn trừ.
Policies::zugferd() chuẩn hóa các bí danh hồ sơ (BASIC_WL, EN16931, EN_16931). Một hồ sơ không xác định sẽ phát sinh \ValueError tại thời điểm factory, trước khi bất kỳ việc xác thực nào chạy.
Một DSS có CRL nhưng không có phản hồi OCSP vẫn thỏa mãn kiểm tra vật liệu thu hồi; kết quả phát hiện ghi chú phương án thay thế chấp nhận được. Việc không có cái nào trong hai hiện diện là một lỗi.
Một từ điển /VRI hoặc mảng /Certs bị thiếu tạo ra cảnh báo, không phải lỗi; báo cáo vẫn có thể đạt.
FdaAuditEvent từ chối bất kỳ timestamp không phải UTC nào bằng InvalidArgumentException khi khởi tạo.
FdaAuditTrail::verifyChain() trả về false đối với bất kỳ sự kiện bị giả mạo hoặc sắp xếp lại nào; nó không bao giờ ném ra.
Các triển khai CompliancePolicy tùy chỉnh có thể ném ra từ validate(); Compliance::run() không bắt, nên các ngoại lệ đó truyền tiếp tới bên gọi.

Hành vi ở chế độ FIPS

Module này không thực hiện việc ký nào, không xác minh bằng mật mã nào, và không giữ khóa nào. Chính sách thuật toán ở chế độ FIPS được điều phối bởi các module Security và Signature. Các seed value của FdaSignatureEnforcer ràng buộc các trường chữ ký gắn với FDA vào các phương thức digest SHA-256, SHA-384, hoặc SHA-512.

Sự phù hợp

Các chính sách này kiểm tra các thuộc tính cấu trúc so với các tiêu chuẩn được nêu tên. Phán định về sự phù hợp đối với các hồ sơ ISO/ETSI vẫn là một thuộc tính của tệp cuối cùng cộng với một trình xác thực bên ngoài.

Hành vi	Tài liệu tham chiếu
Sự phù hợp được xác định so với tiêu chuẩn, không phải bộ tạo	ISO 19005-4:2020 §5.2
Từ điển chữ ký số / DSS cho xác thực dài hạn	ISO 32000-2:2020 §12.8
DSS là một từ điển được giữ bởi khóa `DSS` của catalog tài liệu	ISO 32000-2:2020 §12.8.4.3
Các cấp chữ ký baseline PAdES	ETSI EN 319 142-1 §5.4.3
Mô hình ngữ nghĩa hồ sơ EN 16931 (tài liệu tham chiếu hỗ trợ)	Factur-X 1.08 (EN 16931)

Các chính sách FDA 21 CFR Part 11 và SEC 17a-4 chỉ kiểm tra các thuộc tính cấu trúc; những quy định đó nằm ngoài corpus xác minh và không mang theo tuyên bố phù hợp đã xác minh nào. Các chuỗi điều khoản bên trong các kết quả phát hiện FDA (ví dụ §11.50, §11.10(e)) là các tham chiếu quy tắc do sản phẩm phát ra. Hàng EN 16931 là một tài liệu tham chiếu hỗ trợ dưới sàn truy xuất; nó không phải là một tuyên bố phù hợp cứng. Việc hỗ trợ một tiêu chuẩn không phải là sự phù hợp với nó, và sự phù hợp không phải là chứng nhận — NextPDF không có chứng nhận nào và không cấp chứng nhận nào. Tài liệu tham chiếu này không phải là một ý kiến pháp lý; hãy tham vấn đội ngũ tuân thủ của bạn về mức độ đầy đủ về mặt pháp lý.

Ghi chú phát triển

Validation chạy trong tiến trình và cục bộ, không có I/O mạng. Một chính sách không thể thay đổi đầu vào.
Coi byte PDF từ các nguồn không tin cậy là thù địch. Các chính sách dựng sẵn là toàn phần trên các byte tùy ý và fail closed ở nơi không thể phân giải cấu trúc.
Hiển thị ComplianceReport::getDisclaimer() trong mọi lần kết xuất báo cáo hướng tới người dùng.
Các báo cáo và kết quả phát hiện có thể mang theo dữ liệu cá nhân từ các tài liệu đã ký và siêu dữ liệu dấu vết kiểm toán (tên người ký, số sê-ri chứng chỉ). Người vận hành sở hữu các biện pháp kiểm soát lưu giữ và giảm thiểu.
Các chính sách tùy chỉnh triển khai CompliancePolicy; giữ getIdentifier() duy nhất trên tất cả các chính sách để tuần tự hóa và caching.
Module này liên quan đến chức năng mật mã; hãy coi nó là nhạy cảm về bảo mật trong quá trình rà soát của riêng bạn.
Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của kho mã nguồn và nằm ngoài phạm vi của sổ tay này.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi có thể quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.