福昕开发者文档中心

OFD 安全信封 ​

本节介绍 OFD 安全信封（OFDEnvelope）能力，包括读取信封信息、验证信封密码、将 OFD 文件加密为信封文件，以及将信封文件解密为 OFD 文件。

OFDEnvelope 是信封处理的工具类，公开能力以静态方法为主；OFDEnvelopeInfo 用于保存信封元数据和加密参数。信封处理不依赖 OFDDoc 或 OFDPage 作为入口。Decrypt 输出普通 OFD 文件后，按 OFD 功能概述 中的打开流程，通过 OFD 文件包 加载 OFDDoc 后继续处理。

任务场景 ​

  • 从信封文件读取标题、文件类型、创建人、有效期、权限、加密算法等信息。
  • 在不解密文件的情况下验证信封密码是否正确。
  • 将普通 OFD 文件加密为信封文件。
  • 将信封文件解密输出为普通 OFD 文件，再进入常规 OFD 处理流程。

API 概览 ​

功能C++ API（foxit::ofd）核心参数 / 描述
信封工具OFDEnvelope仅静态方法：GetEnvelopeInfo、VerifyPassword、
Encrypt、Decrypt
信封信息OFDEnvelopeInfoSetTitle、SetPassword、SetCipher 等；IsEmpty 判断有效性
读取信息OFDEnvelope::GetEnvelopeInfo参数为信封文件路径；不解密正文
验证密码OFDEnvelope::VerifyPasswordpassword + OFDEnvelopeInfo
加密为信封OFDEnvelope::Encryptinfo、输入 OFD 路径、输出信封路径
解密为 OFDOFDEnvelope::Decryptpassword、输入信封路径、输出 OFD 路径
加密算法OFDEnvelopeInfo::EnvelopeEncryptTypeRC4、AES128/192/256、SM4

基本处理流程 ​

信封文件由 SDK 创建和解析，开发者通常不需要直接操作信封内部结构。典型流程如下：

  1. 构造 OFDEnvelopeInfo，设置标题、密码、加密算法等信息。
  2. 调用 OFDEnvelope::Encrypt，将输入 OFD 文件加密输出为信封文件。
  3. 调用 OFDEnvelope::GetEnvelopeInfo 读取信封信息。
  4. 调用 OFDEnvelope::VerifyPassword 验证密码。
  5. 调用 OFDEnvelope::Decrypt，将信封文件解密输出为 OFD 文件。

以下示例演示信封信息读取、密码验证、加密和解密流程。

c++
#include "ofd/fs_ofdenvelope.h"

using namespace foxit;
using namespace foxit::ofd;

bool ProcessOFDEnvelope(const wchar_t* input_ofd_file,
                        const wchar_t* output_envelope_file,
                        const wchar_t* output_ofd_file) {
  OFDEnvelopeInfo info;
  if (info.IsEmpty()) {
    return false;
  }

  info.SetTitle(L"TestEnvelope");
  info.SetDocType(L"OFD");
  info.SetDescription(L"Envelope created by Foxit PDF SDK");
  info.SetCreator(L"Foxit PDF SDK");
  info.SetPassword(L"testpwd");
  info.SetCipher(OFDEnvelopeInfo::e_EnvelopeEncryptTypeAES128);

  if (!OFDEnvelope::Encrypt(info, WString(input_ofd_file), WString(output_envelope_file))) {
    return false;
  }

  OFDEnvelopeInfo envelope_info = OFDEnvelope::GetEnvelopeInfo(WString(output_envelope_file));
  if (envelope_info.IsEmpty()) {
    return false;
  }

  if (!OFDEnvelope::VerifyPassword(String("testpwd"), envelope_info)) {
    return false;
  }

  return OFDEnvelope::Decrypt(String("testpwd"),
                              WString(output_envelope_file),
                              WString(output_ofd_file));
}

信封信息字段 ​

OFDEnvelopeInfo 表示信封信息，常用字段如下：

字段说明
Title信封标题或文件名称
DocType文件类型，例如 OFD
Description信封描述
Creator创建人
CreateTime创建时间
StartTime / ExpirationTime有效期开始与结束时间
Password信封密码
Permission用户权限字符串
FileCode文件代码
HashKey密码哈希值
Filter / SubFilter安全处理器标识
Cipher加密算法，使用 EnvelopeEncryptType 枚举
SecurityType / CryptoType安全类型与加密类型字符串

Cipher 是公开枚举，支持 RC4、AES128、AES192、AES256、SM4。Permission、SecurityType、CryptoType 均以字符串形式返回；SDK 当前未在公开 API 中提供对应枚举定义。使用 Encrypt 创建信封时，如果 Filter、SubFilter、SecurityType 或 CryptoType 为空，SDK 会使用默认值。

字段默认值
Filterhtfoxit.PwdSec
SubFilterhtfoxit.sha256.s1
SecurityTypeStandard
CryptoTypeStandard

注意事项 ​

  • GetEnvelopeInfo 返回的是 OFDEnvelopeInfo，可通过 OFDEnvelopeInfo::IsEmpty 判断对象是否有效。
  • 信封文件内部结构由 SDK 创建和解析，开发者通常不需要直接操作内部 XML 或包结构。