Enterprise phiên bản

Các mức độ đảm bảo eIDAS

Tổng quan nhanh

NextPDF Enterprise biến bằng chứng trusted-list của EU thành một Mức độ đảm bảo (Level of Assurance, LoA) eIDAS rõ ràng. Dịch vụ NextPDF\Enterprise\Security\Eidas\LoaMapping phân loại một mục dịch vụ tin cậy thành Low, Substantial, hoặc High. Nó trả về một LoaAssertion mang mức độ đó cùng các mã lý do đọc được bằng máy. Quy trình làm việc của bạn có thể chặn dựa trên mức độ đảm bảo — “yêu cầu High” — và lưu trữ các lý do làm bằng chứng kiểm toán. Một guard đồng hành, CertPiiGuard, biên tập các trường danh tính người ký trước khi các bản ghi kiểm toán rời khỏi tiến trình.

Hai ranh giới định hình khả năng này một cách trung thực. Thứ nhất, việc đủ điều kiện (qualification) luôn thuộc về nhà cung cấp dịch vụ tin cậy (TSP) dưới sự giám sát của quốc gia thành viên. NextPDF khẳng định một phân loại trên bằng chứng đã công bố; nó không bao giờ cấp, trao, hay chứng nhận việc đủ điều kiện. Thứ hai, trang này chỉ đề cập đến việc khẳng định và ánh xạ LoA. Chính sách PAdES cấu trúc eidasQualified(), bao gồm các tiêu chí đạt/không đạt của nó, được ghi trong Validation.

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

Khả năng này được cung cấp trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một envelope 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 khả năng này. So sánh các phiên bản và lấy giấy phép.

Cài đặt

composer require nextpdf/enterprise

Metapackage nextpdf/premium cũng phân giải gói Enterprise. Việc kích hoạt sử dụng envelope giấy phép Enterprise của bạn; xem Cấp phép và kích hoạt. Các lớp eIDAS không cần phần mở rộng PHP nào ngoài baseline của engine. Chúng tự động nạp dưới NextPDF\Enterprise\Security\Eidas và NextPDF\Enterprise\Signature\Eidas.

Tổng quan khái niệm

Regulation (EU) No 910/2014 (eIDAS) định nghĩa ba mức độ đảm bảo: low, substantial, và high (Article 8(1)). Mỗi mức độ thể hiện một mức tin cậy vào một danh tính được tuyên bố. Mức high bổ sung các kiểm soát có mục đích là ngăn chặn — không chỉ đơn thuần giảm thiểu — việc lạm dụng hoặc thay đổi danh tính (Article 8(2)(c)). Article 8 định nghĩa các mức độ này cho các sơ đồ định danh điện tử. NextPDF tái sử dụng cùng bộ từ vựng đó để phân loại bằng chứng trusted-list đằng sau một chứng chỉ ký. Việc tái sử dụng đó là một quy ước kỹ thuật cho việc chặn theo chính sách và kiểm toán, không phải một sự tương đương pháp lý.

Enum LoaLevel mô hình hóa ba mức độ. Các giá trị nền tảng của nó là các LoA URI của eIDAS thay vì các nhãn trần, nên một khẳng định được lưu giữ mang định danh đầy đủ. rank() cung cấp một thứ tự toàn phần (Low = 1, Substantial = 2, High = 3), và meetsOrExceeds() so sánh với một ngưỡng sàn bắt buộc.

LoaMapping tính một mức độ từ một mục trusted-list — một TspService từ hệ thống con trusted-list của Enterprise (NextPDF\Enterprise\Security\Tsl). Việc ánh xạ là xác định:

Bằng chứng trusted-list	Mức độ	Mã lý do
Trạng thái dịch vụ không phải granted	`Low`	`service_not_granted`
Loại dịch vụ không phải `CA/QC`	`Low`	`service_not_qualified_ca`
`CA/QC` đã granted với `QCWithQSCD` và không có `QCNoQSCD`	`High`	`ca_qc_with_qscd` cộng với `esig_or_eseal` hoặc `qc_default`
`CA/QC` đã granted trong các trường hợp khác	`Substantial`	`ca_qc_no_qscd_or_unspecified`

Qualifier QSCD (qualified signature creation device) là điểm mấu chốt. Theo Article 3(12), một qualified electronic signature yêu cầu cả một qualified certificate lẫn một qualified creation device. Một tuyên bố trong trusted-list rằng các chứng chỉ được quản lý trên một QSCD do đó là bằng chứng hỗ trợ một khẳng định High. Không có tuyên bố đó, một CA đủ điều kiện đã granted vẫn hỗ trợ Substantial, không bao giờ High.

Kết quả là một LoaAssertion: mức độ cộng với một danh sách các mã lý do. Các lý do cho phép một bên tiêu thụ kiểm toán tái suy ra phân loại từ cùng bằng chứng đó sau này. Các bộ đánh giá chính sách phía sau có thể ghi khẳng định đó bên cạnh một kết quả kiểm định chữ ký.

Một mảnh nữa được cung cấp trong module này: CertPiiGuard. Khi các artefact kiểm định được tuần tự hóa vào các bundle kiểm toán JSON, chứng chỉ người ký mang dữ liệu cá nhân — Subject CN, các thuộc tính email, và thuộc tính serialNumber, thứ có thể mã hóa một định danh quốc gia cho thể nhân. GDPR Article 5(1)(c) yêu cầu việc xử lý phải giới hạn ở mức cần thiết. Do đó guard mặc định biên tập các trường đó, thay các giá trị bằng [REDACTED] trong khi vẫn giữ envelope cấu trúc (các trường organization, country, chain và status). Bên tiêu thụ vẫn có thể xác minh liệu một chữ ký có đạt hay không mà không biết được ai đã ký.

Vì sao nó hoạt động theo cách này

Quyết định chịu tải là tách khẳng định đảm bảo khỏi phán quyết kiểm định. Kiểm định chữ ký, theo ETSI EN 319 102-1, kết thúc bằng một chỉ báo trạng thái — TOTAL-PASSED, TOTAL-FAILED, hoặc INDETERMINATE — và phán quyết đó thuộc về lớp kiểm định. Việc ánh xạ LoA là một phân loại riêng biệt, có thể phát lại trên bằng chứng trusted-list, với các mã lý do thay vì một nhãn trần. Điều này giữ cho NextPDF không bao giờ trình bày một tuyên bố đảm bảo như một kết quả kiểm định, hay một kết quả kiểm định như một sự cấp đủ điều kiện. Nó cũng khiến việc ánh xạ mang tính bảo thủ theo thiết kế: bằng chứng thiếu hoặc mơ hồ hạ thấp mức độ, không bao giờ nâng nó lên.

Bối cảnh thiết kế: Qualified signatures, explained.

Bề mặt API

Tất cả các ký hiệu bên dưới là public API trong nextpdf/enterprise 3.1.0.

`LoaLevel`

enum LoaLevel: string
{
    case Low = 'http://eidas.europa.eu/LoA/low';
    case Substantial = 'http://eidas.europa.eu/LoA/substantial';
    case High = 'http://eidas.europa.eu/LoA/high';

    public function rank(): int

    public function meetsOrExceeds(self $required): bool
}

Ném hoặc thất bại với: không gì từ rank() hoặc meetsOrExceeds(). Việc dựng enum native qua LoaLevel::from() ném \ValueError trên một URI không nhận diện được; LoaLevel::tryFrom() trả về null thay vào đó.

`LoaMapping`

final class LoaMapping
{
    public function loaForService(TspService $service): LoaAssertion
}

Ném hoặc thất bại với: không gì. Phương thức là toàn phần — mọi đầu vào TspService đều cho ra một LoaAssertion.

Các DTO đầu vào NextPDF\Enterprise\Security\Tsl\TspService và NextPDF\Enterprise\Security\Tsl\TspServiceQualifier là các public DTO ổn định (@api). Việc ánh xạ tham vấn TspService::STATUS_GRANTED, TspService::TYPE_CA_QC, và các hằng qualifier TspServiceQualifier::QSCD_STATEMENT (QCWithQSCD), TspServiceQualifier::NO_QSCD (QCNoQSCD), TspServiceQualifier::FOR_ESIG, và TspServiceQualifier::FOR_ESEAL.

`LoaAssertion`

final readonly class LoaAssertion
{
    /**
     * @param list<non-empty-string> $reasons Machine-readable reason codes for the assertion.
     */
    public function __construct(
        public LoaLevel $level,
        public array $reasons,
    ) {}
}

Ném hoặc thất bại với: không gì. Đối tượng giá trị bất biến.

`CertPiiGuard`

final readonly class CertPiiGuard
{
    public function __construct(
        private bool $disclosePii = false,
    ) {}

    public function disclosesPii(): bool

    public function guardSignerCommonName(string $signer): string

    public function guardDistinguishedName(string $dn): string

    public function guardTsaName(string $tsaName): string

    public function guardRootIssuer(string $issuer): string

    public function guardChainIssue(string $issue): string
}

Ném hoặc thất bại với: không gì. Các guard là các phép biến đổi chuỗi thuần túy. Trên một thành phần DN không thể được tokenize một cách chắc chắn, guard thất bại đóng (fail closed) và thu gọn thành phần đó thành [REDACTED] thay vì phát ra một giá trị được che một phần.

Mẫu code — Bắt đầu nhanh

Phân tích một LoA URI và so sánh nó với một ngưỡng sàn bắt buộc.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Security\Eidas\LoaLevel;

// A LoA URI as persisted in an audit record or received from a peer system.
$uri = 'http://eidas.europa.eu/LoA/substantial';

try {
    $level = LoaLevel::from($uri);
} catch (\ValueError $e) {
    // Unknown URI: refuse to classify. Never guess an assurance level.
    echo "Unrecognized LoA URI: {$uri}\n";
    exit(1);
}

echo 'Level: ' . $level->name . ' (rank ' . $level->rank() . ")\n";
echo 'Meets substantial: ' . ($level->meetsOrExceeds(LoaLevel::Substantial) ? 'yes' : 'no') . "\n";
echo 'Meets high: ' . ($level->meetsOrExceeds(LoaLevel::High) ? 'yes' : 'no') . "\n";

Đầu ra mong đợi:

Level: Substantial (rank 2)
Meets substantial: yes
Meets high: no

Mẫu code — Production

Phân loại một mục trusted-list, chặn dựa trên một mức độ bắt buộc, và phát ra một bản ghi kiểm toán đã biên tập.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Security\Eidas\LoaLevel;
use NextPDF\Enterprise\Security\Eidas\LoaMapping;
use NextPDF\Enterprise\Security\Tsl\TspService;
use NextPDF\Enterprise\Security\Tsl\TspServiceQualifier;
use NextPDF\Enterprise\Signature\Eidas\CertPiiGuard;

// Normally produced by the Enterprise trusted-list subsystem from a
// member-state TSL; constructed inline here for a self-contained example.
$caPem = (string) file_get_contents(__DIR__ . '/example-qc-ca.pem');

$service = new TspService(
    tspName: 'Example Qualified TSP',
    serviceName: 'Example Qualified CA G2',
    serviceTypeIdentifier: TspService::TYPE_CA_QC,
    serviceStatus: TspService::STATUS_GRANTED,
    statusStartingTime: '2024-01-01T00:00:00Z',
    serviceCertificatePem: $caPem,
    qualifiers: [
        new TspServiceQualifier(qualifierUri: TspServiceQualifier::QSCD_STATEMENT),
        new TspServiceQualifier(qualifierUri: TspServiceQualifier::FOR_ESIG),
    ],
    additionalServiceInformation: [],
);

try {
    // Required floor from deployment configuration; defaults to High.
    $required = LoaLevel::from(getenv('LOA_REQUIRED') ?: LoaLevel::High->value);
} catch (\ValueError $e) {
    echo "Invalid LOA_REQUIRED URI; refusing to continue.\n";
    exit(1);
}

$mapping = new LoaMapping();
$assertion = $mapping->loaForService($service);

// Privacy by default: signer identity fields are redacted in audit output.
$guard = new CertPiiGuard();

$audit = [
    'loa' => $assertion->level->value,
    'reasons' => $assertion->reasons,
    'meets_required' => $assertion->level->meetsOrExceeds($required),
    'signer' => $guard->guardSignerCommonName('CN=Jane Example, O=Example Corp, C=DE'),
];

echo json_encode($audit, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n";

Đầu ra mong đợi:

{
    "loa": "http://eidas.europa.eu/LoA/high",
    "reasons": [
        "ca_qc_with_qscd",
        "esig_or_eseal"
    ],
    "meets_required": true,
    "signer": "CN=[REDACTED], O=Example Corp, C=DE"
}

Các trường hợp biên & điểm cần lưu ý

LoaLevel::from() ném \ValueError trên các URI không xác định. Dùng LoaLevel::tryFrom() ở nơi việc xử lý null được ưa chuộng hơn.
Bằng chứng thiết bị xung đột giữ mức bảo thủ. Một dịch vụ mang cả QCWithQSCD lẫn QCNoQSCD ánh xạ thành Substantial, không phải High.
Một dịch vụ CA/QC đã granted không có qualifier nào ánh xạ thành Substantial với lý do ca_qc_no_qscd_or_unspecified — đủ điều kiện theo mặc định, thiết bị chưa được chứng minh.
Các qualifier URI ngoài tập được theo dõi không ảnh hưởng đến phân loại. Các qualifier chưa biết hoặc tương lai không bao giờ nâng mức độ.
Việc ánh xạ chỉ đọc trạng thái dịch vụ hiện tại. Nó không đánh giá lịch sử statusStartingTime; các cửa sổ tại thời điểm cụ thể thuộc về lớp kiểm định.
Lưu giữ URI nền tảng của enum, không phải số nguyên rank(). Các rank chỉ tồn tại để so sánh.
CertPiiGuard thu gọn hoàn toàn một tên trần không có = thành [REDACTED]; các chuỗi rỗng đi qua tất cả các guard không đổi.
Các DN kiểu cũ phân tách bằng dấu gạch chéo của OpenSSL được phát hiện và che theo cấu trúc. Một / bên trong một giá trị RFC 4514 được coi là nội dung, không phải một dấu phân tách.
Các thuộc tính DN không phải PII (O, OU, C, ST, L) được giữ lại, nên lập luận về thẩm quyền tài phán vẫn tồn tại qua việc biên tập.

Ghi chú bảo mật

Riêng tư theo mặc định. Constructor của guard mặc định là disclosePii: false. Chỉ dựng new CertPiiGuard(disclosePii: true) ở nơi bạn có một cơ sở pháp lý được ghi lập tài liệu để xử lý danh tính người ký. Điều này hiện thực hóa việc tối thiểu hóa dữ liệu theo GDPR Article 5(1)(c) tại ranh giới tuần tự hóa.
Biên tập thất bại đóng. Khi một thành phần DN không thể được tokenize một cách chắc chắn, toàn bộ thành phần đó thu gọn thành [REDACTED]. Một kiểm soát riêng tư không bao giờ thất bại mở.
Đầu ra xác định. Các guard dùng xử lý chuỗi thuần túy — không đồng hồ, không ngẫu nhiên — nên đầu ra được che là ổn định về byte với đầu vào giống hệt. Đầu ra ổn định giữ cho các diff kiểm toán có ý nghĩa.
Biên tập không phải là mã hóa. [REDACTED] loại giá trị khỏi bản ghi. Nếu bạn cần danh tính có thể phục hồi, hãy lưu nó riêng dưới cơ sở pháp lý và kiểm soát truy cập của riêng nó.
Rác vào, rác ra. Một LoaAssertion chỉ đáng tin cậy ngang với bằng chứng trusted-list đằng sau nó. Hãy thu nhận và kiểm tra chữ ký các trusted list thông qua hệ thống con trusted-list của Enterprise trước khi đưa các mục vào việc ánh xạ.

Sự phù hợp (conformance)

NextPDF Enterprise hiện thực hành vi được thông tin bởi Regulation (EU) No 910/2014 Article 8 (các mức độ đảm bảo) và Article 3(12) (các thành tố của một qualified electronic signature), và bởi bộ từ vựng qualifier trusted-list của ETSI. Hỗ trợ không phải là sự phù hợp, và sự phù hợp không phải là chứng nhận. NextPDF không giữ chứng nhận nào và không cấp chứng nhận nào. NextPDF không phải là một qualified trust service provider, không phải một cơ quan đánh giá sự phù hợp, và không phải một cơ quan giám sát. Một LoaAssertion là một phân loại phần mềm của bằng chứng đã công bố. Nó không phải là một xác định pháp lý về việc đủ điều kiện hay về mức độ đảm bảo, và nó không thể làm cho một chữ ký trở thành đủ điều kiện.

Regulation (EU) 2024/1183 (eIDAS 2) tiếp tục tham chiếu các mức độ theo Article 8 và yêu cầu European Digital Identity Wallets phải được cung cấp ở mức độ đảm bảo high. Trang này trích dẫn điều đó như bối cảnh pháp lý; NextPDF không đưa ra tuyên bố nào về khả năng liên quan đến ví.

Việc liệu một chữ ký cụ thể có thỏa mãn một chính sách cấu trúc định hướng eIDAS hay không là một câu hỏi riêng, được trả lời bởi module kiểm định; xem Validation.

Hành vi ở chế độ FIPS

Các lớp LoA eIDAS không thực hiện thao tác mật mã nào — không băm, không xác minh chữ ký, không ngẫu nhiên. Chính sách chế độ FIPS của Enterprise chặn các lựa chọn mật mã, nên nó không có gì để chặn trong module này. Việc bật chế độ FIPS không làm thay đổi việc ánh xạ LoA hay hành vi của PII guard. Việc xác minh mật mã các chữ ký và trusted list được quản lý bởi các module kiểm minh (verification) và bảo mật, nơi chính sách chế độ FIPS được áp dụng.

Hợp đồng hành vi

LoaMapping::loaForService() là toàn phần và xác định. Mọi TspService đều cho ra một LoaAssertion; phương thức không bao giờ ném và không tham vấn đồng hồ, mạng, hay trạng thái toàn cục nào.
Việc phân loại mang tính bảo thủ. Bằng chứng thiếu, chưa biết, hoặc xung đột sẽ hạ thấp mức độ; không gì nâng nó lên trừ bằng chứng CA/QC-đã-granted-với-QSCD tường minh.
Các mã lý do đọc được bằng máy và ổn định: service_not_granted, service_not_qualified_ca, ca_qc_with_qscd, esig_or_eseal, qc_default, ca_qc_no_qscd_or_unspecified.
Thứ tự mức độ là cố định: Low < Substantial < High, được phơi bày qua rank() và meetsOrExceeds().
CertPiiGuard mặc định biên tập và thất bại đóng khi có nghi ngờ về tokenize. Với disclosePii: true, mọi guard trả về đầu vào của nó nguyên văn.
Đầu ra của guard ổn định về byte với đầu vào giống hệt.

Phương án dự phòng của Core

NextPDF Core xác minh chữ ký PDF theo mật mã và thất bại đóng trên bằng chứng bị hỏng. Core không có mô hình trusted-list của EU, không có bộ từ vựng LoaLevel, không có việc ánh xạ LoA, và không có PII guard tầng eIDAS cho việc tuần tự hóa kiểm toán. Chỉ với Core, bạn phải tự suy ra các phân loại đảm bảo từ dữ liệu tin cậy mà bạn duy trì, và áp dụng việc biên tập của riêng bạn trước khi các bản ghi kiểm toán rời khỏi tiến trình.

Ranh giới công bố

Trang này chỉ ghi lập tài liệu hành vi quan sát được từ bên ngoài và bề mặt public API đượ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ế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Xem thêm

Validation — các chính sách phù hợp cấu trúc, bao gồm ngữ nghĩa eidasQualified() và các tiêu chí đạt/không đạt
Signature verification — phía xác minh mật mã AdES/PAdES mà các báo cáo của nó được PII guard bảo vệ
Security — Deep Reference — tham chiếu sâu của module Security
Qualified signatures, explained — bài luận Insider về việc đủ điều kiện và đảm bảo
How a signature proves who signed — bài luận Insider về sự tin cậy phía xác minh