암호화 (HasSecurity)

Document의 HasSecurity 트레이트는 Aes256Encryptor 엔진을 통해 AES-256 암호화를 제공합니다. TCPDF-Next는 PDF 2.0 보안 핸들러(AESV3, Revision 6, V5)만을 구현합니다 -- RC4와 AES-128은 의도적으로 제거되었습니다. 비밀번호는 올바른 유니코드 처리를 위해 SASLprep(RFC 4013)을 통해 정규화되며, 키 유도는 Algorithm 2.B(반복 SHA-256/384/512)를 사용합니다.

빠른 참조

메서드	설명
setProtection()	권한과 비밀번호로 AES-256 암호화 활성화

암호화 활성화

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setProtection(
        permissions: ['print', 'copy'],
        userPass: 'reader-password',
        ownerPass: 'owner-secret-password',
    )
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'This PDF is AES-256 encrypted', newLine: true)
    ->save('encrypted.pdf');

setProtection()은 static을 반환하므로 다른 모든 Document 메서드와 체이닝됩니다.

$pdf->setProtection(
    array  $permissions = [],   // 권한 플래그 (아래 표 참조)
    string $userPass    = '',   // 문서를 열 때 필요한 비밀번호
    string $ownerPass   = '',   // 무제한 액세스를 위한 비밀번호
);

사용자 비밀번호 vs 소유자 비밀번호

• 사용자 비밀번호 -- 리더가 PDF를 열고 보려면 이 비밀번호를 입력해야 합니다. 비어 있으면 프롬프트 없이 문서가 열리지만 권한 제한은 여전히 적용됩니다.
• 소유자 비밀번호 -- 모든 권한 제한을 우회하여 문서에 대한 전체 액세스를 부여합니다. 비어 있으면 내부적으로 무작위 32바이트 소유자 비밀번호가 생성됩니다.

두 비밀번호 모두 키 유도 전에 SASLprep(RFC 4013)을 통해 정규화됩니다. 이는 "Pässwörd"와 같은 유니코드 비밀번호가 모든 PDF 뷰어에서 일관되게 처리되도록 보장합니다.

권한 플래그

$permissions 배열에 다음 문자열 플래그를 조합하여 전달합니다:

플래그	설명
print	인쇄 허용 (저해상도)
modify	콘텐츠 수정 허용
copy	텍스트 및 이미지 추출 허용
annotate	주석 추가 허용
fill-forms	폼 필드 입력 허용
extract	접근성 추출 허용
assemble	페이지 삽입, 회전 및 삭제 허용
print-highres	고해상도 인쇄 허용

$permissions가 비어 있으면 모든 작업이 제한됩니다 (모든 작업에 소유자 비밀번호 필요).

소유자 전용 암호화

비밀번호 없이 열 수 있지만 권한을 제한하려면:

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setProtection(
        permissions: ['print', 'fill-forms'],
        ownerPass: 'admin-password',
    )
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Open freely, but only print and fill forms.', newLine: true)
    ->save('restricted.pdf');

문서는 비밀번호 프롬프트 없이 열리지만, 소유자 비밀번호가 제공되지 않으면 수정, 복사 및 주석이 차단됩니다.

보안 아키텍처

TCPDF-Next는 가장 강력한 PDF 암호화 표준만을 적용합니다:

• 알고리즘: AES-256-CBC (AESV3), Revision 6, V5
• 키 길이: 256비트
• 레거시 없음: RC4와 AES-128은 의도적으로 제거됨

SASLprep 비밀번호 정규화

SaslPrep 클래스(RFC 4013)는 NFKC 유니코드 정규화로 비밀번호를 정규화하고, 금지된 문자를 거부하며, 양방향 텍스트 제약을 적용합니다. 이는 플랫폼이나 입력 방법에 관계없이 동일한 해시를 보장합니다.

키 유도 -- Algorithm 2.B

ISO 32000-2 Algorithm 2.B는 반복 SHA-256/384/512 해싱(최대 64라운드)을 통해 암호화 키를 유도하여, 무차별 대입 공격에 대한 강력한 저항력을 제공합니다.

PDF/A 비호환성

암호화는 PDF/A 준수 문서에서 허용되지 않습니다. PDF/A 모드가 활성화된 문서에서 setProtection()을 호출하려고 하면 PdfAException이 발생합니다:

use Yeeefang\TcpdfNext\Core\Document;

// PdfAException을 발생시킵니다
$pdf = Document::create()
    ->setPdfA(true)
    ->setProtection(permissions: ['print'], ownerPass: 'secret');
// -> throws PdfAException: "Encryption is not allowed in PDF/A documents"

보관 준수와 액세스 제어가 모두 필요한 경우, 권한 제한이 있는 디지털 서명 사용을 고려하십시오.

전체 예제

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTitle('Confidential Report')
    ->setAuthor('Security Team')
    ->setProtection(
        permissions: ['print-highres', 'copy'],
        userPass: 'open-me',
        ownerPass: 'full-access-2026',
    )
    ->addPage()
    ->setFont('Helvetica', 'B', 18)
    ->cell(0, 15, 'Confidential Report', newLine: true)
    ->setFont('Helvetica', '', 12)
    ->multiCell(0, 6, 'This document is protected with AES-256 encryption. '
        . 'Readers can print and copy, but cannot modify or annotate.')
    ->save('confidential-report.pdf');