# How to Handle Encrypted and Password-Protected PDFs with LiteParse: A Complete Guide

> Easily handle encrypted and password-protected PDFs with LiteParse. Learn how LiteParse uses PDFium to authenticate and access your secured documents.

- Repository: [LlamaIndex/liteparse](https://github.com/run-llama/liteparse)
- Tags: how-to-guide
- Published: 2026-06-01

---

**LiteParse handles encrypted PDFs by passing an optional password string through the `LiteParseConfig` to PDFium's `FPDF_LoadDocument` API, returning `PasswordRequired` or `InvalidPassword` errors when authentication fails.**

Working with sensitive documents often requires parsing PDFs secured with encryption or password protection. The `run-llama/liteparse` repository provides first-class support for handling encrypted and password-protected PDFs with LiteParse across all language bindings and CLI interfaces. By leveraging the underlying PDFium library's native password capabilities, LiteParse exposes a unified configuration pattern that propagates authentication credentials from user input through to the document loading stage.

## Understanding the Password Flow Architecture

LiteParse implements a three-tier architecture for password handling that ensures consistency whether you use the Rust core directly or higher-level language bindings.

### Configuration Structure in config.rs

The password handling begins at the configuration layer. In [`crates/liteparse/src/config.rs`](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/config.rs), the `LiteParseConfig` struct defines `pub password: Option<String>` as a top-level optional field. When users supply a password via CLI flags, API parameters, or binding options, LiteParse stores it in this configuration object before any document processing begins.

### PDF Loading Pipeline

When the parser initiates document processing, the `extract::load_document_from_input` helper in [`crates/liteparse/src/parser.rs`](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/parser.rs) forwards `self.config.password.as_deref()` (converting the `Option<String>` to `Option<&str>`) downstream to the PDFium wrapper. This ensures the password travels with the document request without requiring separate authentication steps.

### PDFium Integration

The actual decryption occurs in [`crates/pdfium/src/library.rs`](https://github.com/run-llama/liteparse/blob/main/crates/pdfium/src/library.rs), where `pdfium::Pdfium::load_document` (and `load_document_from_bytes`) forwards the optional password pointer to the native C function `FPDF_LoadDocument`. If no password is supplied, LiteParse passes a null pointer to PDFium, triggering the standard encrypted PDF behavior.

## Error Handling for Authentication Failures

When encountering encrypted documents, LiteParse provides explicit error types defined in [`crates/pdfium/src/error.rs`](https://github.com/run-llama/liteparse/blob/main/crates/pdfium/src/error.rs). The system returns `PdfiumError::PasswordRequired` when attempting to open a password-protected PDF without supplying credentials, or `PdfiumError::InvalidPassword` when the provided password fails to decrypt the document. These errors propagate up to the caller, allowing applications to implement retry logic or user prompts rather than failing silently.

## Cross-Platform Implementation Examples

LiteParse exposes password functionality consistently across its Rust core, CLI tool, Node.js package, and Python bindings.

### Command Line Interface

The Rust binary in [`crates/liteparse/src/main.rs`](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/main.rs) exposes a `--password` flag that populates `LiteParseConfig` before processing:

```bash
liteparse input.pdf --output json --password "mySecret123"

```

### Node.js and TypeScript

The Node.js wrapper in [`packages/node/src/lib.ts`](https://github.com/run-llama/liteparse/blob/main/packages/node/src/lib.ts) accepts a password option in the constructor:

```typescript
import { LiteParse } from "liteparse";

const parser = new LiteParse({
  password: "mySecret123",
  output: "json"
});

const result = await parser.parseFile("encrypted.pdf");
console.log(result);

```

### Python API

The Python binding in [`packages/python/liteparse/parser.py`](https://github.com/run-llama/liteparse/blob/main/packages/python/liteparse/parser.py) maps the password argument to the underlying Rust configuration:

```python
from liteparse import LiteParse

parser = LiteParse(password="mySecret123", output="json")
result = parser.parse_file("encrypted.pdf")
print(result)

```

### Direct Rust API

For Rust developers using the core library directly:

```rust
use liteparse::{LiteParse, LiteParseConfig};

let cfg = LiteParseConfig {
    password: Some("mySecret123".to_string()),
    ..Default::default()
};

let parser = LiteParse::new(cfg);
let result = parser.parse_path("encrypted.pdf")?;

```

## Conversion and Rendering Support

Beyond basic parsing, LiteParse extends password support to document transformation workflows. The conversion utilities in [`crates/liteparse/src/conversion.rs`](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/conversion.rs) and rendering functions in [`crates/liteparse/src/render.rs`](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/render.rs) both accept the same `Option<&str>` password argument. This enables encrypted PDFs to undergo OCR processing, image rendering, or format conversion without requiring intermediate decryption steps.

## Summary

LiteParse provides comprehensive support for password-protected PDFs by leveraging PDFium's native encryption handling:

- **Configuration-driven**: The `LiteParseConfig` struct stores passwords as `Option<String>` for optional security
- **PDFium integration**: Direct forwarding to `FPDF_LoadDocument` ensures reliable decryption
- **Explicit errors**: `PasswordRequired` and `InvalidPassword` errors enable proper error handling
- **Universal support**: Available in CLI, Node.js, Python, and Rust APIs with identical behavior
- **Extended workflows**: Passwords propagate through rendering and conversion pipelines

## Frequently Asked Questions

### What error does LiteParse return when a PDF password is incorrect?

LiteParse returns `PdfiumError::InvalidPassword` when the supplied password fails to decrypt the document, and `PdfiumError::PasswordRequired` when attempting to open an encrypted PDF without providing any password. These errors are defined in [`crates/pdfium/src/error.rs`](https://github.com/run-llama/liteparse/blob/main/crates/pdfium/src/error.rs) and propagate through all language bindings.

### Can I use LiteParse to render encrypted PDFs to images?

Yes. The rendering functions in [`crates/liteparse/src/render.rs`](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/render.rs) accept the same password argument as the parsing pipeline. Pass the password through your `LiteParseConfig` when initializing the parser, and LiteParse will decrypt the PDF before rendering pages to images.

### Is password-protected PDF support available in the WASM build?

Yes. The WASM wrapper exposes the same password configuration options as the Node.js and Python bindings. The password field in the configuration object maps to the underlying Rust `LiteParseConfig`, ensuring consistent behavior across WebAssembly, native binaries, and language-specific packages.

### How does LiteParse handle PDFs with owner passwords versus user passwords?

LiteParse delegates password validation entirely to PDFium's `FPDF_LoadDocument` implementation. Supply the appropriate password string through the configuration, and PDFium automatically handles the cryptographic verification regardless of whether the document uses owner passwords, user passwords, or both.