PDFium Delphi Component Docs

الوحدة FPdfCrypto

الوحدة: FPdfCrypto
واجهة موفِّري الموقِّعين والمصادقة على الشهادات لـ PAdES للخلفيات الأساسية للمنصة وتكاملات PKCS#11 ومخازن الثقة وجالبات الإبطال والمصادقة على المسار المحدودة الحدود

الصياغة

TPadesPaddingScheme = (psRsaPss, psRsaPkcs1v15, psEcdsa);

TPadesSignerOptions = record
  CertificateThumbprint: string;
  PaddingScheme: TPadesPaddingScheme;
  class function Default: TPadesSignerOptions; static;
end;

TPadesChainCertArray = array of TBytes;

TPadesResolvedSigner = record
  Signer: ICmsSigner;
  SignerCertDer: TBytes;
  ChainCertDer: TPadesChainCertArray;
end;

TPdfRevocationMode = (prmNone, prmOffline, prmOnlineAllowed,
  prmOnlineRequired);
TPdfStringArray = array of string;

TPdfCertificatePathOptions = record
  ValidationTime: TDateTime;
  RevocationMode: TPdfRevocationMode;
  RequiredPolicyOids: TPdfStringArray;
  MaxCertificates: Integer;
  MaxCertificateBytes: Integer;
  MaxFetchBytes: Integer;
  MaxPathDepth: Integer;
  class function Default: TPdfCertificatePathOptions; static;
end;

TPdfCertificatePathReport = record
  Trusted: Boolean;
  PathBuilt: Boolean;
  PolicyValid: Boolean;
  RevocationChecked: Boolean;
  PathCertificateCount: Integer;
  ErrorCode: Integer;
  ErrorMessage: string;
end;

IPdfTrustStore = interface
  function LoadTrustAnchors: TPadesChainCertArray;
end;

IPdfValidationFetcher = interface
  function Fetch(const Uri: string; MaxBytes: Integer;
    out Data: TBytes): Boolean;
end;

IPdfCertificatePathValidator = interface
  function Validate(const LeafCertificate: TBytes;
    const Intermediates, TrustAnchors: TPadesChainCertArray;
    TrustStore: IPdfTrustStore; Fetcher: IPdfValidationFetcher;
    const Options: TPdfCertificatePathOptions;
    out Report: TPdfCertificatePathReport): Boolean;
end;

IPadesSignerProvider = interface
  function BackendName: string;
  function Resolve(const Options: TPadesSignerOptions): TPadesResolvedSigner;
end;

TPdfPkcs11Slot = record
  SlotID: UInt64;
  Description: string;
  TokenLabel: string;
  TokenPresent: Boolean;
end;
TPdfPkcs11Slots = array of TPdfPkcs11Slot;

TPdfPkcs11Certificate = record
  SlotID: UInt64;
  ObjectID: TBytes;
  LabelText: string;
  CertificateDer: TBytes;
  Mechanisms: TPdfStringArray;
end;
TPdfPkcs11Certificates = array of TPdfPkcs11Certificate;

IPdfPkcs11SignerProvider = interface(IPadesSignerProvider)
  function EnumerateSlots: TPdfPkcs11Slots;
  function EnumerateCertificates(SlotID: UInt64): TPdfPkcs11Certificates;
  procedure CloseProtectedSessions;
end;

TPdfCmsVerifyStatus = (pcvsUnavailable, pcvsValid, pcvsInvalid,
  pcvsUnsupported, pcvsIndeterminate);
TPdfCmsRevocationReason = (pcrrNone, pcrrCertificateRevoked, pcrrCrlExpired,
  pcrrCrlNotYetValid, pcrrCrlUnavailable, pcrrCrlSignatureInvalid,
  pcrrCrlInvalid, pcrrChainUntrusted, pcrrUnknown, pcrrOcspUnavailable,
  pcrrOcspInvalid, pcrrOcspStatusUnknown);
TPdfCmsVerifyStage = (pcvstCryptographicSignature, pcvstChainBuild,
  pcvstOnlineRetrieval, pcvstRevocationCheck);
TPdfCmsVerifyCheckpoint = procedure(Stage: TPdfCmsVerifyStage) of object;

TPdfCmsVerifyOptions = record
  OnlineRetrieval: Boolean;
  CheckRevocation: Boolean;
  CollectChainCertificates: Boolean;
  UrlRetrievalTimeoutMs: Cardinal;
  OnCheckpoint: TPdfCmsVerifyCheckpoint;
  CollectSignerDiagnostics: Boolean;
  MaxSignerCount: Integer;
  class function Default: TPdfCmsVerifyOptions; static;
end;

TPdfCmsSignerVerifyResult = record
  SignerIndex: Integer;
  SignatureStatus, TrustStatus, RevocationStatus: TPdfCmsVerifyStatus;
  SignatureError, TrustError: Cardinal;
  SignerCertificate: TBytes;
  RevocationReason: TPdfCmsRevocationReason;
  RevocationError: Cardinal;
  RevocationCertificate: TBytes;
end;
TPdfCmsSignerVerifyResults = array of TPdfCmsSignerVerifyResult;

TPdfCmsVerifyResult = record
  SignatureStatus: TPdfCmsVerifyStatus;
  TrustStatus: TPdfCmsVerifyStatus;
  RevocationStatus: TPdfCmsVerifyStatus;
  SignatureError: Cardinal;
  TrustError: Cardinal;
  SignerCertificate: TBytes;
  ChainCertificates: TPadesChainCertArray;
  RevocationReason: TPdfCmsRevocationReason;
  RevocationError: Cardinal;
  RevocationCertificate: TBytes;
  SignerResults: TPdfCmsSignerVerifyResults;
  SignerDiagnosticsStatus: TPdfCmsVerifyStatus;
  SignerCount: Integer;
end;

IPdfCmsVerifier = interface
  function BackendName: string;
  function VerifyDetached(const CmsDer: TBytes;
    Segment1: Pointer; Segment1Length: Cardinal;
    Segment2: Pointer; Segment2Length: Cardinal;
    const Options: TPdfCmsVerifyOptions): TPdfCmsVerifyResult;
  function VerifyAttached(const CmsDer: TBytes;
    const Options: TPdfCmsVerifyOptions): TPdfCmsVerifyResult;
end;

procedure ConfigurePadesCmsVerifier(const Verifier: IPdfCmsVerifier);
function PadesCmsVerificationAvailable: Boolean;
function PadesCmsVerificationBackendName: string;
function PadesCryptoAvailable: Boolean;
function PadesCryptoBackendName: string;
function ResolvePadesSigner(const Options: TPadesSignerOptions): TPadesResolvedSigner;
procedure ConfigurePdfCertificatePathValidator(
  const Validator: IPdfCertificatePathValidator);
function ValidatePdfCertificatePath(const LeafCertificate: TBytes;
  const Intermediates, TrustAnchors: TPadesChainCertArray;
  TrustStore: IPdfTrustStore; Fetcher: IPdfValidationFetcher;
  const Options: TPdfCertificatePathOptions;
  out Report: TPdfCertificatePathReport): Boolean;
procedure ConfigurePadesSignerProvider(const Provider: IPadesSignerProvider);

TPadesSignerResolverProc = function(const Options: TPadesSignerOptions): TPadesResolvedSigner;

PadesSignerResolverOverride: TPadesSignerResolverProc;
PdfCertificatePathValidator: IPdfCertificatePathValidator;
PadesSignerProvider: IPadesSignerProvider;
PadesCmsVerifier: IPdfCmsVerifier;

الوصف

FPdfCrypto مدخل منظومة توقيع PAdES؛ تبين PadesCryptoAvailable إتاحة مواد التوقيع وخلفيتها، وتسمي PadesCryptoBackendName الخلفية؛ يستخدم Windows افتراضيًا Cryptography Next Generation، وتحل المنصات الأخرى مفتاح OpenSSL الخاص وشهادته المهيأين صراحة في FPdfCryptoSsl

يأخذ ResolvePadesSigner بصمة شهادة ومخطط حشو ويعيد TPadesResolvedSigner مكتملًا: تنفيذ ICmsSigner الذي ينفذ عملية المفتاح الخاص، وشهادة الموقِّع DER، وشهادات السلسلة المُصدِرة. تُمرَّر النتيجة مباشرة إلى FPdfCms.BuildSignedData

تستطيع التكاملات المخصصة تسجيل IPadesSignerProvider، بما في ذلك IPdfPkcs11SignerProvider الذي يحصي منافذ الرموز وشهاداتها، أو استخدام PadesSignerResolverOverride كنقطة خياطة حل حتمية

المصادقة على مسار الشهادات قائمة على المزودات ومحدودة الميزانيات: يُعدّ المستدعون IPdfCertificatePathValidator، ويزوِّدون اختياريًا مراسي ثقة صريحة و IPdfTrustStore و IPdfValidationFetcher، ثم يفحصون TPdfCertificatePathReport

الدوال

الدالةالوصف
PadesCryptoAvailableيعيد True عندما تتوفر خلفية تعمية لتوقيع PAdES على المنصة الحالية
PadesCryptoBackendNameيعيد الاسم المعروض لخلفية التعمية النشطة
ResolvePadesSignerيحوِّل بصمة شهادة ومخطط حشو إلى موقِّع وشهادة موقِّع وسلسلة
ConfigurePdfCertificatePathValidatorيعيِّن IPdfCertificatePathValidator على مستوى العملية أو يمسحه، وهو ما تستخدمه ValidatePdfCertificatePath
ValidatePdfCertificatePathيصادق على شهادة ورقة مقابل الوسائط والمراسي المشتركة الصريحة ومن مخزن الثقة بعد فرض ميزانيات عدد الشهادات وحجمها والجلب وعمق المسار
ConfigurePadesSignerProviderيعيِّن مزوِّد الموقِّعين على مستوى العملية أو يمسحه، ويُستخدم قبل الخلفية الأساسية للمنصة
ConfigurePadesCmsVerifierتثبت خلفية تحقق CMS التي يستخدمها PAdES؛ تعيد إزالة الخلفية Windows CryptoAPI على Windows؛ تحتاج المنصات الأخرى إلى استدعاء صريح لـ ConfigureSslCmsVerifier أو ConfigureKeychainCmsVerifier
PadesCmsVerificationAvailableيعيد True عندما تستطيع خلفية ما التحقق من CMS في هذا البناء، سواء كانت مسجلة أو مدمجة
PadesCmsVerificationBackendNameيعيد الاسم المعروض لخلفية التحقق النشطة، أو سلسلة فارغة عند غيابها

واجهات المزودات

عضو الواجهةالوصف
IPdfTrustStore.LoadTrustAnchorsيعيد مراسي ثقة إضافية مرمَّزة بـ DER خاضعة لميزانيات الشهادات المُعدَّة
IPdfValidationFetcher.Fetchيجلب مواد المصادقة من Uri دون تجاوز MaxBytes
IPdfCertificatePathValidator.Validateيبني مسار الشهادات ويقيِّمه ويملأ TPdfCertificatePathReport
IPadesSignerProvider.BackendNameيعيد اسم المزوِّد المعروض الذي تكشفه PadesCryptoBackendName
IPadesSignerProvider.Resolveيعيد مواد الموقِّع كاملة لخيارات TPadesSignerOptions المُزوَّدة
IPdfPkcs11SignerProvider.EnumerateSlotsيعيد منافذ PKCS#11 المتاحة وبيانات وصفية عن وجود الرموز
IPdfPkcs11SignerProvider.EnumerateCertificatesيعيد الشهادات وآليات التوقيع الظاهرة في منفذ PKCS#11 واحد
IPdfPkcs11SignerProvider.CloseProtectedSessionsيغلق جلسات PKCS#11 المحمية أو الموثَّقة التي يملكها المزوِّد
IPdfCmsVerifier.BackendNameيعيد الاسم المعروض لخلفية التحقق الذي تُبلِّغ عنه PadesCmsVerificationBackendName
IPdfCmsVerifier.VerifyDetachedيتحقق من توقيع PDF، ومحتواه الموقَّع هو مدى البايتات على جانبي فراغ /Contents
IPdfCmsVerifier.VerifyAttachedيتحقق من رمز الطابع الزمني، الذي يحمل محتواه بنفسه ولا يحتاج مقاطع منفصلة

الأنواع

النوعالوصف
EPadesCryptoاستثناء أساسي لفشل خلفية التعمية
EPadesCryptoUnavailableيُرفع عندما لا تكون خلفية موقِّع مطلوبة أو مُصادِق مسار الشهادات مُعدًّا
TPadesPaddingSchemepsRsaPss أو psRsaPkcs1v15 أو psEcdsa
TPadesSignerOptionsتختار CertificateThumbprint الشهادة ويختار PaddingScheme مخطط التوقيع؛ يستخدم Default بصمة فارغة و psRsaPss
TPadesChainCertArrayمصفوفة ديناميكية من شهادات سلسلة مرمَّزة بـ DER
TPadesResolvedSignerتجمع Signer و SignerCertDer و ChainCertDer الموقِّع المُحلَّل ومواد الشهادة
TPdfRevocationModeprmNone أو prmOffline أو prmOnlineAllowed أو prmOnlineRequired
TPdfStringArrayمصفوفة سلاسل ديناميكية تُستخدم لمعرِّفات OID للسياسات وأسماء آليات المزوِّد
TPdfCertificatePathOptionsتتحكم ValidationTime و RevocationMode و RequiredPolicyOids و MaxCertificates و MaxCertificateBytes و MaxFetchBytes و MaxPathDepth في المصادقة وميزانيات الموارد؛ يختار Default إبطالًا دون اتصال بحدود 64 شهادة و 4 MiB لكل شهادة و 16 MiB بيانات مجلوبة وعمق مسار 16
TPdfCertificatePathReportتُبلِّغ Trusted و PathBuilt و PolicyValid و RevocationChecked و PathCertificateCount و ErrorCode و ErrorMessage عن نتيجة المصادقة
TPdfPkcs11Slotتصف SlotID و Description و TokenLabel و TokenPresent منفذ PKCS#11 واحدًا
TPdfPkcs11Slotsمصفوفة ديناميكية من سجلات TPdfPkcs11Slot
TPdfPkcs11Certificateتصف SlotID و ObjectID و LabelText و CertificateDer و Mechanisms شهادة رمز واحدة
TPdfPkcs11Certificatesمصفوفة ديناميكية من سجلات TPdfPkcs11Certificate
TPadesSignerResolverProcنوع مؤشر دالة لمتغير الحقن PadesSignerResolverOverride
TPdfCmsVerifyStatuspcvsUnavailable أو pcvsValid أو pcvsInvalid أو pcvsUnsupported أو pcvsIndeterminate
TPdfCmsRevocationReasonتشرح pcrrNone أو pcrrCertificateRevoked أو pcrrCrlExpired أو pcrrCrlNotYetValid أو pcrrCrlUnavailable أو pcrrCrlSignatureInvalid أو pcrrCrlInvalid أو pcrrChainUntrusted أو pcrrUnknown أو pcrrOcspUnavailable أو pcrrOcspInvalid أو pcrrOcspStatusUnknown أدلة الإلغاء منفصلة عن حالة التحقق
TPdfCmsVerifyStagepcvstCryptographicSignature أو pcvstChainBuild أو pcvstOnlineRetrieval أو pcvstRevocationCheck
TPdfCmsVerifyCheckpointاستدعاء بطريقة كائن يستقبل كل TPdfCmsVerifyStage أثناء تقدم التحقق
TPdfCmsVerifyOptionsتوجه OnlineRetrieval و CheckRevocation و CollectChainCertificates و UrlRetrievalTimeoutMs و OnCheckpoint التحقق؛ تطلب CollectSignerDiagnostics snapshots لكل موقع ويحدها MaxSignerCount؛ يعطل Default الجلب والإلغاء والتشخيصات، ويحدد 15 ثانية للجلب و 64 snapshot
TPdfCmsSignerVerifyResultيحدد SignerIndex ترتيب SignerInfo المرمز؛ تصف حالات التوقيع والثقة والإلغاء والأخطاء الأصلية الموقع مستقلاً؛ SignerCertificate شهادته DER و RevocationCertificate شهادة الخطأ إذا استطاعت الخلفية التقاطها
TPdfCmsSignerVerifyResultsمصفوفة ديناميكية من snapshots محدودة للموقعين
TPdfCmsVerifyResultتبقى حالات التوقيع والثقة والإلغاء المجمعة مستقلة؛ يعيد السجل أيضًا SignatureError و TrustError و SignerCertificate و ChainCertificates و RevocationReason و RevocationError و RevocationCertificate و SignerResults و SignerDiagnosticsStatus و SignerCount

تشخيصات الإبطال

أعد بناء المستهلكين عند الترقية لأن سجلات الخيارات والنتائج العامة توسعت؛ ابدأ النتائج المدارة بـ Default(TPdfCmsVerifyResult) واترك حقول snapshots غير المدعومة غير متاحة؛ لا تصفر بـ FillChar سجلًا حيًا يحتوي نصوصًا أو مصفوفات ديناميكية

اقرأ RevocationReason و RevocationError من السجل TPdfCmsVerifyResult الذي تعيده IPdfCmsVerifier.VerifyDetached أو VerifyAttached. ويحافظ التحقق من ثقة PAdES عليهما بصفتيهما RevocationReason و NativeRevocationError، مع حقلي TimeStampRevocationReason و NativeTimeStampRevocationError منفصلين لرموز الطوابع الزمنية؛ وتشمل تقارير الأدلة الزوجين معًا

RevocationError هو كود تحقق أصلي خاص بالخلفية، والصفر يعني أن أي تشخيص أصلي لم يُلتقط. وتستخدم خلفية OpenSSL فضاء أكواد X509_V_ERR_*. أما Windows فيحفظ قيمة DWORD خام من CERT_REVOCATION_INFO.dwRevocationResult للشهادة، أو من GetLastError إذا فشلت استدعاءات سلسلة الإبطال لديها؛ وهو ليس فضاء أخطاء HRESULT موحدًا ولا قناع ثقة السلسلة التجميعي

يميز OpenSSL الإلغاء المؤكد عن CRL المنتهية أو الغائبة أو غير الصالحة و OCSP الغائبة أو غير الصالحة أو المجهولة؛ يبلغ Windows الإلغاء المؤكد أو سلسلة غير موثوقة أو فشلًا أصليًا مجهولًا؛ يفحص macOS السلامة والثقة Basic X.509 والإلغاء مستقلة، ويرد أخطاء Security.framework دون تصنيف كل فشل CRL أو OCSP

قد تشير RevocationCertificate إلى شهادة وسيطة ملغاة بدل شهادة موقع CMS؛ تكون فارغة إن تعذر التقاطها؛ يدعم OpenSSL جمعها وتتركها macOS الحالية فارغة

لا يثبت pcrrNone ولا الخطأ الصفري أن الإبطال قد فُحص أو نجح؛ فافحص RevocationStatus دائمًا

تشخيصات كل موقع

استخدم CollectSignerDiagnostics=True لفحص snapshots في SignerResults؛ SignerCount عدد SignerInfo المرمز إذا أمكن تحديده؛ الصفر يعني عدم تحديده

تعني SignerDiagnosticsStatus=pcvsValid اكتمال snapshots المطلوبة، بما فيها التوقيعات غير الصالحة، لا نجاح جميع التوقيعات؛ تعني pcvsUnavailable تعطيل الجمع أو عدم دعمه، و pcvsIndeterminate تعذر إكماله ضمن حدود التحليل والموارد

يحد OpenSSL و macOS الأصلي الجمع بـ 64 موقعًا؛ يحد OpenSSL مدخل CMS التشخيصي بـ 4 MiB والعمل المجمع بـ 64 MiB؛ يحد macOS الشهادات المعادة بـ 4 MiB لكل منها و 64 MiB إجمالًا؛ يخفض MaxSignerCount الأصغر الطلب

تعيد snapshots استخدام الأدلة المهيأة والمجلوبة خلال الفحص المجمع؛ لا يجلب OpenSSL الشبكة ثانية لكل snapshot، ولا يتحول الجلب المجمع الناقص إلى فحص إلغاء ناجح بلا شبكة

خلفية التوقيع الافتراضية

الأولوية لـ PadesSignerResolverOverride ثم IPadesSignerProvider المسجل صراحة ثم افتراضي المنصة؛ خارج Windows يلزم ConfigureSslSigningCredentials؛ إتاحة libcrypto وحدها لا توفر مفتاحًا أو شهادة

يرفض افتراضي OpenSSL ‏CertificateThumbprint غير الفارغ لأن الشهادة مختارة مسبقًا؛ يبقى Keychain متاحًا عبر ConfigureKeychainSignerProvider إذا اختارته التطبيق

متغيرات المزودات العامة

المتغيرالوصف
PadesSignerResolverOverrideاستدعاء حل اختياري يُقيَّم قبل المزودات المسجَّلة ومزودات المنصة
PadesCmsVerifierخلفية تحقق CMS الحالية، وتُعيَّن عادةً عبر ConfigurePadesCmsVerifier
PdfCertificatePathValidatorمُصادِق مسار الشهادات الحالي، ويُعيَّن عادةً عبر ConfigurePdfCertificatePathValidator
PadesSignerProviderمزوِّد الموقِّعين الحالي، ويُعيَّن عادةً عبر ConfigurePadesSignerProvider

انظر أيضًا

FPdfCms, FPdfCryptoWin, FPdfCryptoSsl, FPdfCryptoMac, FPdfCryptoOcsp, FPdfTsa, TPdf.SignPades