← 文章 / 编程开发
freeCodeCamp 1小时前 · 2026-11-21 03:25:36 · 0 阅读

用 JavaScript 构建浏览器端 PDF 密码保护工具

合同、发票、医疗报告、扫描的身份证件,常常会被转成 PDF 文件。但如果其中一份不小心发错了邮箱,或被放到了共享硬盘上,任何人都能打开它。

加个密码就能解决这个问题。受保护的 PDF 是加密过的,只有输入正确的密码才能读取内容。

大多数在线工具都要求你先把文档上传上去。可对一个你正想保护隐私的文件来说,先上传上去未免有些奇怪。

在本教程中,你将用 JavaScript 构建一个基于浏览器的 PDF 密码保护工具:打开 PDF、设置密码、决定是否允许打印、复制或编辑,用 AES-256 加密文件,检查结果并下载。整个过程中文件不会离开浏览器。

有意思的是,最流行的 JavaScript PDF 库 PDF-lib 并不支持加密。所以你得借助 Web Crypto API,按照 PDF 2.0 规范自己实现加密。代码量比想象中少:大约 150 行。

这个工具是我为 All In One Tools 开发的,也就是其中的 Protect PDF 工具。本文会带你实现一个简化版本,只需三个文件。

All In One Tools 上的 Protect PDF 工具,显示用于添加 PDF 的拖放区域

本文内容

这个 PDF 加密工具能做什么

这个工具完成后,你可以点击按钮打开 PDF,或者直接把文件拖到页面上。你可以设置一个打开文件所需的密码(还可以额外设置一个用于权限控制的密码),也能选择允许用户打印、复制文字和图片,或编辑文件。

工具会用 AES-256 加密 PDF,验证新文件确实要求输入密码且你的密码能打开它,最后支持重命名并下载加密后的副本。

整个过程中,原始文件不会被改动,也不会有任何数据发送到服务器。

PDF 加密的原理

在写代码之前,先了解一下受保护 PDF 的内部结构会很有帮助。你不需要去读规范文档,但理解下面这五个概念能让后文更容易跟上。

1. 内容被加密,结构没有

PDF 由一系列带编号的对象组成:字典、数组、数字、名称、字符串和流(流是一块数据,比如某个页面的绘图指令或一张图片)。PDF 被保护后,每个字符串和每个流都会被加密。而数字、名称以及对象之间的引用关系保持可读,这样 PDF 阅读器依然能在文件中正常导航。

2. 一个随机密钥加密所有内容

工具会生成一个随机的 256 位文件密钥,并用它通过 AES 加密所有字符串和流。密码本身并不是密钥。

3. 密码用来解锁密钥

文件会把文件密钥存储两次,分别用两个密码的哈希加密,同时还存有一个校验值,让阅读器能判断输入的密码是否正确。这些值放在加密字典里,文件的 trailer 通过 /Encrypt 指向它。

4. 有两种密码

  • 用户密码(打开密码):打开文件必须用到。
  • 所有者密码(权限密码):除了打开文件,还能修改权限设置。

5. 权限限制并不是真正的锁

允许的操作(打印、复制、编辑)以位的形式存储在一个叫 /P 的数字里。规范的 PDF 阅读器会遵守这些限制,但如果某个程序选择忽略它们,文件一旦被打开,照样可以打印或复制。真正保护内容的是打开密码。

PDF 多年来使用过多种加密方法:

方法 Revision 状态
RC4 40 位和 128 位 R2 到 R4 老旧且不安全,新文件不要使用
AES-128 R4 Acrobat 7 及更新版本可以打开
AES-256 R6 PDF 2.0 标准,Acrobat X 及更新版本以及所有主流 PDF 应用都能打开

本工具采用 AES-256(revision 6)。这是最强的方案,实现起来也最简单,因为所有对象共用同一个密钥。

下面来看整体流程。

从 PDF 文件开始:

  • PDF-lib 加载对象
  • 生成随机的文件密钥(32 字节)
  • 由密码派生出 U、UE、O、OE、Perms(SHA-2 + AES)
  • 所有字符串和流都用 AES-256 加密
  • trailer 中加入 /Encrypt 字典和 /ID
  • 用 PDF.js 验证生成的 PDF,然后下载

项目搭建

项目只有三个文件,不需要构建步骤:

pdf-protector/
├── index.html
├── style.css
└── script.js

由于 Web Crypto API 只能在安全上下文中使用,页面必须通过 https:// 或 http://localhost 打开。如果用 file:// 路径或普通 http:// 地址打开 index.html,crypto.subtle 会是 undefined。

启动本地服务器最简单的方式是:

npx serve .

然后打开它输出的地址,比如 http://localhost:3000。

使用的库和浏览器 API

PDF-lib 1.17.1 负责把 PDF 读成可操作的对象,改完再写回去。它不支持加密,这正是你要自己实现的部分。

PDF.js 3.11.174 是 Mozilla 的 PDF 阅读器。你会用它像真正的阅读器那样打开加密后的文件,验证加密是否生效。

Web Crypto API 内置于所有现代浏览器,提供 AES 加密、SHA-256/384/512 哈希和安全随机数。生成密钥时千万别用 Math.random()。

两个库都在 index.html 末尾通过 CDN 引入:

<script src="https://unpkg.com/pdf-lib@1.17.1/dist/pdf-lib.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script>
<script src="script.js"></script>

搭建 HTML 页面结构

页面分为三部分:上传区、用于设置密码和权限的设置面板,以及结果面板。设置面板和结果面板初始处于隐藏状态。

<!-- 1. 上传 -->
<section id="uploadArea" class="upload-area">
  <p>将 PDF 拖拽到这里,或</p>
  <button type="button" id="selectBtn">选择 PDF</button>
  <input type="file" id="fileInput" accept="application/pdf,.pdf" hidden>
  <p id="fileInfo" class="file-info" aria-live="polite"></p>
</section>

<!-- 2. 密码设置 -->
<section id="settings" class="panel" hidden>
  <h2>密码</h2>

  <label for="openPw">打开 PDF 的密码</label>
  <div class="pw-row">
    <input type="password" id="openPw" autocomplete="new-password">
    <button type="button" class="show-btn" data-target="openPw">显示</button>
  </div>
  <p id="strength" class="hint">请至少使用 8 个字符。</p>

  <label for="openPw2">再次输入密码</label>
  <input type="password" id="openPw2" autocomplete="new-password">

  <label for="ownerPw">权限密码(可选)</label>
  <div class="pw-row">
    <input type="password" id="ownerPw" autocomplete="new-password">
    <button type="button" class="show-btn" data-target="ownerPw">显示</button>
  </div>
  <p class="hint">用于之后修改下方的权限限制。留空则自动生成随机密码。</p>

  <h2>打开后允许哪些操作?</h2>
  <label class="check"><input type="checkbox" id="allowPrint" checked> 打印</label>
  <label class="check"><input type="checkbox" id="allowCopy" checked> 复制文字和图片</label>
  <label class="check"><input type="checkbox" id="allowEdit"> 编辑、批注和填写表单</label>

  <button type="button" id="protectBtn" class="primary">加密 PDF</button>
  <p id="status" class="status" aria-live="polite"></p>
</section>

<!-- 3. 结果 -->
<section id="result" class="panel" hidden>
  <h2>加密后的 PDF 已生成</h2>
  <ul id="checks" class="checks"></ul>
  <label for="fileName">文件名</label>
  <input type="text" id="fileName">
  <button type="button" id="downloadBtn" class="primary">下载 PDF</button>
</section>

这里有几个细节值得注意:

  • 密码输入框使用了 autocomplete="new-password",这样浏览器就不会自动填充已保存的登录密码。
  • 状态提示行使用了 aria-live="polite",让屏幕阅读器可以播报诸如“两次输入的密码不一致”之类的消息。
  • 文件选择框是隐藏的,改用一个普通按钮来触发它,这样更容易设置样式。

CSS 部分就是普通的布局和配色,这里就不展开了,你可以直接从示例文件中复制。

PDF 密码保护工具的上传区域,带有“选择 PDF”按钮

打开 PDF

首先,script.js 从两个库中引入所需的类,为 PDF.js 指定 worker 路径,并把应用的状态集中保存在一个对象里:

// ---------- Setup ----------
const { PDFDocument, PDFName, PDFNumber, PDFBool, PDFHexString, PDFString,
  PDFDict, PDFArray, PDFRawStream } = PDFLib;

pdfjsLib.GlobalWorkerOptions.workerSrc =
  'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js';

const state = {
  file: null,     // the File the user picked
  bytes: null,    // its contents as a Uint8Array
  pages: 0,
  result: null    // the protected PDF as a Uint8Array
};

const $ = (id) => document.getElementById(id);
const uploadArea = $('uploadArea');
const fileInput = $('fileInput');
const fileInfo = $('fileInfo');
const settings = $('settings');
const openPw = $('openPw');
const openPw2 = $('openPw2');
const ownerPw = $('ownerPw');
const strength = $('strength');
const protectBtn = $('protectBtn');
const statusText = $('status');
const result = $('result');
const checks = $('checks');
const fileName = $('fileName');
const downloadBtn = $('downloadBtn');

用户可以点击按钮选择文件,也可以直接把文件拖到上传区域:

// ---------- 打开 PDF ----------
$('selectBtn').addEventListener('click', () => fileInput.click());
fileInput.addEventListener('change', () => {
  if (fileInput.files[0]) loadFile(fileInput.files[0]);
  fileInput.value = '';
});

uploadArea.addEventListener('dragover', (e) => {
  e.preventDefault();
  uploadArea.classList.add('dragover');
});
uploadArea.addEventListener('dragleave', () => uploadArea.classList.remove('dragover'));
uploadArea.addEventListener('drop', (e) => {
  e.preventDefault();
  uploadArea.classList.remove('dragover');
  if (e.dataTransfer.files[0]) loadFile(e.dataTransfer.files[0]);
});

读取文件后把 fileInput.value 设为空字符串,这样用户才能再次选择同一个文件。

loadFile 会检查文件是否为 PDF,将其读入 Uint8Array,然后用 PDF-lib 加载:

async function loadFile(file) {
  const isPdf = file.type === 'application/pdf' || /\.pdf$/i.test(file.name);
  if (!isPdf) {
    fileInfo.textContent = `${file.name} is not a PDF.`;
    return;
  }

  const bytes = new Uint8Array(await file.arrayBuffer());
  try {
    const doc = await PDFDocument.load(bytes, { updateMetadata: false });
    state.file = file;
    state.bytes = bytes;
    state.pages = doc.getPageCount();
  } catch (err) {
    fileInfo.textContent = /encrypted/i.test(err.message)
      ? `${file.name} already has a password. Unlock it first.`
      : `${file.name} could not be read. The file may be damaged.`;
    return;
  }

  fileInfo.textContent = `${file.name}: ${state.pages} page(s), ${formatSize(file.size)}`;
  settings.hidden = false;
  result.hidden = true;
  openPw.focus();
}

function formatSize(n) {
  if (n < 1024) return n + ' B';
  if (n < 1024 * 1024) return (n / 1024).toFixed(1) + ' KB';
  return (n / 1024 / 1024).toFixed(1) + ' MB';
}

这一步加载文件有两个作用:一是统计页数,方便后面核对结果;二是拦截已设置密码的文件——PDF-lib 遇到加密文件时会抛出包含 "encrypted" 的错误信息,工具据此提示用户先解锁文件。

这里的 updateMetadata: false 选项很关键。PDF-lib 默认会在加载文档时修改文件的 Producer 和修改日期,而我们只想添加密码,不想改动文档的其他信息。

提示所选 PDF 已设有密码、必须先解锁的消息 PDF 加载后显示页数和文件大小,以及密码和权限设置

处理密码输入框

每个 Show 按钮会在 password 和 text 之间切换对应输入框的类型,方便用户查看自己输入的内容:

// ---------- 密码输入框 ----------
document.querySelectorAll('.show-btn').forEach((btn) => {
  btn.addEventListener('click', () => {
    const input = $(btn.dataset.target);
    const show = input.type === 'password';
    input.type = show ? 'text' : 'password';
    btn.textContent = show ? 'Hide' : 'Show';
  });
});

用户输入时,一段简短的提示会对密码强度做出评价。它会统计密码中包含几种类型的字符(小写字母、大写字母、数字和符号):

openPw.addEventListener('input', () => {
  const pw = openPw.value;
  const kinds = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^A-Za-z0-9]/]
    .filter((re) => re.test(pw)).length;

  if (pw.length < 8) {
    strength.textContent = 'Use at least 8 characters.';
    strength.className = 'hint weak';
  } else if (pw.length >= 12 && kinds >= 3) {
    strength.textContent = 'Strong password.';
    strength.className = 'hint good';
  } else {
    strength.textContent = 'OK. A longer password with numbers and symbols is stronger.';
    strength.className = 'hint';
  }
});

这算不上真正的强度检测器,也不需要是。它的作用只是引导用户别用 1234 这类密码。

加密之前,passwordProblem 会检查各项条件:有问题就返回对应的提示消息,没问题则返回空字符串:

function passwordProblem() {
  if (openPw.value.length < 8) return 'The password must have at least 8 characters.';
  if (openPw.value !== openPw2.value) return 'The two passwords are different.';
  if (ownerPw.value && ownerPw.value === openPw.value) {
    return 'Use a different permissions password, or leave it empty.';
  }
  return '';
}

最后这条规则是因为:如果两个密码相同,权限设置就毫无意义——能打开文件的人自然也能修改权限。

密码输入框带红色边框,提示两个密码不一致

字节和 Web Crypto 工具函数

加密操作的对象是字节,所以需要几个小工具函数。concat 用于拼接字节数组,randomBytes 生成安全的随机字节,toHex 把字节转成 PDF-lib 需要的十六进制字符串:

// ---------- 字节工具 ----------
function concat(...parts) {
  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
  let offset = 0;
  for (const p of parts) {
    out.set(p, offset);
    offset += p.length;
  }
  return out;
}

const randomBytes = (n) => crypto.getRandomValues(new Uint8Array(n));

function toHex(bytes) {
  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
}

// PDF 2.0 的密码是 UTF-8 编码、经过规范化、最长 127 字节
function passwordBytes(text) {
  return new TextEncoder().encode(text.normalize('NFKC')).slice(0, 127);
}

passwordBytes 按 PDF 2.0 要求的方式处理密码:UTF-8 编码、最长 127 字节。normalize('NFKC') 这一步确保看起来相同的字符以相同方式存储,比如在不同键盘上输入的 é 会产生相同的字节。规范里用的是更严格的 SASLprep 流程,但 NFKC 已经覆盖了实际会遇到的场景。

接下来是 Web Crypto 工具函数:

// ---------- Web Crypto 工具 ----------
async function digest(algorithm, data) {
  return new Uint8Array(await crypto.subtle.digest(algorithm, data));
}

// AES-CBC + PKCS#7 填充(PDF 处理字符串和流用的就是它)
async function aesEncrypt(keyBytes, iv, data) {
  const key = await crypto.subtle.importKey('raw', keyBytes, 'AES-CBC', false, ['encrypt']);
  return new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-CBC', iv }, key, data));
}

// 不带填充的 AES-CBC:输入已经是 16 字节的倍数,
// 所以只保留前 data.length 字节,丢弃多余的填充块
async function aesEncryptNoPad(keyBytes, iv, data) {
  return (await aesEncrypt(keyBytes, iv, data)).slice(0, data.length);
}


Web Crypto 的 AES-CBC 总会自动加 PKCS#7 填充。PDF 的字符串和流本来就需要填充,所以 aesEncrypt 正好适用。但加密字典里有几个值必须不加填充地加密。它们的输入长度始终是 16 字节的整数倍,因此只要取输出中的前 data.length 个字节即可,aesEncryptNoPad 就是简单地丢掉多出来的填充块。

按 PDF 2.0 的方式对密码做哈希

AES-256 加密的 PDF 并不是直接对密码做一次 SHA-256,而是使用一种更慢的哈希算法(ISO 32000-2 中的算法 2.B),目的是让暴力猜密码的代价变得很高:

// ---------- PDF 2.0 密码哈希 ----------
// ISO 32000-2 算法 2.B:先做 SHA-256,再经过至少 64 轮
// AES-128 + SHA-256/384/512,让猜密码变得很慢
async function hashPassword(password, salt, userKey) {
  let k = await digest('SHA-256', concat(password, salt, userKey));
  let e = new Uint8Array([0]);
  let round = 0;

  while (round < 64 || e[e.length - 1] > round - 32) {
    const block = concat(password, k, userKey);
    const k1 = new Uint8Array(block.length * 64);
    for (let i = 0; i < 64; i++) k1.set(block, i * block.length);

    e = await aesEncryptNoPad(k.slice(0, 16), k.slice(16, 32), k1);

    let sum = 0;
    for (let i = 0; i < 16; i++) sum += e[i];
    const hash = ['SHA-256', 'SHA-384', 'SHA-512'][sum % 3];
    k = await digest(hash, e);
    round++;
  }
  return k.slice(0, 32);
}

具体流程如下:

  1. 先对密码、盐值(对于所有者密码还包括 48 字节的 U 值)做一次 SHA-256 哈希。
  2. 把密码、当前哈希和附加数据重复 64 次,用 AES-128 加密这个大块。密钥和 IV 取自当前哈希。
  3. 把结果的前 16 个字节求和,除以 3 取余,据此决定下一轮哈希用 SHA-256、SHA-384 还是 SHA-512。
  4. 至少执行 64 轮,然后继续循环,直到加密块最后一个字节不大于轮数减 32 为止。
  5. 最终哈希的前 32 个字节就是结果。

由于轮数和哈希函数都取决于数据本身,攻击者很难用专用硬件加速这一过程。而在浏览器里,整个过程也只需要几毫秒。

把权限转换成一个数字

权限信息以 32 位数字的形式存储在 /P 中,其中每一位对应一种操作:

// ---------- Permissions ----------
// Bit positions from the PDF specification (bit 1 is the lowest bit)
const PERM = {
  print: 1 << 2,          // bit 3
  modify: 1 << 3,         // bit 4
  copy: 1 << 4,           // bit 5
  annotate: 1 << 5,       // bit 6
  fillForms: 1 << 8,      // bit 9
  accessibility: 1 << 9,  // bit 10
  assemble: 1 << 10,      // bit 11
  printHigh: 1 << 11      // bit 12
};

function permissionFlags({ print, copy, edit }) {
  let p = 0xFFFFF0C0;                    // reserved bits that must be 1
  p |= PERM.accessibility;               // always allow screen readers
  if (print) p |= PERM.print | PERM.printHigh;
  if (copy) p |= PERM.copy;
  if (edit) p |= PERM.modify | PERM.annotate | PERM.fillForms | PERM.assemble;
  return p | 0;                          // as a signed 32-bit number
}

起始值 0xFFFFF0C0 用于设置规范要求必须始终为 1 的位。接着函数会打开第 10 位(用于无障碍访问的文本提取),保证屏幕阅读器正常工作,然后根据用户勾选的选项打开对应的位:

工具中的选项 打开的位
打印 第 3 位(打印)和第 12 位(高质量打印)
复制文本和图片 第 5 位
编辑、批注和填写表单 第 4、6、9 和 11 位

最后的 p | 0 会把数值转换为有符号 32 位整数。高位被置 1 时结果是负数,这是正常的:大多数 PDF 里都会看到类似 /P -1324 这样的值。

打开密码被标记为强,允许打印、禁止复制和编辑

构建加密密钥

接下来就可以构建加密字典所需的各个值了:

// ---------- 构建加密字典的各项值 ----------
async function makeKeys(userText, ownerText, p) {
  const fileKey = randomBytes(32);       // 用于加密整个文档的密钥
  const user = passwordBytes(userText);
  const owner = passwordBytes(ownerText);
  const none = new Uint8Array(0);
  const zeroIv = new Uint8Array(16);

  // U 和 UE:校验打开密码,并用它解锁文件密钥
  const uValidation = randomBytes(8);
  const uKeySalt = randomBytes(8);
  const U = concat(await hashPassword(user, uValidation, none), uValidation, uKeySalt);
  const UE = await aesEncryptNoPad(await hashPassword(user, uKeySalt, none), zeroIv, fileKey);

  // O 和 OE:对权限密码做同样的处理(它们还依赖 U)
  const oValidation = randomBytes(8);
  const oKeySalt = randomBytes(8);
  const O = concat(await hashPassword(owner, oValidation, U), oValidation, oKeySalt);
  const OE = await aesEncryptNoPad(await hashPassword(owner, oKeySalt, U), zeroIv, fileKey);

  // Perms:权限位,用文件密钥加密,防止被篡改
  const perms = new Uint8Array(16);
  new DataView(perms.buffer).setInt32(0, p, true);   // 小端序
  perms.set([0xFF, 0xFF, 0xFF, 0xFF], 4);
  perms.set([0x54, 0x61, 0x64, 0x62], 8);            // 'T'(加密元数据)、'a'、'd'、'b'
  perms.set(randomBytes(4), 12);
  const Perms = await aesEncryptNoPad(fileKey, zeroIv, perms);

  return { fileKey, U, UE, O, OE, Perms };
}

逐个说明一下:

  • fileKey 是 32 字节的随机数,用来加密整个文档。
  • U(48 字节)让阅读器校验用户密码。它由密码哈希加两个 8 字节随机盐组成:一个校验盐用于验证密码,一个密钥盐用于解锁密钥。
  • UE 是文件密钥,用用户密码和密钥盐派生的哈希加密。输入正确密码后,阅读器会重新计算这个哈希并解密出文件密钥。
  • O 和 OE 对权限密码做同样的处理。它们的哈希还包含 U,这样就把两个密码绑定到了同一个文件上。
  • Perms 是权限位数字加上几个校验字节,再用文件密钥加密。阅读器解密后会与 /P 比对,因此有人直接在文本编辑器里改 /P 就会被发现。

规范里有两条规则在这里派上用场:

  • UE、OE 和 Perms 的加密不做填充,且 IV 全为零。(Perms 只有一个 16 字节块,所以零 IV 的 AES-CBC 和规范描述的 AES-ECB 模式结果相同。)
  • Perms 中的字节 T 表示“元数据也被加密”,它必须与字典里的 /EncryptMetadata true 一致。

加密所有字符串和流

文件密钥就绪后,就可以加密文档了。对于 AES-256,每个字符串或流都用文件密钥和一个新的随机 16 字节 IV 加密,IV 存放在加密数据的前面:

// ---------- Encrypting the objects ----------
// With AES-256 every string and stream is encrypted with the file key
// and a fresh random IV, which is stored in front of the encrypted data
async function encryptData(fileKey, data) {
  const iv = randomBytes(16);
  return concat(iv, await aesEncrypt(fileKey, iv, data));
}

async function encryptStrings(value, fileKey) {
  if (value instanceof PDFDict) {
    for (const [key, item] of value.entries()) {
      const replacement = await encryptValue(item, fileKey);
      if (replacement) value.set(key, replacement);
    }
  } else if (value instanceof PDFArray) {
    for (let i = 0; i < value.size(); i++) {
      const replacement = await encryptValue(value.get(i), fileKey);
      if (replacement) value.set(i, replacement);
    }
  }
}

async function encryptValue(item, fileKey) {
  if (item instanceof PDFString || item instanceof PDFHexString) {
    return PDFHexString.of(toHex(await encryptData(fileKey, item.asBytes())));
  }
  await encryptStrings(item, fileKey);   // nested dictionaries and arrays
  return null;
}

async function encryptObjects(context, fileKey) {
  const objects = context.enumerateIndirectObjects();
  for (const [ref, object] of objects) {
    if (object instanceof PDFRawStream) {
      const type = object.dict.get(PDFName.of('Type'));
      if (type === PDFName.of('XRef')) {     // old cross-reference streams
        context.delete(ref);
        continue;
      }
      await encryptStrings(object.dict, fileKey);
      const data = await encryptData(fileKey, object.contents);
      context.assign(ref, PDFRawStream.of(object.dict, data));
    } else {
      await encryptStrings(object, fileKey);
    }
  }
}

encryptObjects 会遍历文件中的每一个对象:

  • 流(PDFRawStream):用加密后的数据替换原数据。PDF-lib 在保存时会自动更新 /Length 条目。
  • 字典和数组:encryptStrings 会遍历它们,把每个字符串替换为加密后的十六进制字符串。嵌套的字典和数组通过递归调用来处理。
  • 交叉引用流(/Type /XRef)会被删除。它们描述的是对象在旧文件中的位置,反正 PDF-lib 会重新写入新的交叉引用表,而且这类流绝不能被加密。

PDF-lib 有两种字符串类型:PDFString 表示字面量字符串(如 (Hello)),PDFHexString 表示十六进制字符串(如 <48656C6C6F>)。两者都有一个 asBytes() 方法,可以返回真实的字节内容,加密时用的就是这些字节。

流数据是按文件中的原样加密的,通常已经处于压缩状态。这个顺序是正确的:阅读器会先解密,再解压。

写出受保护的 PDF

protectPdf 把上述步骤整合在一起:

// ---------- 保护 PDF ----------
async function protectPdf(bytes, options) {
  const doc = await PDFDocument.load(bytes, { updateMetadata: false });
  const context = doc.context;

  const p = permissionFlags(options);
  const ownerText = options.ownerPw || toHex(randomBytes(16));
  const keys = await makeKeys(options.openPw, ownerText, p);

  // 1. 加密文件中已有的所有字符串和流
  await encryptObjects(context, keys.fileKey);

  // 2. 添加加密字典(它自身绝不能被加密)
  const hex = (b) => PDFHexString.of(toHex(b));
  const stdCF = context.obj({ AuthEvent: 'DocOpen', CFM: 'AESV3', Length: 32 });
  const encrypt = context.obj({
    Filter: 'Standard',
    V: 5,
    R: 6,
    Length: 256,
    CF: context.obj({ StdCF: stdCF }),
    StmF: 'StdCF',
    StrF: 'StdCF',
    P: PDFNumber.of(p),
    EncryptMetadata: PDFBool.True
  });
  encrypt.set(PDFName.of('U'), hex(keys.U));
  encrypt.set(PDFName.of('UE'), hex(keys.UE));
  encrypt.set(PDFName.of('O'), hex(keys.O));
  encrypt.set(PDFName.of('OE'), hex(keys.OE));
  encrypt.set(PDFName.of('Perms'), hex(keys.Perms));

  // 3. 让 trailer 指向它,并为文件生成 ID
  context.trailerInfo.Encrypt = context.register(encrypt);
  const id = hex(randomBytes(16));
  context.trailerInfo.ID = context.obj([id, id]);

  // 对象流会隐藏第 1 步处理的对象,所以要以普通对象形式写出
  return doc.save({ useObjectStreams: false });
}

具体步骤如下:

  1. 加密已有对象:这一步必须在添加加密字典之前完成,因为字典本身必须保持可读。
  2. 创建加密字典:context.obj() 会把普通字符串转换为 PDF 名称,比如 Filter: 'Standard' 会变成 /Filter /Standard。V 5 和 R 6 表示 PDF 2.0 的 AES-256,而加密过滤器 StdCF 配合 CFM AESV3 告诉阅读器对流(StmF)和字符串(StrF)都使用 AES-256。
  3. 更新 trailer:trailer 中会加入 /Encrypt 引用和新的 /ID。PDF-lib 会自动把 trailerInfo 写入 trailer,并且不会对 ID 进行加密。

如果用户没有填写权限密码,工具会用 16 个随机字节作为所有者密码。没有人知道这个密码,也就没人能解除限制。(如果所有者密码为空,任何 PDF 程序都能把这些限制删掉。)

最后,文件以 useObjectStreams: false 保存。对象流会把多个对象打包进一个压缩流里,这种流内部的字符串不能再单独加密,因为整个流已经加密过了。既然你已经逐个加密了每个字符串,写入普通对象才能保证文件正确。

保存后的文件里,加密字典是这样的:

<<
/Filter /Standard /V 5 /R 6 /Length 256
/CF << /StdCF << /AuthEvent /DocOpen /CFM /AESV3 /Length 32 >> >>
/StmF /StdCF /StrF /StdCF
/P -1324 /EncryptMetadata true
/U <...48 bytes...> /UE <...32 bytes...>
/O <...48 bytes...> /OE <...32 bytes...>
/Perms <...16 bytes...>
>>

用 PDF.js 验证结果

加密相关的 bug 很容易出现,却很难察觉。文件可能在这个阅读器能打开、在另一个却打不开,甚至根本没加密。所以在提供下载之前,工具会先用 PDF.js 打开自己生成的输出做验证:

// ---------- Checking the result with PDF.js ----------
async function verify(bytes, password) {
  const results = [];

  // 1. Without a password, PDF.js must ask for one
  try {
    const doc = await pdfjsLib.getDocument({ data: bytes.slice() }).promise;
    await doc.destroy();
    results.push([false, 'The file opened without a password']);
  } catch (err) {
    results.push([err.name === 'PasswordException', 'Asks for a password when opened']);
  }

  // 2. With the password, it must open and have every page
  try {
    const doc = await pdfjsLib.getDocument({ data: bytes.slice(), password }).promise;
    results.push([doc.numPages === state.pages, `Opens with your password (${doc.numPages} page(s))`]);
    await doc.destroy();
  } catch (err) {
    results.push([false, 'Could not open it with your password']);
  }
  return results;
}

共两项检查:

  1. 不带密码打开文件必须失败并抛出 PasswordException。如果能打开,说明文件没受保护。
  2. 带上密码必须能正常打开,且页数与原文件一致。

bytes.slice() 传入的是副本,因为 PDF.js 会把 buffer 移交给它的 worker,原数组会因此变成空数组。

连接按钮

点击事件处理器会校验密码、调用 protectPdf、执行各项检查并展示结果:

// ---------- Running everything ----------
protectBtn.addEventListener('click', async () => {
  const problem = passwordProblem();
  openPw.setAttribute('aria-invalid', String(openPw.value.length < 8));
  openPw2.setAttribute('aria-invalid', String(openPw.value !== openPw2.value));
  if (problem) {
    statusText.textContent = problem;
    statusText.className = 'status error';
    return;
  }

  protectBtn.disabled = true;
  statusText.className = 'status';
  statusText.textContent = 'Encrypting…';
  try {
    const options = {
      openPw: openPw.value,
      ownerPw: ownerPw.value,
      print: $('allowPrint').checked,
      copy: $('allowCopy').checked,
      edit: $('allowEdit').checked
    };
    state.result = await protectPdf(state.bytes, options);

    statusText.textContent = 'Checking the protected file…';
    const results = await verify(state.result, options.openPw);
    checks.innerHTML = '';
    for (const [ok, text] of results) {
      const li = document.createElement('li');
      li.textContent = (ok ? '✅ ' : '❌ ') + text;
      checks.appendChild(li);
    }
    const sizeLi = document.createElement('li');
    sizeLi.textContent = 'Size: ' + formatSize(state.result.length);
    checks.appendChild(sizeLi);

    fileName.value = state.file.name.replace(/\.pdf$/i, '') + '-protected.pdf';
    statusText.textContent = '';
    result.hidden = false;
    result.scrollIntoView({ behavior: 'smooth' });
  } catch (err) {
    console.error(err);
    statusText.textContent = 'Something went wrong: ' + err.message;
    statusText.className = 'status error';
  } finally {
    protectBtn.disabled = false;
  }
});

任务执行期间按钮会被禁用,避免双击触发两次加密。finally 块负责重新启用按钮,即使中途出错也不例外。

重命名与下载

结果面板会给出一个类似 report-protected.pdf 的建议文件名。用户点击 Download PDF 时,会先清理文件名再保存文件:

// ---------- 下载 ----------
downloadBtn.addEventListener('click', () => {
  let name = fileName.value.trim().replace(/[\\/:*?"<>|]+/g, '-') || 'protected.pdf';
  if (!/\.pdf$/i.test(name)) name += '.pdf';

  const blob = new Blob([state.result], { type: 'application/pdf' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = name;
  a.click();
  setTimeout(() => URL.revokeObjectURL(url), 60000);
});

正则表达式会把 Windows 文件名中不允许的字符替换掉。对象 URL 会在一分钟之后释放,足以让浏览器完成下载的启动。

结果面板显示 PDF 需要密码并可用密码打开,同时展示文件名和 Download 按钮

在浏览器之外验证文件

如果加密后的 PDF 只能在自己的工具里打开,那没什么意义。所以还需要在其他软件中测试输出结果。

qpdf 是一个免费的命令行工具,对加密 PDF 的校验非常严格。下面这些命令可以检查文件并显示加密设置:

# 应输出:"invalid password"
qpdf --check report-protected.pdf

# 应输出:"No syntax or stream encoding errors found"
qpdf --check --password='your password' report-protected.pdf

# 显示 R = 6、AESv3 以及各项权限
qpdf --show-encryption --password='your password' report-protected.pdf

对于本文的版本,qpdf --show-encryption 会输出:

R = 6
P = -1324
User password = Correct-Horse-42
Supplied password is user password
extract for accessibility: allowed
extract for any purpose: allowed
print low resolution: allowed
print high resolution: allowed
modify document assembly: not allowed
modify forms: not allowed
modify annotations: not allowed
modify other: not allowed
modify anything: not allowed
stream encryption method: AESv3
string encryption method: AESv3
file encryption method: AESv3

另外,也可以在浏览器的 PDF 查看器和 Adobe Acrobat Reader 中打开这个文件。两者都应该要求输入密码,而且 Acrobat 的 Document Properties > Security 标签页里应该能看到你设置的各项限制。

演示:加密 PDF 工具的工作原理

下面是 All In One Tools 完整工具中的操作流程。

第 1 步:添加 PDF

把 PDF 拖到页面上,或者点击 Select PDF。页面会显示各页的预览,方便你在加密前确认文件没问题。

已上传的 PDF,显示文件名、大小和页面大图预览

第 2 步:设置密码和权限限制

输入两次打开密码。如果想限制打印、复制或编辑,开启相应限制并单独设置一个权限密码。默认使用 AES-256 加密。

密码设置界面:已选择 AES-256,包含打开密码、权限密码以及打印和复制限制

第 3 步:验证并下载

工具会在浏览器中打开加密后的文件,验证它会要求输入密码、正确密码能通过、错误密码会被拒绝,然后显示预览。你可以重命名文件,再点击 Download PDF 下载。

加密后的 PDF 预览,浏览器内验证已通过,并提供 Download PDF 按钮

性能建议

以下几点可以帮助工具保持良好性能。

第一,逐个处理对象。代码对每次加密都用 await 依次执行,这样内存占用更低,因为同一时间只复制一个流。如果文件包含成千上万个小对象,可以用 Promise.all 按批次(比如每批 50 个)加密来提速。

第二,文件会略微变大。每个字符串和流会增加一个 16 字节的 IV,最多再加上 16 字节的填充;而且不使用对象流保存会让交叉引用表变大。一个 4 KB 的文件可能变成 8 KB,而 5 MB 的文件只增加几 KB。

第三,验证时不要重复加密。工具验证的就是即将下载的那份文件的字节。下载时不要再跑一遍 protectPdf,否则文件会生成新的随机密钥,之前的验证结果也就不适用了。

最后,处理完大文件后记得释放内存。用完 PDF.js 文档后调用 doc.destroy(),就像 verify 里那样。否则 worker 会一直把解析后的文件留在内存中。

常见错误

开发这个工具时,还有几个坑要避开。

首先,不要通过纯 http:// 打开页面。crypto.subtle 只在安全上下文中可用。在 http://example.com 或 file:// 路径下,代码会报错 "Cannot read properties of undefined (reading 'digest')"。请使用 https:// 或 localhost。

不要用 Math.random() 生成密钥或盐值。它不是为安全场景设计的,输出结果可以被预测。始终使用 crypto.getRandomValues()。

也不要对加密字典本身进行加密。如果 /U、/O 或 /Perms 字符串被加密了,任何阅读器都无法校验密码。正确的做法是先加密文档,再添加字典。

避免用对象流保存。PDF-lib 默认使用对象流保存。在加密场景下,对象流里的字符串会被加密两次。要传入 useObjectStreams: false。

另外,把字节数据传给 PDF.js 时别忘了 slice()。PDF.js 会把 buffer 转移给它的 worker,之后你原来的 Uint8Array 就空了,下载下来就是 0 字节的文件。

不要把权限限制当成安全保障。限制打印和复制对守法用户有用,但算不上保护。如果内容必须保密,关键还是打开密码。

不要对已数字签名的 PDF 加密。加密会改动签名覆盖的每一个字节,导致签名失效。应该先加密码,再对受保护的文件签名。

最后,确保你和用户都不会弄丢密码。AES-256 没有后门,也没有“忘记密码”功能。要提醒用户把密码存放在安全的地方。

总结

在本教程中,你构建了一个基于浏览器的工具,用 AES-256 加密为 PDF 添加密码保护。

你了解了 PDF 加密的组织结构,学会了如何用 PDF 2.0 算法对密码做哈希,如何用 Web Crypto API 构建 U、UE、O、OE 和 Perms 值,如何用 PDF-lib 加密每个字符串和流,以及如何用 PDF.js 和 qpdf 验证结果。

所有流程都在浏览器中完成,文档始终留在用户的设备上。

你可以在 Protect PDF 体验完整版工具,它还支持页面预览、AES-128 和针对老旧阅读器的 RC4 选项、仅允许低分辨率打印,以及更细粒度的权限设置。

如果你想扩展自己的版本,可以参考以下几个思路:

  • 添加一个 Unlock 工具,在用户知道密码的前提下解除密码保护
  • 允许用户选择"仅允许低分辨率打印"(设置第 3 位但不设置第 12 位)
  • 用一个密码批量保护多个 PDF
  • 当 PDF 含有数字签名时给出警告提示
原始来源: freeCodeCamp

评论 (0)