C# / .NET

Last updated: 2026-06-29

The RustPdf NuGet package wraps the rust-pdf C core with idiomatic, chainable classes over source-generated P/Invoke (LibraryImport). It covers the whole product surface: vector graphics, embedded/subset fonts & Unicode text, paragraphs, images, PDF/A (1b–3a + A-4/4e/4f), tagged/accessible output, attachments, AcroForm fields, manipulation, text extraction, encryption and digital signatures. The native library ships inside the package for every runtime, with no native build.

Installation

Install from NuGet. The native library (libpdf_ffi) is bundled as a per-runtime asset (runtimes/<rid>/native/ for osx-arm64, linux-x64, linux-arm64 and win-x64): .NET resolves the one matching your OS/architecture automatically, so there's nothing to compile.

dotnet add package RustPdf

Targets net8.0 (works on .NET 8+). Verify it loaded:

using RustPdf;
Console.WriteLine(Pdf.Version());   // native library version

Quick start

A one-page document with a filled rectangle, saved to disk:

using RustPdf;

using var doc = new Document();          // A4 by default
doc.AddPage();
doc.SetFillRgb(0.86, 0.20, 0.18);
doc.Rect(72, 640, 200, 120);             // x, y, width, height (points)
doc.Fill();
doc.Save("out.pdf");

Most methods return the document, so calls chain:

using var doc = new Document();
int font = doc.AddFontFile("Roboto-Regular.ttf");
doc.AddPage()
   .SetFillRgb(0.1, 0.1, 0.12)
   .Rect(0, 800, 595, 42).Fill()
   .ShowText(font, 24, 72, 740, "Olá, açúcar — café");
byte[] data = doc.ToBytes();             // a byte[] instead of a file

Licensing & activation

Basic generation (everything above) is always free. The corporate features (PDF/A, digital signatures/PAdES, encryption, accessibility) require an active license token. Without one, those calls throw PdfException and produce no output.

Activation needs no rebuild. Easiest is an environment variable, auto-activated the first time a corporate feature is used:

export RUSTPDF_LICENSE="010f0000…"           # the token we email you
# or point at a file:
export RUSTPDF_LICENSE_FILE=/etc/rustpdf/license.txt

Or activate explicitly in code:

using RustPdf;
Pdf.ActivateLicense(token);   // throws PdfException if forged / expired / malformed

Coordinate system

• Units are points (1 pt = 1/72 inch). A4 is 595 × 842, US Letter 612 × 792.
• The origin (0, 0) is the bottom-left corner; y grows upward.
• For text, (x, y) is the baseline of the first glyph by default; stamping calls accept an explicit VerticalAnchor (see stamping and the interactive positioning guide).
• Drawing/text always targets the most recently added page.

Threading & concurrency

Every native call is synchronous and the core is Send but not Sync: a single handle must never be touched by two threads at once.

• Documents are independent. Each Document/EditableDoc shares no state, so they're safe to build in parallel Tasks or threads, one handle per task.
• Don't share a live handle across threads; give each its own.
• Errors are per-thread. The native last-error is thread-local, so a failure on one thread never clobbers another's, and PdfException surfaces on the calling side.
• License is process-global. Pdf.ActivateLicense (or the env var) applies to every thread; activate once at startup.

// one document per task — no shared handle
var jobs = Enumerable.Range(0, 8).Select(i => Task.Run(() =>
{
    using var doc = new Document();
    doc.AddPage().SetFillRgb(0.1, 0.1, 0.12).Rect(72, 700, 200, 80).Fill();
    return doc.ToBytes();
}));
byte[][] pdfs = await Task.WhenAll(jobs);

Authoring: create & save

Creates an empty document (A4 default page size). Wrap in using (or call Dispose()) to free the native handle.

Pages & vector graphics

Graphics state and path operators mirror PDF's content-stream model. Colors are RGB in 0.0–1.0.

using var doc = new Document();
doc.AddPage();
doc.SetStrokeRgb(0.10, 0.45, 0.90).SetLineWidth(3);
doc.Rect(72, 600, 300, 160).Stroke();
doc.SetFillRgb(0.95, 0.77, 0.06);
doc.Rect(120, 640, 120, 80).Fill();
doc.Save("shapes.pdf");

Fonts & text

Fonts are embedded and subsetted, with HarfBuzz-quality shaping, kerning and full Unicode (Type0/CIDFontType2 with ToUnicode, so text extracts and copies correctly, provided the embedded font covers those characters). Register a font once, then reference it by its integer id.

headingLevel (1–6) tags the run as H1–H6 in an accessible document (see Accessibility); leave it as 0 for ordinary text.

using var doc = new Document();
int regular = doc.AddFontFile("Roboto-Regular.ttf");
// …or from bytes you already have in memory:
// int regular = doc.AddFont(File.ReadAllBytes("Roboto-Regular.ttf"));

doc.AddPage();
doc.ShowText(regular, 28, 72, 760, "Invoice #1024");
doc.ShowText(regular, 12, 72, 720, "日本語 · Ελληνικά · العربية");
doc.Save("text.pdf");

Paragraphs

The paragraph layer wraps, aligns and justifies text inside a fixed width (greedy line breaking using shaped glyph widths).

using RustPdf;

string intro =
    "A long paragraph that wraps to the given width and is justified " +
    "automatically; extra space is distributed between words.";

using var doc = new Document();
int f = doc.AddFontFile("Roboto-Regular.ttf");
doc.AddPage();
doc.Paragraph(f, 12, 72, 700, 451, intro, Align.Justify);
doc.Save("paragraph.pdf");

See the Align enum for the alignment options.

Images

JPEGs are embedded verbatim (DCTDecode, no re-encode). PNGs are decoded and re-encoded (FlateDecode); alpha becomes an /SMask, palette becomes an Indexed color space. Register an image once, draw it many times.

using var doc = new Document();
int logo = doc.AddImageFile("logo.png");
doc.AddPage();
doc.DrawImage(logo, 72, 680, 160, 90);
doc.Save("with_image.pdf");

PDF/A licensed

Produce archival-grade output. Pdfa() defaults to A-2b; pass a PdfaLevel for a specific level. An embedded sRGB ICC profile, output intent, XMP metadata and document /ID are added automatically; A-1b also forces PDF 1.4 and emits a /CIDSet, and A-4 (ISO 19005-4) is based on PDF 2.0.

using RustPdf;

using var doc = new Document();
doc.Pdfa(PdfaLevel.A2b).SetInfo(title: "Q3 Report", author: "Acme Inc.");
int f = doc.AddFontFile("Roboto-Regular.ttf");
doc.AddPage();
doc.ShowText(f, 20, 72, 760, "Archival report");
doc.Save("report_pdfa.pdf");     // throws PdfException without a license granting PDF/A

Accessibility (Tagged PDF / PDF/UA) licensed

Tagged() builds a logical structure tree (PDF/UA-1). Combine with Pdfa(PdfaLevel.A2a) for archival and accessible output. Use headingLevel on ShowText for H1–H6, and Figure(..., alt) for described images.

using RustPdf;

using var doc = new Document();
doc.Pdfa(PdfaLevel.A2a).Tagged().SetInfo(title: "Accessible report");
int f = doc.AddFontFile("Roboto-Regular.ttf");
doc.AddPage();
doc.ShowText(f, 26, 72, 760, "Annual report", headingLevel: 1);   // H1
doc.ShowText(f, 14, 72, 720, "Overview", headingLevel: 2);         // H2
doc.ShowText(f, 11, 72, 690, "Body paragraph of the section…");
int chart = doc.AddImageFile("chart.png");
doc.Figure(chart, 72, 520, 300, 150, "Revenue grew 18% year over year");
doc.Save("accessible.pdf");

Attachments (PDF/A-3) licensed

PDF/A-3 allows embedding arbitrary source files (e.g. the XML behind an e-invoice). Each attachment carries a MIME type and an AFRelationship.

using RustPdf;

byte[] xml = File.ReadAllBytes("invoice.xml");
using var doc = new Document();
doc.Pdfa(PdfaLevel.A3b).SetInfo(title: "E-invoice 1024");
int f = doc.AddFontFile("Roboto-Regular.ttf");
doc.AddPage();
doc.ShowText(f, 18, 72, 760, "Invoice 1024");
doc.AttachFile("invoice.xml", "text/xml", xml,
               AFRelationship.Source, "Structured invoice data");
doc.Save("einvoice.pdf");

ZUGFeRD / Factur-X e-invoices licensed

Turn the document into a ZUGFeRD / Factur-X electronic invoice: the embedded XML (the Cross-Industry Invoice) is attached as factur-x.xml, the file is marked PDF/A-3, and the Factur-X identification is written into the XMP metadata. The visible PDF is the human-readable invoice; the embedded XML is its machine-readable twin. Validates as PDF/A-3 + Factur-X under veraPDF.

using RustPdf;

byte[] xml = File.ReadAllBytes("factur-x.xml");   // your Cross-Industry Invoice XML
using var doc = new Document();
doc.SetInfo(title: "Invoice INV-2026-001");
int f = doc.AddFontFile("Roboto-Regular.ttf");
doc.AddPage();
doc.ShowText(f, 18, 72, 760, "Invoice INV-2026-001");
doc.Facturx(xml, FacturxProfile.En16931);
doc.Save("einvoice.pdf");        // PDF/A-3 + Factur-X; needs a PDF/A license

See the FacturxProfile enum for the conformance levels (Minimum to Extended).

AcroForm fields

Build interactive forms with generated appearance streams (no NeedAppearances). Rectangles are (x0, y0, x1, y1) tuples; page is a 0-based page index. Dotted names ("a.b.c") create hierarchical fields.

using var doc = new Document();
doc.AddPage();
doc.TextField("applicant.name", 0, (72, 700, 320, 720));
doc.Checkbox("agree", 0, (72, 660, 88, 676), false);
doc.Dropdown("plan", 0, (72, 620, 240, 640),
             new[] { "Starter", "Pro", "Enterprise" }, selected: 1);
doc.RadioGroup("billing", 0, new[]
{
    ((72.0, 580.0, 88.0, 596.0), "monthly"),
    ((140.0, 580.0, 156.0, 596.0), "annual"),
}, selected: 1);
doc.Save("form.pdf");

Fill and flatten fields later with EditableDoc.

Hyperlinks free

Add clickable link rectangles to the current page: a web link opens a URL; an internal link jumps to another page (optionally scrolling so a given top y-coordinate sits at the top of the view).

using var doc = new Document();
int f = doc.AddFontFile("Roboto-Regular.ttf");
doc.AddPage();
doc.ShowText(f, 14, 72, 760, "Visit rustpdf.dev (see page 2)");
doc.LinkUri((72, 756, 320, 776), "https://rustpdf.dev/");   // web link
doc.LinkToPage((330, 756, 430, 776), 1, top: 800);         // jump to page 2
doc.AddPage();
doc.Save("links.pdf");

Rectangles are (x0, y0, x1, y1) tuples in points; pageIndex is 0-based.

Bookmarks / outline free

Build a navigable document outline. A Bookmark has a title, a target page and an optional top; nest children with .Child(...). A document with bookmarks opens with the outline pane shown.

using RustPdf;

using var doc = new Document();
int f = doc.AddFontFile("Roboto-Regular.ttf");
for (int i = 0; i < 3; i++)
    doc.AddPage();
doc.AddBookmark(
    new Bookmark("Chapter 1", 0, top: 820)
        .Child(new Bookmark("Section 1.1", 1))
        .Child(new Bookmark("Section 1.2", 2)));
doc.AddBookmark(new Bookmark("Chapter 2", 2));
doc.Save("outline.pdf");

Metadata

Sets the document information dictionary (and, for PDF/A, the matching XMP). Pass only the named arguments you need.

doc.SetInfo(title: "Q3 Report", author: "Acme Inc.",
            subject: "Quarterly results", keywords: "finance, q3");

Manipulation: load an existing PDF

EditableDoc parses an existing document (classic & xref streams, object streams, all standard filters, RC4/AES decryption) into an editable model. Pages are a flat list; the page tree is rebuilt on output.

using RustPdf;

using (var ed = EditableDoc.LoadFile("in.pdf"))
    Console.WriteLine(ed.PageCount);

// encrypted input:
using var sec = EditableDoc.LoadFile("secured.pdf", "user-or-owner-pw");
sec.Save("plain.pdf");

Pages: merge, split, reorder, rotate

using var a = EditableDoc.LoadFile("a.pdf");
using (var b = EditableDoc.LoadFile("b.pdf"))
    a.Merge(b);                        // a now has a's pages followed by b's
a.RotatePage(0, 90);
a.ReorderPages(Enumerable.Range(0, a.PageCount).Reverse().ToList());
a.Save("merged.pdf");

using var subset = a.ExtractPages(new[] { 0, 2 });   // pages 1 and 3
subset.Save("subset.pdf");

Metadata, overlay & form fill

using var ed = EditableDoc.LoadFile("form.pdf");
ed.SetInfo("Title", "Filled form");
bool found = ed.FillTextField("applicant.name", "Jane Doe");
Console.WriteLine($"filled: {found} | title: {ed.GetInfo("Title")}");
ed.Save("filled.pdf");

Form fill & flatten free

Fill the fields of an existing AcroForm and (optionally) flatten them: filling generates a fresh appearance stream (no NeedAppearances), and flattening bakes every widget's appearance into the page content and removes the interactive form entirely.

using RustPdf;

using var ed = EditableDoc.LoadFile("form.pdf");
Console.WriteLine(string.Join(", ", ed.FieldNames()));   // applicant.name, agree, plan, ...
ed.FillTextField("applicant.name", "Jane Doe");
ed.SetCheckbox("agree", true);
ed.SetRadio("billing", "annual");
ed.SetChoice("plan", "Pro");
ed.FlattenForms();                  // optional: make it non-editable
ed.Save("filled.pdf");

Watermarks free

Stamp a diagonal text watermark or a centered image watermark across every page, drawn semi-transparently over the existing content. Text uses the standard Helvetica font, so keep it to WinAnsi (Latin-1) for stamps like "CONFIDENTIAL".

Set opaqueBackground: true to draw an opaque box behind the text, a white-out / redaction-style banner instead of a transparent overlay. WatermarkImageFile takes a rotationDeg to rotate the stamped image.

using var ed = EditableDoc.LoadFile("report.pdf");
ed.WatermarkText("CONFIDENTIAL", color: (0.7, 0.1, 0.1),
                 opacity: 0.25, rotationDeg: 45, opaqueBackground: false);
ed.WatermarkImageFile("stamp.png", 200, 120, opacity: 0.30, rotationDeg: 30);
ed.Save("stamped.pdf");

Positioned drawing free

Stamp a single page in place: fill a rectangle and/or drop a line of text at exact coordinates. Coordinates are in the page's visible space (origin lower-left, y up), so content lands where a viewer sees it regardless of the page's /Rotate; rotationDeg rotates the text counter-clockwise about its anchor. Text uses the standard Helvetica font (keep it WinAnsi / Latin-1). Both return whether the page existed.

A typical use is masking a spot with an opaque white box, then writing a value over it. MaskedText does exactly that in one call: it fills the box [x, y, x+width, y+height] in bgColor (default opaque white), then writes the text in textColor horizontally aligned per align and vertically centered in the box, so you never hand-compute the baseline. PlaceText's align shifts the start point along the baseline by the text width for Center or Right. DrawImage takes raw JPEG/PNG image bytes and places the image with its lower-left corner at (x, y) scaled to width × height points.

byte[] data = File.ReadAllBytes("invoice.pdf");
PageGeometry g = Pdf.MeasurePage(data, 0);          // read the page geometry first
using var ed = EditableDoc.Load(data);
ed.FillRect(0, 400, g.Height - 60, 120, 18);        // mask: default opaque white
ed.PlaceText(0, 404, g.Height - 56, "PAID", size: 12, color: (0.0, 0.5, 0.0));
// or mask + stamp a right-aligned value in one call:
ed.MaskedText(0, 400, g.Height - 60, 120, 18, "R$ 1.250,00", size: 12, align: Align.Right);
ed.DrawImage(0, File.ReadAllBytes("logo.png"), 404, g.Height - 120, 120, 48);
ed.Save("stamped.pdf");

Stamping: fonts, anchors & paragraphs free

Everything below extends the positioned-drawing primitives with production-grade control: real embedded fonts, explicit vertical anchors, word-wrapping paragraphs and a per-document coordinate space. Try every mode live in the interactive positioning guide.

Embedded stamping fonts

Register a TrueType/OpenType font on the EditableDoc and pass its fontId to PlaceText/MaskedText/PlaceParagraph. The font is embedded as a subset; text may be arbitrary Unicode. fontId: -1 keeps the built-in Helvetica (WinAnsi).

using var ed = EditableDoc.LoadFile("contract.pdf");
int times = ed.AddFontFile("/Library/Fonts/Times New Roman.ttf");
ed.PlaceText(0, 72, 96, "Assinado por Maria — ação registrada", size: 11, fontId: times);

Vertical anchors: what y means

VerticalAnchor.Baseline (default) anchors the text baseline. Top/Bottom anchor the geometric ascender/descender lines. LineTop/LineBottom anchor the layout line box (OS/2 win metrics + half-leading), the drop-in pair when matching output from legacy layout engines's fixed-position layout. Rotation always pivots at the anchor (x, y); anchor offsets rotate with the text.

// y is the BOTTOM of the line box, like legacy fixed-position layout:
ed.PlaceText(0, 72, 140, "Total: R$ 1.250,00", size: 12, fontId: times,
             anchor: VerticalAnchor.LineBottom);

MaskedText: box alignment & padding

valign places the line inside the box: Top (top line-alignment in rectangle-based text APIs), Middle (default, cap-height centered) or Bottom. padding is the horizontal inset for Left/Right alignment; null keeps the default min(0.15 × size, width / 4), 0 starts flush at the box edge.

ed.MaskedText(0, 400, 700, 120, 18, "R$ 1.250,00", size: 12,
              valign: VerticalAlign.Top, padding: 0);

Paragraphs: wrapping, bottom-pin, ceiling

Breaks text greedily by word inside width (\n forces a line break). anchor: Top (default) hangs the block from y. Bottom/LineBottom bottom-pin it: the block's bottom rests on y and grows upward by its real content height; maxHeight is a ceiling that cuts overflowing lines from the top (the last lines stay pinned) and never inflates the position. PlaceParagraphMeasured also returns the consumed height, so blocks stack without re-measuring. The Line* anchors use the layout line box for the first line and the legacy multiplied-leading advance between lines.

var (lines, height) = ed.PlaceParagraphMeasured(0, 72, 96, 220,
    "Digitally signed by Maria Silva\nReason: Approval\n2026-07-02 14:31 UTC",
    size: 10, fontId: times, maxHeight: 64, anchor: VerticalAnchor.LineBottom);

Coordinate space on rotated scans: StampSpace

Visible (default): coordinates in the page as displayed; the library compensates /Rotate, so a rotationDeg: 0 stamp reads upright on screen. Media: the raw PDF user space (the semantics of legacy engines that draw in raw coordinates), nothing composed on top of your math. Applies to FillRect, PlaceText, MaskedText, PlaceParagraph and DrawImage; watermarks and redaction are unaffected.

ed.StampSpace = StampSpace.Media;   // porting coordinates computed for legacy PDF libraries
ed.PlaceText(0, x, y, "APPROVED", rotationDeg: 90, anchor: VerticalAnchor.LineBottom);

Rotated images: ImageAnchor

Corner (default) keeps (x, y) as the image's own lower-left corner; the image sweeps around it when rotated. BoundingBox lands the rotated image's bounding box at (x, y) (bounding-box layout: a 90° image occupies [x, x+height] × [y, y+width]).

ed.DrawImage(0, File.ReadAllBytes("stamp.png"), 404, 96, 120, 48,
             rotationDeg: 90, anchor: ImageAnchor.BoundingBox);

Redaction licensed

True redaction: every shown glyph whose box intersects a rectangle is removed from the content stream (surviving glyphs keep their exact positions), images/XObjects overlapping a rect are dropped with their data, and intersecting annotations are deleted; only then are opaque black boxes painted. The call throws when a page cannot be safely rewritten (inline BI images, undecodable streams) instead of painting over still-present data.

using var ed = EditableDoc.LoadFile("statement.pdf");
// rects = list of (x0, y0, x1, y1) tuples on that page
ed.Redact(0, new[]
{
    (60.0, 590.0, 400.0, 620.0),
    (60.0, 540.0, 400.0, 570.0),
});
ed.Save("redacted.pdf");     // throws PdfException without a license granting redaction

Convert to PDF/A licensed

Convert an existing PDF to archival PDF/A (a basic profile: A-1b, A-2b or A-3b). An sRGB output intent, PDF/A XMP metadata (synced with /Info) and a document /ID are added. Fails if any font is not embedded (PDF/A requires every font embedded) or a level-A profile is requested.

using RustPdf;

using var ed = EditableDoc.LoadFile("in.pdf");
ed.ConvertToPdfa(PdfaLevel.A2b);    // throws PdfException if fonts aren't embedded
ed.Save("archival.pdf");            // veraPDF: PDF/A-2b compliant

Optimize & compact

using var ed = EditableDoc.LoadFile("big.pdf");
ed.Optimize().Compact(true);
ed.Save("small.pdf");

Encryption licensed

Apply standard-handler encryption at output. AES-256 (V5/R6) uses OS-CSPRNG keys/IVs.

using RustPdf;

using var ed = EditableDoc.LoadFile("in.pdf");
ed.Encrypt(user: "", owner: "owner-secret",
           method: Encryption.Aes256, readOnly: true);
ed.Save("secured.pdf");          // throws PdfException without an Encryption license

See the Encryption enum for RC4 / AES-128 / AES-256.

Normalize & downgrade free

Turn a PDF/A or PDF 2.0 file back into a plain PDF: SetVersion sets the header version, StripPdfa removes the PDF/A conformance markers (/OutputIntents, the XMP pdfaid entry and any /Version override), and Normalize does both at once.

using var ed = EditableDoc.LoadFile("archival.pdf");
ed.Normalize(2);                 // strip PDF/A + set version 1.7
// or step by step:
// ed.StripPdfa().SetVersion(2);
ed.Save("plain.pdf");

Output & incremental update

byte[] original = File.ReadAllBytes("in.pdf");
using var ed = EditableDoc.Load(original);
ed.SetInfo("Subject", "reviewed");
byte[] incremental = ed.ToBytesIncremental(original);   // original bytes preserved verbatim
File.WriteAllBytes("reviewed.pdf", incremental);

Digital signatures licensed

Sign a PDF with a PKCS#7 detached signature via an incremental update (the original bytes are preserved). Keys and certificates are passed as DER byte[]. pades: true switches to PAdES-B-B.

using RustPdf;

byte[] pdf     = File.ReadAllBytes("contract.pdf");
byte[] keyDer  = File.ReadAllBytes("signing-key.pkcs8.der");   // PKCS#8 private key (DER)
byte[] certDer = File.ReadAllBytes("signing-cert.der");        // X.509 certificate (DER)

byte[] signed = Pdf.Sign(pdf, keyDer, certDer,
    reason: "Approved", location: "New York",
    name: "Jane Doe", pades: true);
File.WriteAllBytes("contract.signed.pdf", signed);
// Verify in a shell: pdfsig contract.signed.pdf  →  "Signature is Valid."

Deferred / HSM signing licensed

Sign without ever handing the library a private key. When the key lives in an HSM, a cloud KMS, a smartcard or a PKI token (any PKI: eIDAS, AATL, a national CA), you supply the raw RSA signature and the library builds and embeds the CMS / PKCS#7 container. There are two flavours: a synchronous remote signer callback, and a two-phase begin / complete flow for asynchronous or out-of-band signing.

Model A: remote signer callback

The library assembles the signed attributes and calls back for the raw RSA PKCS#1 v1.5 signature over their SHA-256 digest. The certificate is passed as DER; the key stays inside your HSM. Provide a RemoteSign delegate, or an IRemoteSigner for the interface-shaped overload.

using RustPdf;

byte[] pdf     = File.ReadAllBytes("contract.pdf");
byte[] certDer = File.ReadAllBytes("signer-cert.der");   // X.509 (DER); key stays remote

byte[] signed = Pdf.SignWith(pdf, certDer,
    signHash: dataToSign => hsm.SignRsaPkcs1Sha256(dataToSign),   // your HSM / KMS / token
    chain: new[] { intermediateDer },
    options: new SigningOptions { Reason = "Approved", Pades = true });

File.WriteAllBytes("contract.signed.pdf", signed);

Model B: two-phase begin / complete

For an asynchronous HSM or a detached workflow, phase 1 prepares the PDF with a placeholder and returns the exact bytes the signature covers; you sign the digest out of band and build the CMS container; phase 2 embeds it.

A SigningSession exposes Document (the prepared PDF), Bytes (the bytes covered by the signature), Hash (their SHA-256, the value an HSM signs) and Complete(container), which embeds a finished DER CMS / PKCS#7 container and returns the final signed PDF.

SigningSession session = Pdf.BeginSigning(pdf,
    new SigningOptions { Name = "Jane Doe", ContainerSize = 16384 });

byte[] cmsDer = await BuildCmsWithRemoteSignatureAsync(session.Hash);   // sign the digest remotely

byte[] signed = session.Complete(cmsDer);
// equivalently: Pdf.CompleteSignature(session.Document, cmsDer)
File.WriteAllBytes("contract.signed.pdf", signed);

Inspect existing signature fields

Before signing, list the signature fields already present (a classic pre-sign signature-field inventory). An empty list means the document is unsigned.

foreach (SignatureField f in Pdf.ListSignatures(pdf))
    Console.WriteLine($"{f.Name} signed: {f.Signed}");

SigningOptions

Both models accept an optional SigningOptions:

A visible signature can carry an embedded image: set Visible = true, give it a rectangle, and pass the PNG/JPEG bytes in VisibleImage (drawn aspect-fit behind VisibleText).

var opts = new SigningOptions
{
    Name = "Jane Doe",
    Visible = true,
    VisiblePage = 0,
    VisibleRect = new[] { 72.0, 96.0, 272.0, 156.0 },
    VisibleText = "Signed by Jane Doe\n2026-06-30",
    VisibleImage = File.ReadAllBytes("signature.png"),
};

Certify

SignaturePolicy

A PAdES-EPES signature-policy identifier. Oid is the policy OID (dotted-decimal); Hash is the policy document hash (byte[]); HashAlgorithmOid is the hash algorithm OID (null means SHA-256); Uri is an optional SPURI qualifier pointing to where the policy can be retrieved.

Timestamp & DSS (PAdES LTV) licensed

Build long-term-validation signatures offline. Pdf.AddDss appends a Document Security Store (/DSS with certs/CRLs, PAdES-B-LT); Pdf.Timestamp appends an RFC 3161 document timestamp (/DocTimeStamp, PAdES-B-LTA).

byte[] signed = File.ReadAllBytes("contract.signed.pdf");

// B-LT: embed validation material (caller supplies DER certs/CRLs)
byte[] lt = Pdf.AddDss(signed, new[] { certDer }, new[] { crlDer });

// B-LTA: add a document timestamp signed by a TSA key/cert
byte[] lta = Pdf.Timestamp(lt, tsaKeyDer, tsaCertDer);
File.WriteAllBytes("contract.lta.pdf", lta);

Network timestamp (AD-RT)

To stamp from a real network RFC 3161 TSA, the transport is left to you: Pdf.BeginTimestamp prepares the PDF and returns the bytes to timestamp, Pdf.TimestampRequest builds the request (DER), you POST it to the TSA, Pdf.TimestampTokenFromResponse extracts the token, then Pdf.CompleteSignature embeds it. Free public TSAs work (FreeTSA https://freetsa.org/tsr, DigiCert http://timestamp.digicert.com).

using System.Security.Cryptography;

byte[] pdf = File.ReadAllBytes("contract.signed.pdf");

var (document, toStamp) = Pdf.BeginTimestamp(pdf);
byte[] imprint = SHA256.HashData(toStamp);
byte[] request = Pdf.TimestampRequest(imprint);

// POST the DER request to the TSA (you own the HTTP call):
using var http = new HttpClient();
using var body = new ByteArrayContent(request);
body.Headers.ContentType = new("application/timestamp-query");
byte[] response = await (await http.PostAsync("https://freetsa.org/tsr", body))
    .Content.ReadAsByteArrayAsync();

byte[] token  = Pdf.TimestampTokenFromResponse(response);
byte[] lta    = Pdf.CompleteSignature(document, token);
File.WriteAllBytes("contract.lta.pdf", lta);

Validate signatures licensed

Validate every signature in a PDF: each report recomputes the /ByteRange digest, parses the CMS, and checks that the cryptographic signature is valid, that the messageDigest matches the covered bytes, and whether the signature covers the whole document.

Each SignatureInfo has FieldName, SubFilter, Signer, CoversWholeDocument, DigestValid, SignatureValid, IsValid and ByteRange. When the signer certificate parses, it also carries the certificate detail: Issuer, SerialNumber, ValidFrom, ValidTo, Algorithm (e.g. SHA256withRSA), SigningTime, CertCount and HasTimestamp. The string fields may be null when absent. An empty list means the document is unsigned. Signature validation is a licensed feature: this call requires an active license (signatures) even when the document is unsigned, so it is not available on the free tier.

using RustPdf;

byte[] data = File.ReadAllBytes("contract.signed.pdf");
foreach (SignatureInfo sig in Pdf.VerifySignatures(data))
{
    Console.WriteLine($"{sig.Signer} valid: {sig.IsValid} " +
                      $"covers whole doc: {sig.CoversWholeDocument}");
    Console.WriteLine($"  issuer:    {sig.Issuer}");
    Console.WriteLine($"  serial:    {sig.SerialNumber}");
    Console.WriteLine($"  valid:     {sig.ValidFrom} … {sig.ValidTo}");
    Console.WriteLine($"  algorithm: {sig.Algorithm}");
    Console.WriteLine($"  signed at: {sig.SigningTime}");
    Console.WriteLine($"  certs:     {sig.CertCount}, timestamp: {sig.HasTimestamp}");
}

Positional text search free

Find every occurrence of a query string and get back each match's bounding box in PDF points (origin lower-left). Useful for highlighting, redaction targeting, or locating where to stamp. Search is case-insensitive by default; pass caseSensitive: true to match case. See the searching a PDF concept page for background.

Each TextHit has Page (0-based), Text, and the box X, Y, Width, Height. An empty list means no match.

using RustPdf;

byte[] data = File.ReadAllBytes("report.pdf");
foreach (TextHit hit in Pdf.FindText(data, "Total"))
    Console.WriteLine(
        $"page {hit.Page}: \"{hit.Text}\" at " +
        $"({hit.X:0.#}, {hit.Y:0.#}) {hit.Width:0.#}×{hit.Height:0.#} pt");

Text & image extraction

Extract a document's text, mapping shown glyph codes back to Unicode through each font's ToUnicode map, with space/line inference. Raster images can be pulled out too: JPEGs are written verbatim as .jpg, everything else as .png. The output directory is created automatically if it does not already exist.

byte[] data = File.ReadAllBytes("report.pdf");
Console.WriteLine(Pdf.ExtractText(data));

int n = Pdf.ExtractImagesToDir(data, "out_images/");   // returns how many were written
Console.WriteLine($"wrote {n} image(s)");

Page geometry free

Read each page's size, rotation and boxes without modifying the file. Width/Height ignore /Rotate; RotatedWidth/RotatedHeight are the dimensions a viewer shows. Sizes are in PDF points (72 per inch).

Each PageGeometry has Page (0-based), Width, Height, Rotation (0/90/180/270), RotatedWidth, RotatedHeight, and the MediaBox/CropBox as a PdfRect (X0, Y0, X1, Y1 with Width/Height helpers).

byte[] data = File.ReadAllBytes("report.pdf");
PageGeometry g = Pdf.MeasurePage(data, 0);
Console.WriteLine($"page {g.Page}: {g.Width:0.#}×{g.Height:0.#} pt, rotate {g.Rotation}");
Console.WriteLine($"visible: {g.RotatedWidth:0.#}×{g.RotatedHeight:0.#} pt");

Document inspection free

Get a non-mutating overview of a PDF, its version, PDF/A level (if any) and encryption posture, without decrypting or rewriting it. Handy for triage before deciding how to process a file.

PdfOverview carries Version (e.g. "1.7"), PdfaLevel (e.g. "2b", or null if not PDF/A), Encrypted, Encryption ("None", "RC4", "AES-128" or "AES-256"), RequiresPassword, and PageCount.

byte[] data = File.ReadAllBytes("report.pdf");
PdfOverview o = Pdf.Inspect(data);
Console.WriteLine($"PDF {o.Version}, {o.PageCount} page(s)");
Console.WriteLine($"PDF/A: {o.PdfaLevel ?? "no"}, encryption: {o.Encryption}");
if (o.RequiresPassword) Console.WriteLine("needs a password to open");

Render a page to an image licensed

Rasterize a page to a PNG image. A native Rust renderer (built on tiny-skia, with no headless browser) interprets the page content stream, painting real glyph outlines, vector graphics, images, color and transparency. Page rendering is a Pro feature; page_count is free.

byte[] data = File.ReadAllBytes("report.pdf");
Console.WriteLine($"{Pdf.PageCount(data)} page(s)");
byte[] png = Pdf.RenderPageToPng(data, pageIndex: 0, dpi: 150.0);
File.WriteAllBytes("page1.png", png);

Enums

PdfaLevel

Align

VerticalAnchor

VerticalAlign

StampSpace

ImageAnchor

AFRelationship

Encryption

FacturxProfile

Error handling

Every failing native call throws PdfException carrying the Status (PdfStatus) code and the library's last-error message. License failures (missing/expired/forged token, or a feature the token doesn't grant) surface here too. Token activation failures carry the dedicated license status code (12); a gated build, sign or encrypt call instead reports that operation’s own status (for example Serialize = 4 or Sign = 10) with the same “requires a valid license” message.

using RustPdf;

try
{
    using var doc = new Document();
    doc.Pdfa().SetInfo(title: "x");
    doc.AddPage();
    doc.Save("out.pdf");
}
catch (PdfException e)
{
    Console.Error.WriteLine($"failed: {e.Status} {e.Message}");
    // e.g. PdfStatus=4 (Serialize): feature 'pdfa' requires a valid license
}

Utilities