rustpdf 0.4.3-x86_64-linux → 0.4.5-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95532283bdf3fafe95ca9e1227ea40e36c4fdce81f3b28544ae66dabcafa1939
-  data.tar.gz: 29c18936673cb3d467a881c0cab11f9c0d85ee2dbb4839059a292694eb27c9f8
+  metadata.gz: 1e1a51e3817bb0d67e1769dae5b88b46e8691b106670c5fe00667a1f0fa6f29b
+  data.tar.gz: e2496c1209908d600fa54c27b1a75c9773763ab76033564190686f5a8407d46d
 SHA512:
-  metadata.gz: 84e472bbc222217ea7d5db1f1a345e3159ea9185e2afefeb033a50f244065ff68029d9bf7206911c423262c1a2637dabd561e24137d2a90aeb0fbcac5d4c64b1
-  data.tar.gz: 8db08da3b030c712be6ae50b67cffbe6fbc47c59e5dcab4b27904438662836e01ccb06bbbf5c47fa3dd17e2e5b1c98fe874fae0f8e28abd1d95f442b45969b85
+  metadata.gz: 62c4b0d61e522dd37037887ed0a7db658f093fa206713975085a7f45e0bf0a3bf2a9c7b11a2431d112363458e5842d08ae352d81bc35d14eaa2dd4b9b41c8e5f
+  data.tar.gz: 95c1d90d8cefa73f1fccabd1eccede8eae9b8bb1bdd144eb8b7ace08e82c94c46f4de37242494bbae51a161eb2c0c637599a2ee2eaf80ba8be95f98e7dba962e

data/README.md

@@ -49,6 +49,38 @@ signed = RustPdf.sign(data, key_der, cert_der, pades: true)
 Corporate features (PDF/A, signing, encryption, accessibility, page rendering — a **Pro** feature) require a license;
 without one they raise `RustPdf::Error`. See [`docs/LICENSING.md`](../../docs/LICENSING.md).
 
+## Deferred / HSM signing
+
+Sign without the private key ever entering this library — the key stays in an
+HSM, cloud KMS, smartcard or PKI token. Works with any PKI (eIDAS, AATL, or
+your own CA). The library builds the CMS and asks your code only for the raw
+RSA signature over the bytes it hands you.
+
+```ruby
+require "rustpdf"
+
+pdf      = File.binread("contract.pdf")
+cert_der = File.binread("signing-cert.der")   # X.509 signer certificate (DER)
+
+# Model A — your block returns the raw RSA PKCS#1 v1.5 signature; the key
+# never reaches the library. Call your HSM / cloud KMS / token here.
+signed = RustPdf.sign_with(pdf, cert_der,
+                           chain: [issuer_der],
+                           options: RustPdf::SigningOptions.new(reason: "Approved")) do |to_sign|
+  hsm.sign_rsa_sha256(to_sign)   # bytes in, raw signature out
+end
+File.binwrite("contract.signed.pdf", signed)
+
+# Model B — two-phase: prepare, sign the hash out of band, then complete.
+session   = RustPdf.begin_signing(pdf)
+container = remote.build_cms(session.hash)     # send #hash to a remote signer
+final     = session.complete(container)        # embed the DER CMS / PKCS#7
+```
+
+`RustPdf.list_signatures(pdf)` inventories existing signature fields before you
+sign. See [`docs/ruby.html`](../../site/public/docs/ruby.html#sign) for the full
+deferred-signing API (`SigningOptions`, `Certify`, `SignaturePolicy`).
+
 ## Test
 
 ```sh

data/lib/rustpdf/editable_doc.rb

@@ -127,19 +127,58 @@ module RustPdf
       text.split("\n").reject(&:empty?)
     end
 
-    # Stamp a diagonal text watermark across every page.
-    def watermark_text(text, size: 64.0, color: [0.5, 0.5, 0.5], opacity: 0.30, rotation_deg: 45.0)
+    # Stamp a diagonal text watermark across every page. When
+    # +opaque_background+ is true, the text is drawn over an opaque white box
+    # (otherwise it is blended into the page content).
+    def watermark_text(text, size: 64.0, color: [0.5, 0.5, 0.5], opacity: 0.30,
+                       rotation_deg: 45.0, opaque_background: false)
       r, g, b = color
-      RustPdf.check(Native.call("pdf_editable_watermark_text", ptr, text, size, r, g, b, opacity, rotation_deg))
+      RustPdf.check(Native.call("pdf_editable_watermark_text", ptr, text, size, r, g, b,
+                                opacity, rotation_deg, opaque_background ? 1 : 0))
       self
     end
 
-    # Stamp an image watermark (from a file) across every page.
-    def watermark_image_file(path, width, height, opacity: 0.30)
-      RustPdf.check(Native.call("pdf_editable_watermark_image_file", ptr, path, width, height, opacity))
+    # Stamp an image watermark (from a file) across every page, rotated
+    # +rotation_deg+ degrees counter-clockwise.
+    def watermark_image_file(path, width, height, opacity: 0.30, rotation_deg: 0.0)
+      RustPdf.check(Native.call("pdf_editable_watermark_image_file", ptr, path, width, height,
+                                opacity, rotation_deg))
       self
     end
 
+    # ---- positioned drawing primitives (issue #45 P1) -----------------------
+
+    # Paint a filled rectangle at (+x+, +y+) sized +width+ x +height+ on page
+    # +page_index+ (0-based), in RGB +color+ (each 0..1, default opaque white) at
+    # +opacity+ (0..1). Coordinates are in the page's VISIBLE space (origin
+    # lower-left, y up), regardless of the page's /Rotate. The common use is
+    # masking a placeholder with an opaque white box. Returns whether the page
+    # existed.
+    def fill_rect(page_index, x, y, width, height, color = [1.0, 1.0, 1.0], opacity = 1.0)
+      r, g, b = color
+      found = RustPdf.out_int do |buf|
+        Native.call("pdf_editable_fill_rect", ptr, page_index, x.to_f, y.to_f,
+                    width.to_f, height.to_f, r.to_f, g.to_f, b.to_f, opacity.to_f, buf)
+      end
+      found != 0
+    end
+
+    # Draw a line of positioned +text+ with baseline at (+x+, +y+) on page
+    # +page_index+ (0-based), using standard Helvetica at +size+ points in RGB
+    # +color+ (each 0..1, default black). +rotation_deg+ rotates the text
+    # counter-clockwise about its anchor (match the page rotation to follow a
+    # rotated page). Coordinates are in the page's VISIBLE space (origin
+    # lower-left, y up), regardless of the page's /Rotate. Returns whether the
+    # page existed.
+    def place_text(page_index, x, y, text, size = 12.0, color = [0.0, 0.0, 0.0], rotation_deg = 0.0)
+      r, g, b = color
+      found = RustPdf.out_int do |buf|
+        Native.call("pdf_editable_place_text", ptr, page_index, x.to_f, y.to_f, text,
+                    size.to_f, r.to_f, g.to_f, b.to_f, rotation_deg.to_f, buf)
+      end
+      found != 0
+    end
+
     # ---- redaction + PDF/A conversion (Tier 2) ------------------------------
 
     # Black out rectangles on a page. rects = [[x0,y0,x1,y1], ...].
@@ -156,6 +195,29 @@ module RustPdf
       self
     end
 
+    # ---- version normalization (issue #41 P1) -------------------------------
+
+    # Set the output PDF version (downgrade/normalize). +version+ uses the
+    # RustPdf::Version codes (V1_4=0, V1_5=1, V1_7=2, V2_0=3).
+    def set_version(version)
+      RustPdf.check(Native.call("pdf_editable_set_version", ptr, version))
+      self
+    end
+
+    # Strip PDF/A conformance (OutputIntents, XMP pdfaid, /Version) so the file
+    # is a plain PDF.
+    def strip_pdfa
+      RustPdf.check(Native.call("pdf_editable_strip_pdfa", ptr))
+      self
+    end
+
+    # Normalize to a plain PDF at +version+ (strip PDF/A + set version). Codes as
+    # in #set_version.
+    def normalize(version = Version::V1_7)
+      RustPdf.check(Native.call("pdf_editable_normalize", ptr, version))
+      self
+    end
+
     def optimize
       RustPdf.check(Native.call("pdf_editable_optimize", ptr))
       self

data/lib/rustpdf/native.rb

@@ -97,13 +97,38 @@ module RustPdf
       "pdf_editable_set_choice"      => [[VP, VP, VP, VP], I],
       "pdf_editable_flatten_forms"   => [[VP], I],
       "pdf_editable_field_names"     => [[VP, VP, VP], I],
-      "pdf_editable_watermark_text"  => [[VP, VP, D, D, D, D, D, D], I],
-      "pdf_editable_watermark_image_file" => [[VP, VP, D, D, D], I],
+      # watermark_text gained a trailing int opaque_background; watermark_image
+      # gained a trailing double rotation_deg (issue #41 P1).
+      "pdf_editable_watermark_text"  => [[VP, VP, D, D, D, D, D, D, I], I],
+      "pdf_editable_watermark_image_file" => [[VP, VP, D, D, D, D], I],
       # Tier 2: redaction + PDF/A conversion (EditableDoc)
       "pdf_editable_redact"          => [[VP, SZ, VP, SZ, VP], I],
       "pdf_editable_convert_to_pdfa" => [[VP, I], I],
       # Tier 2: signature validation (module-level)
       "pdf_verify_signatures_json"   => [[VP, SZ, VP, VP], I],
+
+      # Deferred / external (HSM) signing — issue #41 P0. The PdfSigningOptions
+      # struct crosses as an opaque pointer (VP); the Model-A callback is a
+      # Fiddle::Closure passed as a function pointer (VP).
+      "pdf_sign_begin"               => [[VP, SZ, VP, VP, VP, VP, VP], I],
+      "pdf_sign_complete"            => [[VP, SZ, VP, SZ, VP, VP], I],
+      "pdf_sign_with"                => [[VP, SZ, VP, SZ, VP, VP, SZ, VP, VP, VP, VP, VP], I],
+      "pdf_list_signatures"          => [[VP, SZ, VP, VP], I],
+
+      # Issue #41 P1: positional text search, version normalization, network TSA.
+      "pdf_find_text_json"           => [[VP, SZ, VP, I, VP, VP], I],
+      "pdf_editable_set_version"     => [[VP, I], I],
+      "pdf_editable_strip_pdfa"      => [[VP], I],
+      "pdf_editable_normalize"       => [[VP, I], I],
+      "pdf_timestamp_begin"          => [[VP, SZ, VP, VP, VP, VP], I],
+      "pdf_timestamp_request"        => [[VP, SZ, VP, SZ, I, VP, VP], I],
+      "pdf_timestamp_token_from_response" => [[VP, SZ, VP, VP], I],
+
+      # Issue #45 P1: page geometry, document inspection, positioned drawing.
+      "pdf_measure_pages_json"       => [[VP, SZ, VP, VP], I],
+      "pdf_inspect_json"             => [[VP, SZ, VP, VP], I],
+      "pdf_editable_fill_rect"       => [[VP, I, D, D, D, D, D, D, D, D, VP], I],
+      "pdf_editable_place_text"      => [[VP, I, D, D, VP, D, D, D, D, D, VP], I],
     }.freeze
 
     def lib

data/lib/rustpdf.rb

@@ -1,5 +1,6 @@
 require "fiddle"
 require "json"
+require "digest"
 require_relative "rustpdf/native"
 
 # Idiomatic Ruby binding for the rust-pdf core over its C ABI (libpdf_ffi),
@@ -55,6 +56,14 @@ module RustPdf
     AES256 = 2
   end
 
+  # Output PDF version (for set_version / normalize).
+  module Version
+    V1_4 = 0
+    V1_5 = 1
+    V1_7 = 2
+    V2_0 = 3
+  end
+
   # ZUGFeRD / Factur-X conformance profiles.
   module FacturxProfile
     MINIMUM = 0
@@ -91,6 +100,114 @@ module RustPdf
     end
   end
 
+  # DocMDP certification level applied by the first (certifying) signature.
+  module Certify
+    NONE = 0                  # not a certifying signature
+    LOCKED = 1                # /P 1 — no changes permitted after signing
+    FORMS = 2                 # /P 2 — form-filling and signing permitted
+    FORMS_AND_ANNOTATIONS = 3 # /P 3 — also annotations permitted
+  end
+
+  # A signature-policy identifier (PAdES-EPES / ICP-Brasil AD-RB).
+  class SignaturePolicy
+    attr_accessor :oid, :hash, :hash_algorithm_oid, :uri
+
+    # +oid+: dotted-decimal policy OID; +hash+: policy document hash bytes
+    # (under +hash_algorithm_oid+, nil = SHA-256); +uri+: optional SPURI.
+    def initialize(oid:, hash:, hash_algorithm_oid: nil, uri: nil)
+      @oid = oid
+      @hash = hash
+      @hash_algorithm_oid = hash_algorithm_oid
+      @uri = uri
+    end
+  end
+
+  # Options for deferred / external signing (issue #41). The +visible_*+ fields
+  # request a visible signature appearance: +visible_rect+ is [x0,y0,x1,y1] in
+  # points, +visible_text+ is newline-separated appearance lines, and
+  # +visible_image+ is PNG/JPEG bytes of a handwritten-signature image.
+  class SigningOptions
+    attr_accessor :reason, :location, :name, :pades, :certify, :container_size, :policy,
+                  :visible, :visible_page, :visible_rect, :visible_text, :visible_image
+
+    def initialize(reason: nil, location: nil, name: nil, pades: false,
+                   certify: Certify::NONE, container_size: 0, policy: nil,
+                   visible: false, visible_page: 0, visible_rect: nil,
+                   visible_text: nil, visible_image: nil)
+      @reason = reason
+      @location = location
+      @name = name
+      @pades = pades
+      @certify = certify
+      @container_size = container_size
+      @policy = policy
+      @visible = visible
+      @visible_page = visible_page
+      @visible_rect = visible_rect
+      @visible_text = visible_text
+      @visible_image = visible_image
+    end
+  end
+
+  # A signature field discovered in a PDF (pre-signing inventory). +signed+ is
+  # true when the field already carries a signature.
+  SignatureField = Struct.new(:name, :signed)
+
+  # One positional text match from #find_text. Coordinates are in PDF points,
+  # origin lower-left; +x+/+y+ is the lower-left corner of the box.
+  TextHit = Struct.new(:page, :text, :x, :y, :width, :height)
+
+  # A rectangle in PDF user space (points, origin lower-left). Used for a page's
+  # MediaBox/CropBox. #width / #height are the (non-negative) extents.
+  PdfRect = Struct.new(:x0, :y0, :x1, :y1) do
+    def width
+      (x1 - x0).abs
+    end
+
+    def height
+      (y1 - y0).abs
+    end
+  end
+
+  # Read-only geometry of one page (from #measure_page / #measure_pages). Sizes
+  # are in PDF points; +width+/+height+ ignore rotation while +rotated_width+/
+  # +rotated_height+ account for it (swapped for 90/270 pages). +media_box+ and
+  # +crop_box+ are PdfRect values.
+  PageGeometry = Struct.new(:page, :width, :height, :rotation,
+                            :rotated_width, :rotated_height, :media_box, :crop_box)
+
+  # A non-mutating summary of a PDF (from #inspect_pdf). +pdfa_level+ is nil when
+  # the document is not PDF/A; +encryption+ is the cipher name ("None" when the
+  # document is not encrypted).
+  PdfOverview = Struct.new(:version, :pdfa_level, :encrypted, :encryption,
+                           :requires_password, :page_count)
+
+  # An in-progress two-phase signature: #document holds the placeholder PDF and
+  # #bytes the exact bytes the signature covers. Hand #hash to a remote signer,
+  # build the CMS container, then call #complete.
+  class SigningSession
+    # The prepared PDF (with a zero-filled /Contents placeholder).
+    attr_reader :document
+    # The exact bytes covered by the signature (the two ByteRange segments).
+    attr_reader :bytes
+
+    def initialize(document, bytes)
+      @document = document
+      @bytes = bytes
+    end
+
+    # SHA-256 of #bytes — the 32-byte value an HSM signs.
+    def hash
+      Digest::SHA256.digest(@bytes)
+    end
+
+    # Phase 2: complete the signature by embedding a finished DER CMS / PKCS#7
+    # +container+, returning the final signed PDF.
+    def complete(container)
+      RustPdf.complete_signature(@document, container)
+    end
+  end
+
   module_function
 
   # Native library version string.
@@ -133,10 +250,67 @@ module RustPdf
     count[0, Native::SIZEOF_SZ].unpack1("J")
   end
 
+  # Find every occurrence of +query+ in +pdf+, returning positional boxes.
+  # Returns an Array of TextHit (page, text, x, y, width, height) in PDF points
+  # (origin lower-left). +case_sensitive+ defaults to false. An empty Array
+  # means no match.
+  def find_text(pdf, query, case_sensitive: false)
+    js = take_bytes do |pp, pn|
+      Native.call("pdf_find_text_json", pdf, pdf.bytesize, query, case_sensitive ? 1 : 0, pp, pn)
+    end.force_encoding(Encoding::UTF_8)
+    return [] if js.empty?
+
+    JSON.parse(js).map do |h|
+      TextHit.new(h["page"], h["text"], h["x"], h["y"], h["width"], h["height"])
+    end
+  end
+
+  # Read the geometry (size, rotation, MediaBox, CropBox) of every page in +pdf+,
+  # in page order, without mutating it. Returns an Array of PageGeometry. Sizes
+  # are in PDF points; +rotated_width+/+rotated_height+ swap for 90/270 pages.
+  def measure_pages(pdf)
+    js = take_bytes { |pp, pn| Native.call("pdf_measure_pages_json", pdf, pdf.bytesize, pp, pn) }
+         .force_encoding(Encoding::UTF_8)
+    return [] if js.empty?
+
+    rect = lambda do |arr|
+      a = Array(arr)
+      a.size == 4 ? PdfRect.new(a[0], a[1], a[2], a[3]) : PdfRect.new(0, 0, 0, 0)
+    end
+    JSON.parse(js).map do |g|
+      PageGeometry.new(g["page"], g["width"], g["height"], g["rotation"],
+                       g["rotatedWidth"], g["rotatedHeight"],
+                       rect.call(g["mediaBox"]), rect.call(g["cropBox"]))
+    end
+  end
+
+  # Read the geometry of a single 0-based page of +pdf+. Raises IndexError if
+  # +index+ is out of range.
+  def measure_page(pdf, index)
+    pages = measure_pages(pdf)
+    raise IndexError, "page index #{index} out of range (#{pages.size} pages)" if index.negative? || index >= pages.size
+
+    pages[index]
+  end
+
+  # Inspect +pdf+ without mutating it: PDF version, PDF/A level (if any),
+  # encryption posture and page count. Works even on password-protected files
+  # (the encryption fields are still reported). Returns a PdfOverview. Named
+  # +inspect_pdf+ to avoid shadowing Object#inspect.
+  def inspect_pdf(pdf)
+    js = take_bytes { |pp, pn| Native.call("pdf_inspect_json", pdf, pdf.bytesize, pp, pn) }
+         .force_encoding(Encoding::UTF_8)
+    o = JSON.parse(js)
+    PdfOverview.new(o["version"], o["pdfaLevel"], o["encrypted"] ? true : false,
+                    o["encryption"], o["requiresPassword"] ? true : false, o["pageCount"])
+  end
+
   # Validate every signature in +pdf+. Returns one Hash per signature with keys
   # "field_name", "sub_filter", "signer", "covers_whole_document",
-  # "digest_valid", "signature_valid", "is_valid" and "byte_range". An empty
-  # array means the document is unsigned.
+  # "digest_valid", "signature_valid", "is_valid" and "byte_range", plus the
+  # richer certificate fields (any may be null): "issuer", "serial_number",
+  # "valid_from", "valid_to", "algorithm", "signing_time", "cert_count" and
+  # "has_timestamp". An empty array means the document is unsigned.
   def verify_signatures(pdf)
     js = take_bytes { |pp, pn| Native.call("pdf_verify_signatures_json", pdf, pdf.bytesize, pp, pn) }
          .force_encoding(Encoding::UTF_8)
@@ -177,8 +351,213 @@ module RustPdf
     result
   end
 
+  # ---- deferred / external (HSM) signing — issue #41 ------------------------
+
+  # Model A — remote signer. Sign +pdf+ without handing this library a key: it
+  # builds the CMS signed attributes and calls the given block for the raw RSA
+  # PKCS#1 v1.5 signature (over SHA-256 of the block's argument), then assembles
+  # and embeds the CMS. +cert_der+ is the signer certificate (DER); +chain+ are
+  # intermediate certificates (DER), supplied independently of the key. The
+  # private key never reaches this library. Returns the signed PDF bytes.
+  def sign_with(pdf, cert_der, chain: [], options: nil, &block)
+    raise Error, "sign_with requires a block that produces the signature" unless block
+
+    opts_bytes, keep = build_signing_options(options)
+    cptrs = chain.map { |c| Fiddle::Pointer[c] }
+    cptr_buf = cptrs.map(&:to_i).pack("J*")
+    clen_buf = chain.map(&:bytesize).pack("J*")
+
+    signer_error = nil
+    closure = Fiddle::Closure::BlockCaller.new(
+      Fiddle::TYPE_INT,
+      [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T,
+       Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP]
+    ) do |_ctx, data, data_len, sig_buf, sig_cap, sig_len|
+      begin
+        sig = block.call(data[0, data_len]).to_s
+        if sig.bytesize > sig_cap
+          signer_error = Error.new("signature (#{sig.bytesize} bytes) exceeds buffer capacity #{sig_cap}")
+          next 2
+        end
+        sig_buf[0, sig.bytesize] = sig
+        sig_len[0, Native::SIZEOF_SZ] = [sig.bytesize].pack("J")
+        0
+      rescue StandardError => e
+        signer_error = e
+        1
+      end
+    end
+
+    begin
+      result = take_bytes do |pp, pn|
+        Native.call("pdf_sign_with", pdf, pdf.bytesize, cert_der, cert_der.bytesize,
+                    cptr_buf, clen_buf, chain.size, opts_bytes, closure, Fiddle::NULL, pp, pn)
+      end
+    rescue Error
+      raise signer_error if signer_error
+
+      raise
+    end
+    # keep the callback, struct and per-cert pointers alive until the call returned
+    cptrs.clear
+    keep.clear
+    closure.to_i # touch to keep it referenced past the native call
+    result
+  end
+
+  # Model B — two-phase signing, phase 1. Prepare +pdf+ for deferred signing:
+  # returns a SigningSession whose #hash you send to a remote HSM. Build the CMS
+  # container, then call SigningSession#complete (or .complete_signature). The
+  # key never reaches this library.
+  def begin_signing(pdf, options: nil)
+    opts_bytes, keep = build_signing_options(options)
+    doc_p = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    doc_n = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    tbs_p = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    tbs_n = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    check(Native.call("pdf_sign_begin", pdf, pdf.bytesize, opts_bytes, doc_p, doc_n, tbs_p, tbs_n))
+    keep.clear
+    SigningSession.new(read_buffer(doc_p, doc_n), read_buffer(tbs_p, tbs_n))
+  end
+
+  # Model B — phase 2. Embed a complete DER CMS / PKCS#7 +container+ into a
+  # prepared +document+ (from #begin_signing), returning the final signed PDF.
+  def complete_signature(document, container)
+    take_bytes do |pp, pn|
+      Native.call("pdf_sign_complete", document, document.bytesize, container, container.bytesize, pp, pn)
+    end
+  end
+
+  # ---- network TSA (AD-RT) document timestamp — issue #41 -------------------
+
+  # Phase 1 of a network-TSA document timestamp (/DocTimeStamp). Prepares +pdf+
+  # and returns [document_bytes, tbs_bytes]: +tbs_bytes+ are the bytes whose
+  # SHA-256 forms the RFC 3161 message imprint. Build a TimeStampReq with
+  # #timestamp_request, POST it to the TSA, extract the token with
+  # #timestamp_token_from_response, then embed it via #complete_signature.
+  def begin_timestamp(pdf)
+    doc_p = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    doc_n = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    tbs_p = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    tbs_n = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
+    check(Native.call("pdf_timestamp_begin", pdf, pdf.bytesize, doc_p, doc_n, tbs_p, tbs_n))
+    [read_buffer(doc_p, doc_n), read_buffer(tbs_p, tbs_n)]
+  end
+
+  # Build an RFC 3161 TimeStampReq (DER) for +imprint+ (the SHA-256 of the bytes
+  # to timestamp, e.g. the +tbs_bytes+ from #begin_timestamp). +nonce+ is
+  # optional; +cert_req+ asks the TSA to embed its certificate. Returns the
+  # request bytes to POST to the TSA.
+  def timestamp_request(imprint, nonce: nil, cert_req: true)
+    take_bytes do |pp, pn|
+      Native.call("pdf_timestamp_request", imprint, imprint.bytesize,
+                  nonce, nonce ? nonce.bytesize : 0, cert_req ? 1 : 0, pp, pn)
+    end
+  end
+
+  # Extract the TimeStampToken (a CMS ContentInfo) from a TSA's RFC 3161
+  # TimeStampResp +response+ bytes. The returned token is embedded via
+  # #complete_signature(document, token).
+  def timestamp_token_from_response(response)
+    take_bytes do |pp, pn|
+      Native.call("pdf_timestamp_token_from_response", response, response.bytesize, pp, pn)
+    end
+  end
+
+  # List the signature fields in +pdf+ (detect existing signatures before
+  # signing). Returns an Array of SignatureField; an empty Array means there are
+  # no signature fields.
+  def list_signatures(pdf)
+    text = take_bytes { |pp, pn| Native.call("pdf_list_signatures", pdf, pdf.bytesize, pp, pn) }
+           .force_encoding(Encoding::UTF_8)
+    fields = []
+    text.each_line do |line|
+      line = line.chomp
+      tab = line.index("\t")
+      next unless tab
+
+      fields << SignatureField.new(line[(tab + 1)..-1], line[0...tab] == "1")
+    end
+    fields
+  end
+
   # ---- internal helpers (used by Document/EditableDoc) ----------------------
 
+  # Marshal a SigningOptions (or nil) into the C PdfSigningOptions struct bytes,
+  # returning [packed_struct, keepalive] where +keepalive+ holds the Fiddle
+  # pointers backing the struct's string/byte fields (keep it referenced until
+  # the native call returns). 64-bit layout: 3 ptr, 2 int (8 bytes together),
+  # size_t, ptr, ptr, size_t, ptr, ptr, then the visible-signature tail:
+  # int (+ 4 pad), size_t, double[4], ptr, ptr, size_t.
+  def build_signing_options(options)
+    keep = []
+    cstr = lambda do |s|
+      return 0 if s.nil?
+
+      p = Fiddle::Pointer[s.to_s]
+      keep << p
+      p.to_i
+    end
+
+    reason   = cstr.call(options&.reason)
+    location = cstr.call(options&.location)
+    name     = cstr.call(options&.name)
+    pades    = options&.pades ? 1 : 0
+    cert     = (options&.certify || Certify::NONE).to_i
+    est      = (options&.container_size || 0).to_i
+
+    policy_oid = 0
+    policy_hash = 0
+    policy_hash_len = 0
+    policy_alg = 0
+    policy_uri = 0
+    if (pol = options&.policy)
+      policy_oid = cstr.call(pol.oid)
+      if pol.hash && !pol.hash.empty?
+        hp = Fiddle::Pointer[pol.hash]
+        keep << hp
+        policy_hash = hp.to_i
+        policy_hash_len = pol.hash.bytesize
+      end
+      policy_alg = cstr.call(pol.hash_algorithm_oid)
+      policy_uri = cstr.call(pol.uri)
+    end
+
+    visible  = options&.visible ? 1 : 0
+    vis_page = (options&.visible_page || 0).to_i
+    vis_rect = Array(options&.visible_rect || [0.0, 0.0, 0.0, 0.0]).map(&:to_f)[0, 4]
+    vis_rect += [0.0] * (4 - vis_rect.size)
+    vis_text = cstr.call(options&.visible_text)
+    vis_image = 0
+    vis_image_len = 0
+    if (img = options&.visible_image) && !img.empty?
+      ip = Fiddle::Pointer[img]
+      keep << ip
+      vis_image = ip.to_i
+      vis_image_len = img.bytesize
+    end
+
+    bytes = [reason, location, name].pack("J3") +
+            [pades, cert].pack("l2") +
+            [est, policy_oid, policy_hash, policy_hash_len, policy_alg, policy_uri].pack("J6") +
+            [visible].pack("l") + "\x00\x00\x00\x00".b +          # int visible + 4-byte pad
+            [vis_page].pack("J") + vis_rect.pack("d4") +
+            [vis_text, vis_image, vis_image_len].pack("J3")
+    [bytes, keep]
+  end
+
+  # Read an out-buffer (pointer-to-pointer +pp+, pointer-to-len +pn+) into a
+  # binary String, freeing the native buffer.
+  def read_buffer(pp, pn)
+    len = pn[0, Native::SIZEOF_SZ].unpack1("J")
+    return "".b if len.zero?
+
+    dptr = pp.ptr
+    bytes = dptr[0, len]
+    Native.call("pdf_buffer_free", dptr, len)
+    bytes
+  end
+
   def last_error
     p = Native.call("pdf_last_error_message")
     p.null? ? "unknown error" : p.to_s
@@ -194,13 +573,7 @@ module RustPdf
     pp = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
     pn = Fiddle::Pointer.malloc(Native::SIZEOF_SZ, Fiddle::RUBY_FREE)
     check(yield(pp, pn))
-    len = pn[0, Native::SIZEOF_SZ].unpack1("J")
-    return "".b if len.zero?
-
-    dptr = pp.ptr
-    bytes = dptr[0, len]
-    Native.call("pdf_buffer_free", dptr, len)
-    bytes
+    read_buffer(pp, pn)
   end
 
   # Run a producer { |out_int| status } and return the written int.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rustpdf
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: x86_64-linux
 authors:
 - rust-pdf
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-06-30 00:00:00.000000000 Z
 dependencies: []
 description: Idiomatic Ruby binding over the rust-pdf C ABI (libpdf_ffi) using the
   built-in Fiddle stdlib.