Enterprise phiên bản

Certificate Transparency — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tham chiếu chuyên sâu cho bề mặt Certificate Transparency (CT) trong NextPDF Enterprise. Bề mặt này là một đối tượng giá trị bất biến duy nhất: NextPDF\Enterprise\Security\CertificateTransparency\CtValidationResult. Nó tóm tắt trạng thái Signed Certificate Timestamp (SCT) của một chứng chỉ ký X.509. Nó mang cờ phần mở rộng SCT, tổng số và số SCT hợp lệ, cùng các định danh log phát hành. Nó phơi bày một phương thức chính sách, meetsPolicy(), vốn là một phép kiểm tra ngưỡng SCT tối thiểu. Kiểu này biểu diễn một kết quả; nó không trích xuất SCT, không xác minh chữ ký SCT, và không liên hệ các CT log. Về hướng dẫn ở cấp quy trình làm việc, xem Chính sách Certificate Transparency cho chứng chỉ ký.

Tình trạng khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một phong bì giấy phép cấp Enterprise. Một triển khai không có quyền đó 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à nhận giấy phép.

Bề mặt API công khai

Symbol	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`CtValidationResult`	—	Đối tượng giá trị bất biến tóm tắt trạng thái SCT của một chứng chỉ	—	Không ném	`final readonly`; cả bốn thuộc tính được thăng cấp từ hàm khởi tạo đều là public
`CtValidationResult::__construct`	`bool $hasSctsExtension`, `int $totalScts`, `int $validScts`, `array<string> $logIds`	Lưu các giá trị được cung cấp đúng như nó vốn có, không xác thực hay đối chiếu	Một thể hiện `CtValidationResult` mới	Không khai báo `@throws`; PHP phát sinh `TypeError` khi kiểu đối số không khớp dưới `strict_types`	Các thuộc tính public `readonly` được thăng cấp
`CtValidationResult::meetsPolicy`	`int $minimumScts = 2`	So sánh số SCT hợp lệ với ngưỡng: `validScts >= $minimumScts`	`bool`	Không ném	Chỉ đếm các SCT hợp lệ; không kiểm tra tính riêng biệt của log hay sự hiện diện của phần mở rộng

final readonly class CtValidationResult

public function __construct(
    public bool $hasSctsExtension,
    public int $totalScts,
    public int $validScts,
    public array $logIds,
) {}

public function meetsPolicy(int $minimumScts = 2): bool

Các thuộc tính public readonly

Thuộc tính	Kiểu	Ý nghĩa
`$hasSctsExtension`	`bool`	Liệu chứng chỉ có chứa phần mở rộng SCT hay không
`$totalScts`	`int`	Tổng số SCT tìm thấy trong phần mở rộng
`$validScts`	`int`	Số SCT có chữ ký hợp lệ, như được xác định ở phía thượng nguồn
`$logIds`	`array<string>`	Các định danh log (băm SHA-256) của các CT log đã phát hành các SCT

Hợp đồng hành vi

CtValidationResult là một giá trị kết quả. Nó biểu diễn kết cục của việc trích xuất và xác minh SCT mà môi trường của bên gọi đã thực hiện. Nó không phân tích chứng chỉ, không xác minh chữ ký SCT, không truy vấn log, và không gửi chứng chỉ tới log.
Phần mở rộng đang được đề cập là phần mở rộng chứng chỉ X.509v3 chứa SCT nhúng, được nhận diện bởi OID 1.3.6.1.4.1.11129.2.4.2 — RFC 6962 §3.3. Một SCT mang một version, một định danh log, một dấu thời gian, các phần mở rộng, và chữ ký log trên mục nhập — RFC 6962 §3.2.
Mỗi mục trong $logIds là một định danh log như định nghĩa bởi RFC 6962 §3.2: băm SHA-256 của khóa công khai của log trên SubjectPublicKeyInfo được mã hóa DER của nó. Kiểu này lưu các chuỗi đúng như được cung cấp và không tính lại hay xác thực chúng.
meetsPolicy() hiện thực đúng một phép so sánh: số SCT hợp lệ lớn hơn hoặc bằng ngưỡng. Ngưỡng mặc định là 2.
meetsPolicy() không tham vấn $hasSctsExtension. Một chính sách phải thất bại khi thiếu phần mở rộng sẽ kiểm soát trên thuộc tính đó riêng biệt, trước hoặc song song với phép kiểm tra ngưỡng.
meetsPolicy() không loại trùng lặp $logIds. Một chính sách yêu cầu SCT từ các log độc lập sẽ kiểm tra tính riêng biệt thông qua chính $logIds.
Hàm khởi tạo lưu đầu vào nguyên văn. Nó không thực hiện kiểm tra phạm vi và không kiểm tra tính nhất quán giữa các trường.
Các thể hiện là bất biến (final readonly). Mọi thao tác đọc và phép kiểm tra ngưỡng đều mang tính tất định và không gây tác dụng phụ.
Giá trị ngưỡng là lựa chọn chính sách của người vận hành; NextPDF không áp đặt con số nào. Mã nguồn của gói chú giải một điểm tham chiếu trong hệ sinh thái: chính sách CT của Chrome, tính đến năm 2024, kỳ vọng ít nhất hai SCT từ các log khác nhau đối với các chứng chỉ có vòng đời tối đa 180 ngày, và ba đối với các chứng chỉ có vòng đời dài hơn. Đó là một chính sách chương trình trình duyệt, không phải yêu cầu của IETF.
Vị trí đặt dự kiến là một cổng tiền-ký: một quy trình ký từ chối khởi tạo một signer khi phép kiểm tra thất bại. Lý lẽ tuân theo mô hình tin cậy của CT: một SCT là lời hứa của log về việc kết nạp chứng chỉ, và các bên tin cậy từ chối một chứng chỉ thiếu một SCT hợp lệ — RFC 6962 §3. CT version 2.0 giữ nguyên mô hình đó: một log chấp nhận một lần gửi sẽ trả về một SCT, mà người gửi xác thực trước khi tin cậy vào nó — RFC 9162 §3.

Các trường hợp biên & chế độ thất bại

Ngưỡng bằng không hoặc âm. meetsPolicy(0) trả về true với bất kỳ $validScts không âm nào. Phương thức không từ chối giá trị. Hãy chọn một ngưỡng ít nhất là 1.
Phần mở rộng vắng mặt, số đếm dương. Khi $hasSctsExtension là false nhưng $validScts đạt ngưỡng, meetsPolicy() vẫn trả về true. Cổng phải kiểm tra $hasSctsExtension một cách tường minh khi sự vắng mặt phải làm thất bại; trang năng lực trình bày mẫu này.
Định danh log trùng lặp. N SCT hợp lệ từ một log duy nhất thỏa mãn một ngưỡng N. Phép kiểm tra ngưỡng không đưa ra tuyên bố nào về tính độc lập. Các chính sách về tính riêng biệt của log sẽ xem xét $logIds.
Số đếm không nhất quán. Một $validScts lớn hơn $totalScts, hoặc một số đếm âm, được lưu đúng như được cung cấp. Không có ngoại lệ nào được phát sinh. Bước trích xuất ở thượng nguồn chịu trách nhiệm về tính nhất quán của đầu vào.
Chuỗi định danh log chưa được xác thực. Kiểu này không áp đặt hình dạng 32-byte hay thập lục phân trên các mục của $logIds. Các định danh sai định dạng được truyền qua nguyên vẹn.
Không có đường ngoại lệ. Không phương thức nào trên bề mặt này ném dưới các kiểu PHP hợp lệ. Chế độ thất bại của phép kiểm tra chính sách là sự từ chối (false), không phải một ngoại lệ. Kiểu đối số không khớp sẽ phát sinh một TypeError của PHP dưới strict_types, như với bất kỳ API PHP có kiểu nào.

Hành vi trong chế độ FIPS

CtValidationResult không thực hiện tính toán mật mã nào. Nó không tính bản tóm tắt và không xác minh chữ ký nào. Việc một chữ ký SCT có được tính là hợp lệ hay không được quyết định ở thượng nguồn, bởi thành phần đã thực hiện xác minh trước khi khởi tạo kết quả. Do đó, hồ sơ chính sách mật mã FIPS 140-3 của Enterprise, được ghi tài liệu cùng với mô-đun bảo mật, không làm thay đổi hành vi của kiểu này.

Tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản
Một SCT là lời hứa của log về việc kết nạp chứng chỉ; các bên tin cậy từ chối một chứng chỉ thiếu một SCT hợp lệ.	RFC 6962	§3
Một SCT mang một version, một định danh log, một dấu thời gian, các phần mở rộng, và chữ ký log trên mục nhập.	RFC 6962	§3.2
Định danh log là băm SHA-256 của khóa công khai của log trên `SubjectPublicKeyInfo` được mã hóa DER của nó.	RFC 6962	§3.2
Các SCT nhúng đi kèm một phần mở rộng chứng chỉ X.509v3 được nhận diện bởi OID `1.3.6.1.4.1.11129.2.4.2`.	RFC 6962	§3.3
Trong CT version 2.0, một log chấp nhận một lần gửi sẽ trả về một SCT, mà người gửi xác thực trước khi tin cậy vào nó.	RFC 9162	§3

Tất cả các điều khoản đều được diễn giải; NextPDF không tái tạo văn bản quy phạm. NextPDF không đưa ra tuyên bố tuân thủ hay chứng nhận Certificate Transparency nào. NextPDF Enterprise không phải là một CT log, một kiểm toán viên, hay một bộ giám sát. Nó không gửi chứng chỉ tới log và nó không khẳng định một kết cục xác minh CT. Kiểu này biểu diễn các số đếm và định danh mà môi trường của bên gọi đã tạo ra, và nó đánh giá một ngưỡng do bên gọi chọn. Các chương trình CT của trình duyệt, chẳng hạn của Chrome, là các chính sách hệ sinh thái chứ không phải các yêu cầu quy phạm của IETF; việc lựa chọn và thỏa mãn một chính sách như vậy là trách nhiệm của người vận hành.

Ghi chú phát triển

Đối tượng giá trị không có phụ thuộc và không có I/O. Hãy khởi tạo các thể hiện trực tiếp trong các bài kiểm thử đơn vị.
Các bài kiểm thử biên được khuyến nghị: số đếm hợp lệ đúng bằng ngưỡng, một đơn vị dưới ngưỡng, phần mở rộng vắng mặt với số đếm ở ngưỡng, và các định danh log trùng lặp đối chiếu với một chính sách về tính riêng biệt.
Lớp được khai báo dưới strict_types=1 với các thuộc tính được thăng cấp có kiểu. Kiểu đối số sai sẽ phát sinh một TypeError của PHP trong bên gọi.
Lớp mang một chú giải @since cấp gói là 1.0.0 và tham chiếu RFC 6962 và RFC 9162 trong tài liệu nguồn của nó.
Tham số $logIds được ghi tài liệu là array<string>; phân tích tĩnh xem thuộc tính này là một mảng các chuỗi. Hãy giữ nguyên hình dạng đó khi khởi tạo các kết quả.
Hãy đặt việc xác minh CT ở thượng nguồn của bạn và cổng ngưỡng này trước khi khởi tạo signer, để một chứng chỉ được ghi log chưa đủ không bao giờ chạm tới một thao tác ký. Trang năng lực ghi tài liệu về quy trình làm việc và một ví dụ cổng đã được xử lý hoàn chỉnh.

Xem thêm

Chính sách Certificate Transparency cho chứng chỉ ký — trang năng lực: quy trình làm việc, cấu hình, và một cổng chính sách đã được xử lý hoàn chỉnh.
Bảo mật — NextPDF Enterprise — bề mặt bảo mật Enterprise hợp nhất.
Chữ ký — Tham chiếu chuyên sâu — bộ sản xuất dài hạn PAdES B-LT và B-LTA.
Bảo mật / Ký (Core) — signer CMS của Core và hợp đồng chiến lược ký.
Certificate Transparency · SCT — các thuật ngữ trong bảng chú giải.

Ranh giới xuất bản

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