用 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 工具。本文会带你实现一个简化版本,只需三个文件。
本文内容
- 这个 PDF 保护工具能做什么
- PDF 加密的原理
- 项目搭建
- 用到的库和浏览器 API
- 创建 HTML 布局
- 打开 PDF
- 处理密码输入框
- 字节和 Web Crypto 辅助函数
- 按 PDF 2.0 规范对密码做哈希
- 把权限设置转换为数字
- 构建加密密钥
- 加密所有字符串和流
- 生成加密后的 PDF
- 用 PDF.js 验证结果
- 绑定按钮事件
- 重命名与下载
- 在浏览器外测试文件
- 演示:Protect 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
首先,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 和修改日期,而我们只想添加密码,不想改动文档的其他信息。
处理密码输入框
每个 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);
}
具体流程如下:
- 先对密码、盐值(对于所有者密码还包括 48 字节的
U值)做一次 SHA-256 哈希。 - 把密码、当前哈希和附加数据重复 64 次,用 AES-128 加密这个大块。密钥和 IV 取自当前哈希。
- 把结果的前 16 个字节求和,除以 3 取余,据此决定下一轮哈希用 SHA-256、SHA-384 还是 SHA-512。
- 至少执行 64 轮,然后继续循环,直到加密块最后一个字节不大于轮数减 32 为止。
- 最终哈希的前 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 });
}
具体步骤如下:
- 加密已有对象:这一步必须在添加加密字典之前完成,因为字典本身必须保持可读。
- 创建加密字典:
context.obj()会把普通字符串转换为 PDF 名称,比如Filter: 'Standard'会变成/Filter /Standard。V 5和R 6表示 PDF 2.0 的 AES-256,而加密过滤器StdCF配合CFM AESV3告诉阅读器对流(StmF)和字符串(StrF)都使用 AES-256。 - 更新 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;
}
共两项检查:
- 不带密码打开文件必须失败并抛出
PasswordException。如果能打开,说明文件没受保护。 - 带上密码必须能正常打开,且页数与原文件一致。
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 只能在自己的工具里打开,那没什么意义。所以还需要在其他软件中测试输出结果。
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。页面会显示各页的预览,方便你在加密前确认文件没问题。
第 2 步:设置密码和权限限制
输入两次打开密码。如果想限制打印、复制或编辑,开启相应限制并单独设置一个权限密码。默认使用 AES-256 加密。
第 3 步:验证并下载
工具会在浏览器中打开加密后的文件,验证它会要求输入密码、正确密码能通过、错误密码会被拒绝,然后显示预览。你可以重命名文件,再点击 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 含有数字签名时给出警告提示