v2026.05.16 2026年5月パッチ: PDFパスワードと権限制御

POST /api/v1/pdf/render に settings.security を追加しました。AES-128 / AES-256の文書暗号化、任意の所有者パスワード、8種類の権限ロックを指定できます。ProはAES-128 + open_password、EnterpriseはAES-256 + owner_password + 8種類すべての権限制御に対応します。

2026年5月16日 by gPdf Engineering

変更点

added POST /api/v1/pdf/render が settings.security を受け付けるようになりました。サブフィールドは algorithm (aes_128 | aes_256)、open_password、owner_password、permissions{print,modify,copy,annotate,fill_forms,extract_accessibility,assemble,print_high_quality} です。パスワードは32 UTF-8バイトまでです。

added /capabilities/ に10枚目のカード「パスワードと権限ロック」を追加し、8種類すべての権限を展開リストで表示します。JSON-LD ItemList numberOfItems は9から10になりました。/pricing/ のProとEnterpriseの機能リストには、それぞれセキュリティ行が1つ追加されています。

added xAdmin PDF Policy に、ティアごとの document.security.allow と document.security.allowed_algorithms toggle を追加しました。Pro pack は aes_128 のみ、Enterprise pack は両方のalgorithm + owner_password + permissions を含みます。

security メタデータストリームも文書本体と一緒に暗号化されます。/EncryptMetadata は true を書き込みます。

improved API-002 に、settings.security の代表的な誤用を明示しました。意味的に不正なsecurityオブジェクト、32 UTF-8バイトを超えるpassword、現在のtoken policyで許可されていないalgorithm、settings.profile または settings.e_invoice との併用が含まれます。

新機能

POST /api/v1/pdf/render が settings.security オブジェクトを受け付けるようになり、出力PDFにPDF標準セキュリティハンドラーの暗号化を有効化できます。gPdfが暗号化PDFを生成するのは今回が初めてです。これまでのリリースでは、通常のPDFまたはPDF/A文書のみを出力していました。

構造

{
  "settings": {
    "security": {
      "algorithm": "aes_256",
      "open_password": "***",
      "owner_password": "***",
      "permissions": {
        "print": true,
        "modify": false,
        "copy": false,
        "annotate": false,
        "fill_forms": true,
        "extract_accessibility": true,
        "assemble": false,
        "print_high_quality": true
      }
    }
  },
  "pages": []
}

algorithm — aes_128 (default; PDF 1.7 standard-security-handler revision 4, V=4, AESV2 crypt filter) または aes_256 (PDF 2.0 revision 6, V=5, AESV3)。
open_password — PDFを開くために必要なパスワードです。省略した場合、または null、空文字列、空白だけの文字列を送った場合、文書は暗号化されません。
owner_password — open_password とは別のパスワードです。両方を指定する場合は異なる値にする必要があります。所有者としての完全な権限を提供し、permissions で何かを制限する場合に必須です。Enterprise のみ。
permissions — 8 個の boolean で、既定値は true です。いずれかを false にするには owner_password が必要です。Enterprise のみ。

ティアごとのポリシー

	Pro	Enterprise
Algorithms	AES-128 のみ	AES-128 または AES-256
`open_password`	✓	✓
`owner_password`	—	✓
`permissions`	—	✓

同時に使えない設定

settings.security は次の設定と併用できません。

settings.profile (PDF/A) — 暗号化は PDF/A archival contract と仕様上互換性がありません。併用すると API-002 を返します。
settings.e_invoice — Factur-X / ZUGFeRD PDF は、埋め込み XML pipeline で機械可読なままである必要があります。併用すると API-002 を返します。

エラー条件

新しい API-002 は、無効な settings.security に対して発生します。

認識できない algorithm value → 明示的なmessageを持つ API-001
32 UTF-8バイトを超えるpassword
owner_password なしで permissions が指定されている
現在の token の xAdmin PDF Policy が、要求された algorithm を許可していない
settings.profile または settings.e_invoice と併用している

完全な列挙はエラーコードのセクションを参照してください。

サイト上での反映箇所

/capabilities/ — 10枚目のカードとして追加し、8種類すべての権限ビットを展開リストで表示します。
/pricing/ — ProとEnterpriseの機能リストに、新しいセキュリティ機能を説明する行をそれぞれ追加しました。
/docs/api-reference/ — リクエストリファレンスの settings.security に、全サブフィールド表を追加しました。

互換性

settings.security は純粋な追加です。これを含まないrequestは、これまでとまったく同じ出力バイト列を生成します。既存の連携に変更は不要です。