Level jaminan eIDAS

Sekilas pandang

NextPDF Enterprise mengubah bukti trusted-list Uni Eropa menjadi eIDAS Level of Assurance (LoA) yang eksplisit. Layanan NextPDF\Enterprise\Security\Eidas\LoaMapping mengklasifikasikan satu entri trust-service sebagai Low, Substantial, atau High. Ia mengembalikan LoaAssertion yang membawa level tersebut ditambah kode alasan yang dapat dibaca mesin. Alur kerja Anda dapat menggerbang berdasarkan jaminan — “wajib High” — dan mengarsipkan alasan-alasan itu sebagai bukti audit. Pengaman pendamping, CertPiiGuard, meredaksi bidang identitas penanda tangan sebelum catatan audit meninggalkan proses.

Dua batasan membingkai kapabilitas ini secara jujur. Pertama, kualifikasi selalu menjadi milik trust service provider (TSP) di bawah pengawasan negara anggota. NextPDF mengasersikan klasifikasi atas bukti yang dipublikasikan; ia tidak pernah memberikan, menganugerahkan, atau mensertifikasi kualifikasi. Kedua, halaman ini hanya mencakup asersi dan pemetaan LoA. Kebijakan struktural PAdES eidasQualified(), termasuk kriteria lolos/gagalnya, didokumentasikan di Validation.

Ketersediaan & lisensi

Kapabilitas ini hadir dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan amplop lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Instalasi

composer require nextpdf/enterprise

Metapaket nextpdf/premium juga meresolusi paket Enterprise. Aktivasi menggunakan amplop lisensi Enterprise Anda; lihat Licensing and activation. Kelas-kelas eIDAS tidak memerlukan ekstensi PHP di luar baseline engine. Mereka melakukan autoload di bawah NextPDF\Enterprise\Security\Eidas dan NextPDF\Enterprise\Signature\Eidas.

Tinjauan konseptual

Regulation (EU) No 910/2014 (eIDAS) mendefinisikan tiga level jaminan: low, substantial, dan high (Article 8(1)). Setiap level mengungkapkan derajat kepercayaan pada identitas yang diklaim. Level high menambahkan kontrol yang tujuannya mencegah — bukan sekadar mengurangi — penyalahgunaan atau pengubahan identitas (Article 8(2)(c)). Article 8 mendefinisikan level-level ini untuk skema identifikasi elektronik. NextPDF menggunakan kembali kosakata yang sama untuk mengklasifikasikan bukti trust-service di balik sertifikat penandatanganan. Penggunaan ulang itu adalah konvensi rekayasa untuk gerbang kebijakan dan audit, bukan kesetaraan hukum.

Enum LoaLevel memodelkan ketiga level. Nilai backing-nya adalah eIDAS LoA URI alih-alih label telanjang, sehingga asersi yang dipersistensikan membawa pengidentifikasi lengkap. rank() memberi urutan total (Low = 1, Substantial = 2, High = 3), dan meetsOrExceeds() membandingkan terhadap floor yang diwajibkan.

LoaMapping menghitung sebuah level dari satu entri trusted-list — sebuah TspService dari subsistem trusted-list Enterprise (NextPDF\Enterprise\Security\Tsl). Pemetaannya deterministik:

Bukti trusted-list	Level	Kode alasan
Status layanan bukan granted	Low	service_not_granted
Tipe layanan bukan CA/QC	Low	service_not_qualified_ca
CA/QC yang granted dengan QCWithQSCD dan tanpa QCNoQSCD	High	ca_qc_with_qscd plus esig_or_eseal atau qc_default
CA/QC yang granted selain itu	Substantial	ca_qc_no_qscd_or_unspecified

Kualifier QSCD (qualified signature creation device) adalah porosnya. Di bawah Article 3(12), tanda tangan elektronik terkualifikasi memerlukan baik sertifikat terkualifikasi maupun perangkat pembuatan terkualifikasi. Karena itu, pernyataan trusted-list bahwa sertifikat dikelola pada QSCD adalah bukti yang mendukung asersi High. Tanpa pernyataan tersebut, CA terkualifikasi yang granted masih mendukung Substantial, tidak pernah High.

Hasilnya adalah LoaAssertion: level ditambah daftar kode alasan. Alasan-alasan itu memungkinkan konsumen audit untuk menurunkan ulang klasifikasi dari bukti yang sama di kemudian hari. Evaluator kebijakan hilir dapat mencatat asersi tersebut bersama hasil validasi-tanda tangan.

Satu bagian lagi hadir dalam modul ini: CertPiiGuard. Ketika artefak validasi diserialisasikan ke dalam bundel audit JSON, sertifikat penanda tangan membawa data pribadi — Subject CN, atribut email, dan atribut serialNumber, yang dapat mengodekan pengidentifikasi nasional untuk orang perorangan. GDPR Article 5(1)(c) mengharuskan pemrosesan dibatasi pada apa yang diperlukan. Karena itu, pengaman meredaksi bidang-bidang tersebut secara default, mengganti nilai dengan [REDACTED] sambil mempertahankan amplop struktural (organisasi, negara, bidang chain dan status). Konsumen tetap dapat memverifikasi apakah sebuah tanda tangan lolos tanpa mengetahui siapa yang menandatangani.

Mengapa cara kerjanya begini

Keputusan penyangga beban adalah memisahkan asersi jaminan dari verdict validasi. Validasi tanda tangan, menurut ETSI EN 319 102-1, berakhir pada indikasi status — TOTAL-PASSED, TOTAL-FAILED, atau INDETERMINATE — dan verdict itu menjadi milik lapisan validasi. Pemetaan LoA adalah klasifikasi terpisah yang dapat diputar ulang atas bukti trusted-list, dengan kode alasan alih-alih label telanjang. Ini menjaga NextPDF agar tidak pernah menyajikan klaim jaminan sebagai hasil validasi, atau hasil validasi sebagai pemberian kualifikasi. Ini juga membuat pemetaan konservatif secara konstruksi: bukti yang absen atau ambigu menurunkan level, tidak pernah menaikkannya.

Latar belakang desain: Qualified signatures, explained.

Permukaan API

Semua simbol di bawah ini adalah API publik di 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
}

Melempar atau gagal dengan: tidak ada dari rank() atau meetsOrExceeds(). Konstruksi enum native melalui LoaLevel::from() melempar \ValueError pada URI yang tidak dikenali; LoaLevel::tryFrom() mengembalikan null sebagai gantinya.

LoaMapping

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

Melempar atau gagal dengan: tidak ada. Metode ini total — setiap input TspService menghasilkan sebuah LoaAssertion.

DTO input NextPDF\Enterprise\Security\Tsl\TspService dan NextPDF\Enterprise\Security\Tsl\TspServiceQualifier adalah DTO publik yang stabil (@api). Pemetaan mengonsultasikan TspService::STATUS_GRANTED, TspService::TYPE_CA_QC, serta konstanta kualifier TspServiceQualifier::QSCD_STATEMENT (QCWithQSCD), TspServiceQualifier::NO_QSCD (QCNoQSCD), TspServiceQualifier::FOR_ESIG, dan 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,
    ) {}
}

Melempar atau gagal dengan: tidak ada. Objek nilai yang immutable.

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
}

Melempar atau gagal dengan: tidak ada. Pengaman adalah transformasi string murni. Pada komponen DN yang tidak dapat ditokenisasi dengan yakin, pengaman gagal-tertutup dan meruntuhkan komponen menjadi [REDACTED] alih-alih memancarkan nilai yang tersamar sebagian.

Contoh kode — Mulai cepat

Parse sebuah LoA URI dan bandingkan terhadap floor yang diwajibkan.

loa-quick-start.php

<?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";

Output yang diharapkan:

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

Contoh kode — Produksi

Klasifikasikan sebuah entri trusted-list, gerbang berdasarkan level yang diwajibkan, dan pancarkan catatan audit yang teredaksi.

loa-audit-gate.php

<?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";

Output yang diharapkan:

{
    "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"
}

Kasus tepi & jebakan

• LoaLevel::from() melempar \ValueError pada URI yang tidak dikenal. Gunakan LoaLevel::tryFrom() bila penanganan null lebih disukai.
• Bukti perangkat yang bertentangan tetap konservatif. Sebuah layanan yang membawa baik QCWithQSCD maupun QCNoQSCD memetakan ke Substantial, bukan High.
• Layanan CA/QC yang granted tanpa kualifier memetakan ke Substantial dengan alasan ca_qc_no_qscd_or_unspecified — terkualifikasi secara default, perangkat tidak terbukti.
• URI kualifier di luar himpunan yang dilacak tidak memengaruhi klasifikasi. Kualifier yang tidak dikenal atau masa depan tidak pernah menaikkan level.
• Pemetaan hanya membaca status layanan saat ini. Ia tidak mengevaluasi riwayat statusStartingTime; jendela titik-waktu menjadi milik lapisan validasi.
• Persistensikan URI backing enum, bukan integer rank(). Rank hanya ada untuk perbandingan.
• CertPiiGuard meruntuhkan nama telanjang tanpa = seluruhnya menjadi [REDACTED]; string kosong lolos melewati semua pengaman tanpa perubahan.
• DN legacy OpenSSL yang dipisahkan garis miring dideteksi dan disamarkan secara struktural. Sebuah / di dalam nilai RFC 4514 diperlakukan sebagai konten, bukan pemisah.
• Atribut DN non-PII (O, OU, C, ST, L) dipertahankan, sehingga penalaran yurisdiksi bertahan melewati redaksi.

Catatan keamanan

• Privasi secara default. Konstruktor pengaman default ke disclosePii: false. Konstruksi new CertPiiGuard(disclosePii: true) hanya di tempat Anda memegang dasar hukum yang terdokumentasi untuk memproses identitas penanda tangan. Ini mengimplementasikan minimalisasi data GDPR Article 5(1)(c) pada batas serialisasi.
• Redaksi gagal-tertutup. Ketika sebuah komponen DN tidak dapat ditokenisasi dengan yakin, seluruh komponen runtuh menjadi [REDACTED]. Kontrol privasi tidak pernah gagal-terbuka.
• Output deterministik. Pengaman menggunakan pemrosesan string murni — tanpa jam, tanpa keacakan — sehingga output tersamar stabil-byte untuk input yang identik. Output yang stabil menjaga diff audit tetap bermakna.
• Redaksi bukan enkripsi. [REDACTED] menghapus nilai dari catatan. Jika Anda memerlukan identitas yang dapat dipulihkan, simpan secara terpisah di bawah dasar hukum dan kontrol aksesnya sendiri.
• Sampah masuk, sampah keluar. Sebuah LoaAssertion hanya sedapat-dipercaya bukti trusted-list di baliknya. Peroleh dan periksa-tanda-tangan trusted list melalui subsistem trusted-list Enterprise sebelum memberikan entri ke pemetaan.

Konformansi

NextPDF Enterprise mengimplementasikan perilaku yang diinformasikan oleh Regulation (EU) No 910/2014 Article 8 (level jaminan) dan Article 3(12) (elemen tanda tangan elektronik terkualifikasi), serta oleh kosakata kualifier trusted-list ETSI. Dukungan bukanlah konformansi, dan konformansi bukanlah sertifikasi. NextPDF tidak memegang sertifikasi dan tidak memberikan satu pun. NextPDF bukan qualified trust service provider, bukan conformity assessment body, dan bukan supervisory body. Sebuah LoaAssertion adalah klasifikasi perangkat lunak atas bukti yang dipublikasikan. Ia bukan penentuan hukum atas kualifikasi atau jaminan, dan ia tidak dapat menjadikan sebuah tanda tangan terkualifikasi.

Regulation (EU) 2024/1183 (eIDAS 2) terus merujuk level Article 8 dan mengharuskan European Digital Identity Wallets disediakan pada level jaminan high. Halaman ini mengutip itu sebagai konteks regulasi; NextPDF tidak membuat klaim kapabilitas terkait wallet.

Apakah sebuah tanda tangan tertentu memenuhi kebijakan struktural berorientasi eIDAS adalah pertanyaan terpisah, yang dijawab oleh modul validasi; lihat Validation.

Perilaku mode FIPS

Kelas-kelas eIDAS LoA tidak melakukan operasi kriptografis — tanpa hashing, tanpa verifikasi tanda tangan, tanpa keacakan. Kebijakan mode FIPS Enterprise menggerbang pilihan kriptografis, sehingga tidak ada yang perlu digerbang di modul ini. Mengaktifkan mode FIPS tidak mengubah pemetaan LoA maupun perilaku PII-guard. Verifikasi kriptografis atas tanda tangan dan trusted list diatur oleh modul verifikasi dan keamanan, tempat kebijakan mode FIPS berlaku.

Kontrak perilaku

• LoaMapping::loaForService() bersifat total dan deterministik. Setiap TspService menghasilkan sebuah LoaAssertion; metode ini tidak pernah melempar dan tidak mengonsultasikan jam, jaringan, atau state global mana pun.
• Klasifikasi bersifat konservatif. Bukti yang hilang, tidak dikenal, atau bertentangan menurunkan level; tidak ada yang menaikkannya kecuali bukti CA/QC granted-dengan-QSCD yang eksplisit.
• Kode alasan dapat dibaca mesin dan stabil: service_not_granted, service_not_qualified_ca, ca_qc_with_qscd, esig_or_eseal, qc_default, ca_qc_no_qscd_or_unspecified.
• Urutan level tetap: Low < Substantial < High, diekspos melalui rank() dan meetsOrExceeds().
• CertPiiGuard default ke redaksi dan gagal-tertutup pada keraguan tokenisasi. Dengan disclosePii: true, setiap pengaman mengembalikan inputnya secara verbatim.
• Output pengaman stabil-byte untuk input yang identik.

Fallback Core

NextPDF Core memverifikasi tanda tangan PDF secara kriptografis dan gagal-tertutup pada bukti yang rusak. Core tidak memiliki model trusted-list Uni Eropa, tidak ada kosakata LoaLevel, tidak ada pemetaan LoA, dan tidak ada PII guard lapisan-eIDAS untuk serialisasi audit. Pada Core saja, Anda harus menurunkan sendiri klasifikasi jaminan dari data trust yang Anda pelihara, dan menerapkan redaksi Anda sendiri sebelum catatan audit meninggalkan proses.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas pembantu, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Validation — kebijakan kepatuhan struktural, termasuk semantik eidasQualified() dan kriteria lolos/gagal
• Signature verification — sisi verifikasi kriptografis AdES/PAdES yang laporannya dilindungi oleh PII guard
• Security — Deep Reference — referensi mendalam modul Security
• Qualified signatures, explained — esai Insider tentang kualifikasi dan jaminan
• How a signature proves who signed — esai Insider tentang trust sisi-verifikasi