Khắc phục sự cố: mã hóa và cờ quyền

Phạm vi và giới hạn

Dùng các mục này để khắc phục những lỗi giải mã mà engine phát ra qua NextPDF\Exception\EncryptionException và NextPDF\Security\Exception\DecryptionFailedException, đồng thời hiểu rõ giới hạn của cờ quyền Portable Document Format (PDF).

Nên bắt đầu từ giới hạn này, vì đây là điểm dễ gây hiểu lầm nhất: cờ quyền PDF trong từ điển mã hóa chỉ ghi lại ý định của tác giả. Chúng không phải là cơ chế kiểm soát truy cập do thư viện này thực thi. Một trình đọc bỏ qua các cờ này vẫn có thể in, sao chép hoặc chỉnh sửa nội dung. Hãy xem các cờ này như một yêu cầu gửi tới trình đọc có hợp tác, chứ không phải là biện pháp bắt buộc.

Mục: thao tác mã hóa thất bại

Triệu chứng. EncryptionException kèm thông báo có dạng Encryption operation "<op>" failed using algorithm "<algorithm>".
Nguyên nhân có thể. Thao tác mật mã không chạy được, thường do thiếu hoặc cấu hình sai phần mở rộng OpenSSL, vật liệu khóa không hợp lệ, hoặc kích thước vectơ khởi tạo (IV) không hợp lệ tại ranh giới mật mã.
Bằng chứng / chẩn đoán. getContext() trả về algorithm và operation. Giá trị operation là một trong các giá trị encrypt, decrypt hoặc key_derivation, giúp bạn xác định giai đoạn bị lỗi.
Cách khắc phục.
1. Xác nhận rằng phần mở rộng PHP OpenSSL đã được cài đặt và nạp.
2. Dùng trường operation để tìm giai đoạn bị lỗi.
3. Với key_derivation, hãy kiểm tra lại mật khẩu hoặc đầu vào khóa.
4. Chạy lại lệnh gọi.
Liên quan. Tài liệu tham khảo về ngoại lệ.

Mục: giải mã thất bại vì lý do cấu trúc

Triệu chứng. DecryptionFailedException kèm thông báo có dạng Decryption failed for "<algorithm>": <reason>.
Nguyên nhân có thể. Bản mã không thể được xử lý vì một lý do không phải giả mạo, chẳng hạn như bản mã bị cắt cụt, thiếu IV, hoặc cung cấp sai khóa tại ranh giới giao diện lập trình ứng dụng (API). Việc kiểm tra tính toàn vẹn không chạy vì không có đủ dữ liệu để đánh giá.
Bằng chứng / chẩn đoán. getContext() trả về algorithm và reason. Tài liệu nguồn phân biệt DecryptionFailedException với TamperedDataException: ngoại lệ này cho biết lỗi cấu hình hoặc lỗi truyền tải, chứ không phải giả mạo. Đừng tự xem đó là một sự cố bảo mật.
Cách khắc phục.
1. Hãy đọc reason để xác định khiếm khuyết cấu trúc, ví dụ ciphertext shorter than IV+tag.
2. Xác nhận rằng bản mã được truyền tải mà không bị cắt cụt.
3. Xác nhận rằng khóa được cung cấp tại ranh giới đúng là khóa đã dùng để mã hóa tài liệu.
4. Chạy lại lệnh gọi.
Liên quan. Lỗi chữ ký và dấu thời gian.

Mục: một ngoại lệ “dữ liệu bị giả mạo” được phát ra

Triệu chứng. Bạn nhận được NextPDF\Security\Exception\TamperedDataException thay vì DecryptionFailedException.
Nguyên nhân có thể. Việc kiểm tra tính toàn vẹn đã chạy và thất bại. Điều này khác với lỗi giải mã cấu trúc: đã có đủ dữ liệu để đánh giá tính toàn vẹn, và tính toàn vẹn không còn được đảm bảo.
Bằng chứng / chẩn đoán. Nguồn phân biệt hai lớp này: DecryptionFailedException là lỗi cấu trúc và không phải sự cố bảo mật; TamperedDataException cho biết nội dung đã xác thực không vượt qua bước xác minh.
Cách khắc phục.
1. Hãy coi đầu vào là không đáng tin; đừng sử dụng nội dung đã giải mã.
2. Tải lại tài liệu từ một nguồn đáng tin cậy.
3. Nếu lỗi vẫn tiếp diễn với một nguồn đã biết là tốt, hãy ghi lại getContext() để lập báo cáo sự cố.
Liên quan. Lỗi chữ ký và dấu thời gian.

Mục: cờ quyền không ngăn được một hành động ở phía sau

Triệu chứng. Một tài liệu được tạo với các cờ quyền đã đặt — ví dụ, không cho sao chép hoặc in — nhưng trình đọc vẫn sao chép hoặc in nội dung.
Nguyên nhân có thể. Đây là giới hạn dự kiến, không phải lỗi. Số nguyên quyền được truyền cho bộ dựng từ điển mã hóa của core không được thư viện này áp dụng như một biện pháp bắt buộc. Các cờ này là siêu dữ liệu mang tính khuyến nghị; NextPDF sẽ không chặn một trình đọc không tôn trọng chúng.
Bằng chứng / chẩn đoán. src/Security/Encryption/EncryptionDictionaryBuilder.php khai báo buildDict(int $permissions, string $fileId), và ghi chú tham số này là ignored; retained for forward compatibility. Phương thức này bắt đầu bằng unset($permissions, $fileId). Các cờ quyền do src/Inspect/PdfPermissions.php hiển thị là các trường kiểm tra chỉ đọc, không phải lớp thực thi.
Cách khắc phục.
1. Đừng dựa vào cờ quyền để ngăn việc in, sao chép hoặc chỉnh sửa. Chúng không thể được thực thi bởi một thư viện tạo tài liệu.
2. Khi buộc phải giới hạn truy cập, hãy kiểm soát việc phân phối chính tệp đó, hoặc áp dụng một hệ thống kiểm soát truy cập bên ngoài PDF.
3. Chỉ dùng PdfPermissions để báo cáo các cờ mà một tài liệu hiện có khai báo, chứ không để khẳng định rằng những hành động đó đã bị ngăn chặn.
Liên quan. Lỗi chữ ký và dấu thời gian.

Mục: mã hóa bị từ chối khi dùng PDF/A

Triệu chứng. NextPDF\Security\Exception\IncompatiblePdfAModeException khi một bản dựng bật PDF/A đồng thời yêu cầu mã hóa.
Nguyên nhân có thể. Hồ sơ PDF/A cấm khóa Encrypt trong trailer. Engine từ chối tổ hợp này ở cả hai thứ tự gọi.
Bằng chứng / chẩn đoán. Xem mục PDF/A và PDF/UA để biết điều khoản được trích dẫn, các trường getContext() và kiểm thử đường lỗi.
Cách khắc phục.
1. Quyết định xem tài liệu cần tuân thủ lưu trữ hay cần mã hóa.
2. Bỏ lệnh gọi cho thuộc tính mà bạn không cần.
3. Chạy lại pipeline.
Liên quan. Xác thực PDF/A và PDF/UA.

Trường hợp đặc biệt & lưu ý

DecryptionFailedException và TamperedDataException mang ý nghĩa khác nhau: lỗi cấu trúc so với lỗi toàn vẹn. Hãy rẽ nhánh theo lớp, chứ không theo thông báo.
Bộ dựng từ điển mã hóa của core bỏ qua số nguyên quyền; bất kỳ bản dựng nào phụ thuộc vào việc thực thi quyền từ gói core đều dựa trên một hiểu lầm.
PdfPermissions chỉ được điền cho các tài liệu đã mã hóa ở độ sâu kiểm tra đầy đủ và phản ánh các cờ đã khai báo. Một trường được điền không có nghĩa là hành động đó đã bị ngăn chặn.

Xem thêm

Bảng thuật ngữ: cờ quyền · giải mã có xác thực