מדריך מפתחים של PDFium Delphi Component

Unit: FPdfEncrypt

גוזרת מפתחות הצפנה AES-256 ופולטת מחרוזות, זרמים ומילוני הצפנה של ISO 32000-2 AESV3-CBC או של ISO/TS 32003 AESV4-GCM

Syntax

TPdfEncryptionRevision = (erR5, erR6, erR7);

TPdfEncryptOptions = record
  UserPassword: AnsiString;
  OwnerPassword: AnsiString;
  Permissions: Cardinal;
  EncryptMetadata: Boolean;
  Revision: TPdfEncryptionRevision;
  EnableIntegrityProtection: Boolean;
  class function Default: TPdfEncryptOptions; static;
end;

TPdfEncryptionKeys = record
  FileEncryptionKey: TBytes;
  OEntry: TBytes;
  UEntry: TBytes;
  OEEntry: TBytes;
  UEEntry: TBytes;
  PermsEntry: TBytes;
  KdfSalt: TBytes;
end;

TPdfIncrementalEncryptionContext = record
  FileEncryptionKey: TBytes;
  KdfSalt: TBytes;
  Revision: TPdfEncryptionRevision;
  EncryptMetadata: Boolean;
  EncryptObjectNumber: Integer;
  EncryptGeneration: Integer;
  HasAuthenticationCode: Boolean;
end;

procedure DeriveEncryptionKeys(const Options: TPdfEncryptOptions;
  out Keys: TPdfEncryptionKeys);
function BuildEncryptDictionary(const Keys: TPdfEncryptionKeys;
  const Options: TPdfEncryptOptions): AnsiString;
function EncryptStreamPayload(const FileKey: TBytes;
  const Plain: TBytes): TBytes;
function EncryptDocumentBytes(const PlainPdf: TBytes;
  const Options: TPdfEncryptOptions): TBytes;
function DecryptAesGcmDocumentBytes(const EncryptedPdf: TBytes;
  const Password: AnsiString; out PlainPdf: TBytes;
  out ErrorText: string): Boolean;
function ValidateEncryptedDocumentMac(const EncryptedPdf: TBytes;
  const Password: AnsiString): TPdfMacValidationResult;
function ReadIncrementalEncryptionContext(const EncryptedPdf: TBytes;
  const Password: AnsiString;
  out Context: TPdfIncrementalEncryptionContext;
  out ErrorText: string): Boolean;
procedure ClearIncrementalEncryptionContext(
  var Context: TPdfIncrementalEncryptionContext);
function EncryptIncrementalObjectBody(const PlainBody: TBytes;
  const Context: TPdfIncrementalEncryptionContext;
  out EncryptedBody: TBytes;
  out ErrorText: string): Boolean;

Description

FPdfEncrypt מממש את מטפל האבטחה PDF AES-256 המוגדר ב-ISO 32000-2 §7.6 ואת הרחבת AESV4-GCM המוגדרת ב-ISO/TS 32003. ‏EncryptDocumentBytes הופך מערך בתים של PDF פשוט אל מסמך מוצפן באמצעות המהדורה הנבחרת

‏DeriveEncryptionKeys מריץ את גזירת המפתחות מבוססת-הסיסמה שמפיקה את מפתח ההצפנה של הקובץ בן 32 הבתים בתוספת רשומות המילון /O, ‏/U, ‏/OE, ‏/UE ו-/Perms. ‏BuildEncryptDictionary מסדר את הרשומות האלה לטקסט מילון ה-/Encrypt. ‏EncryptStreamPayload מחיל הצפנת AES-256-CBC על זרם אובייקט בודד באמצעות מפתח הקובץ

משתמש מתקדם שבונה צינור שמירה מותאם יכול לקרוא לשלושת הפרימיטיבים ישירות; קוד יישומי בדרך כלל משתמש ב-TPdf.SaveAsEncrypted או ב-TPdf.SaveAsEncryptedToStream, שקוראים ל-EncryptDocumentBytes באופן פנימי

כאשר EnableIntegrityProtection הוא true, הכותב פולט קוד אימות עצמאי של ISO/TS 32004 ל-PDF 2.0 עם /ByteRange שמכסה בדיוק את ה-EOF, ‏/KDFSalt, CMS AuthenticatedData, ‏HKDF-SHA256, ‏AES-256 Key Wrap, ו-HMAC-SHA256

PDFium אינו חושף כרגע ניתוח AESV4 דרך ה-ABI הציבורי שלו. קראו קודם ל-DecryptAesGcmDocumentBytes והעבירו את הבתים שהוחזרו אל TPdf.LoadDocument; הפונקציה אינה מחזירה תוכן פשוט חלקי לאחר כשל של סיסמה, הרשאה, PDF MAC, תג מחרוזת או תג זרם

‏ReadIncrementalEncryptionContext מאמת את שרשרת המהדורות המוצפנות הנוכחית ומשחזר את מצב האבטחה שהורש. ‏EncryptIncrementalObjectBody מצפין את המחרוזות ואת מטען הזרם באובייקט עקיף אחד שהשתנה, תוך שמירה על פטורי המטא-נתונים ועדכון ערכי /Length ישירים; ‏ClearIncrementalEncryptionContext מנקה חומר מפתח ששוחזר

Functions

Function	Description
`DeriveEncryptionKeys`	מריץ גזירת מפתחות מבוססת-סיסמה ומחזיר את מפתח הקובץ ואת חמש רשומות המילון
`BuildEncryptDictionary`	מסדר את המפתחות והאפשרויות לטקסט מילון ה-`/Encrypt`
`EncryptStreamPayload`	מצפין זרם אובייקט אחד עם AES-256-CBC באמצעות מפתח הקובץ
`EncryptDocumentBytes`	עוזר פעולה-אחת שגוזר מפתחות, כותב מחדש זרמים, ומזריק את מילון ה-`/Encrypt` אל מערך בתים של PDF שלם
`DecryptAesGcmDocumentBytes`	מאמת ומפענח פלט AESV4-GCM אל בתים פשוטים ש-PDFium יכול לטעון
`ValidateEncryptedDocumentMac`	מאמת PDF MAC עצמאי מול בתי המסמך המוצפנים המקוריים באמצעות סיסמת משתמש או בעלים
`ReadIncrementalEncryptionContext`	מאמת שרשרת מהדורות מוצפנת ומשחזר את מפתח הקובץ היורש, את המהדורה, את מדיניות המטא-נתונים, את ההפניה של `/Encrypt`, ואת מצב ה-PDF MAC
`ClearIncrementalEncryptionContext`	מנקה בביטחון חומר מפתח הצפנה מצטבר ששוחזר
`EncryptIncrementalObjectBody`	מצפין מחרוזות וזרמים בגוף אובייקט עקיף אחד שהשתנה, תחת הקשר האבטחה שהורש

Types

Type	Description
`TPdfEncryptionRevision`	ספירה שבוחרת מהדורת AESV3-CBC ‏`erR5` או `erR6`, או מהדורת AESV4-GCM של ISO/TS 32003 ‏`erR7`
`TPdfEncryptOptions`	רשומה שנושאת סיסמאות, דגלי הרשאות, מדיניות מטא-נתונים, מהדורת מטפל-אבטחה, והגנת שלמות PDF MAC אופציונלית
`TPdfEncryptionKeys`	רשומה שמחזיקה את מפתח הקובץ, את רשומות מטפל-האבטחה, ואת `/KDFSalt` בן 32 הבתים האופציונלי
`TPdfIncrementalEncryptionContext`	מצב אבטחה יורש מאומת, המשמש לצירוף אובייקטים עקיפים מוצפנים מבלי להחליף את מילון ה-`/Encrypt` הקיים
`TPdfMacValidationStatus`	‏`pmvsValid`, ‏`pmvsNotPresent`, ‏`pmvsInvalid` או `pmvsUnsupported`
`TPdfMacValidationResult`	‏`Status` של אימות PDF MAC עצמאי ו-`MessageText` אבחוני

Remarks

הפרימיטיבים של ה-AES מגיעים מהיחידה FPdfAes, וה-hashing של SHA-256 מ-FPdfSha256
AESV4 משתמש בקידומת מסמך אקראית אחת בתוספת מונה מונוטוני כדי להבטיח IV ייחודי בן 12 בתים לכל מחרוזת וזרם מוצפנים
‏DecryptAesGcmDocumentBytes עוקב אחר שרשרות מהדורות /Prev קלאסיות שכותב המהדורות המוצפנות פולט, ופותר את generation האובייקט הפעיל החדש ביותר; טעינה מקורית של AESV4 ב-PDFium וקלט AESV4 של xref-stream חיצוני אינם זמינים במהדורה זו
‏Permissions משתמש בפריסת הסיביות של ISO 32000-1 Table 22 (דגלי /P)

יחידת FPdfEncrypt