rnp-rs

Idiomatic Rust binding to the RNP OpenPGP (RFC 9580) C library.

RNP is the C++ OpenPGP implementation that powers Mozilla Thunderbird. This crate provides a thin, safe Rust wrapper over its public C FFI (declared in include/rnp/rnp.h).

Status

The crate wraps ~250 of librnp's ~309 public functions across all major OpenPGP concerns: signing, verification, encryption, decryption, key generation, keyring management, ASCII armor, packet dumps, security profile, and feature queries. PQC and crypto-refresh (RFC 9580 v6) support is feature-gated. MSRV is Rust 1.88 (let-chains in build.rs).

Cargo features

Quick start

use rnp::{Algorithm, Context, Hash, KeyBuilder, KeyUsage};

let ctx = Context::new()?;
let key = KeyBuilder::new(Algorithm::Rsa)
    .bits(2048)
    .userid("alice <alice@example.com>")
    .hash(Hash::Sha256)
    .add_usage(KeyUsage::Sign)
    .add_usage(KeyUsage::Certify)
    .build(&ctx)?;

let message = b"hello, world";
let signed = rnp::sign(&ctx, message, &key)?;
let result = rnp::verify(&ctx, &signed)?;
assert!(result.any_valid()?);
# Ok::<(), rnp::Error>(())

See examples/ for end-to-end demos of sign/verify, encrypt/decrypt, key generation, and multi-signer signatures.

Feature coverage

Each subsection below lists the Rust surface and the librnp C functions it wraps.

Context, password provider, and key provider

Context::new() is the entry point — it owns an rnp_ffi_t and ties the lifetimes of every derived handle to it. A Context accepts a PasswordProvider trait object (used by rnp_request_password and any operation that needs to unlock a key) and a KeyProvider trait object (used by rnp_ffi_set_key_provider for verify/decrypt key lookup).

use rnp::{Context, KeyIdentifier, PasswordProvider, RequestedKeyType};

struct MyPw;
impl PasswordProvider for MyPw {
    fn request(&mut self, _keyid: Option<&[u8]>, _ctx: &Context) -> rnp::Result<Vec<u8>> {
        Ok(b"hunter2".to_vec())
    }
}

let mut ctx = Context::new()?;
ctx.set_password_provider(MyPw);

Key generation

KeyBuilder is the primary surface; SubkeyBuilder builds subkeys off a primary in one composite call. Both wrap rnp_op_generate_*.

use rnp::{Algorithm, Context, Hash, KeyBuilder, KeyUsage, SubkeyBuilder};

let ctx = Context::new()?;
let key = KeyBuilder::new(Algorithm::Rsa)
    .bits(3072)
    .userid("alice <alice@example.com>")
    .hash(Hash::Sha256)
    .add_usage(KeyUsage::Sign)
    .add_usage(KeyUsage::Certify)
    .add_pref_hash(Hash::Sha512)
    .clear_pref_hash()                  // reset and add a fresh set
    .add_pref_hash(Hash::Sha256)
    .add_subkey(
        SubkeyBuilder::new(Algorithm::Rsa)
            .bits(2048)
            .add_usage(KeyUsage::EncryptComms),
    )
    .build(&ctx)?;

Algorithm coverage: RSA, DSA, ElGamal, ECDSA/ECDH (NIST/Brainpool curves), EdDSA, X25519, SM2, plus the PQC composites (ML-KEM, ML-DSA, SLH-DSA) when built with the pqc feature.

Key inspection

Key<'ctx> is a borrowed handle. All getters return Result<T> so a deleted/expired/revoked underlying key surfaces as an error rather than a panic.

# use rnp::*;
# let ctx = Context::new()?;
# let key = KeyBuilder::new(Algorithm::Rsa).bits(2048)
#     .userid("alice <a@example.com>").build(&ctx)?;
println!("fp: {}", key.fingerprint()?);
println!("alg: {:?}", key.alg()?);
println!("bits: {:?}", key.bits()?);
println!("subkeys: {}", key.subkey_count()?);
for uid in key.uids()? {
    println!("uid: {}", uid.data_string()?);
}
# Ok::<(), rnp::Error>(())

UID, Subkey, Signature handles

Uid<'key>, Subkey<'key>, and Signature<'key> borrow the parent Key. They each carry a Drop that calls the matching rnp_*_handle_destroy.

# use rnp::*;
# let ctx = Context::new()?;
# let key = KeyBuilder::new(Algorithm::Rsa).bits(2048)
#     .userid("alice <a@example.com>").build(&ctx)?;
let uid = key.uids()?.into_iter().next().unwrap();
println!("primary? {}", uid.is_primary()?);
println!("signatures on uid: {}", uid.signature_count()?);

let sig = key.signatures()?.into_iter().next().unwrap();
for sp in sig.subpackets()? {
    println!("subpacket: {:?}", sp.subpacket_type());
}
# Ok::<(), rnp::Error>(())

Key mutation

# use rnp::*;
# let ctx = Context::new()?;
# let key = KeyBuilder::new(Algorithm::Rsa).bits(2048)
#     .userid("alice <a@example.com>").build(&ctx)?;
key.add_uid("alias <a@example.com>", &AddUidOptions::new().hash(Hash::Sha256))?;
key.protect(&ProtectOptions::new().password("hunter2"))?;
key.lock()?;
key.unlock(|_| Ok(b"hunter2".to_vec()))?;
# Ok::<(), rnp::Error>(())

The three signature-creation builders share a single SignatureSetterOps trait — adding a new subpacket setter adds one method to the trait and a delegating impl per concrete builder.

Sign and verify

Three signing modes (inline / detached / cleartext) all flow through one Signer builder, so new output formats are a Mode variant rather than a new top-level function.

# use rnp::*;
# let ctx = Context::new()?;
# let k1 = KeyBuilder::new(Algorithm::Rsa).bits(2048).userid("a")
#     .add_usage(KeyUsage::Sign).build(&ctx)?;
# let k2 = KeyBuilder::new(Algorithm::Rsa).bits(2048).userid("b")
#     .add_usage(KeyUsage::Sign).build(&ctx)?;
let now = std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as u32;
let sig = Signer::new(&ctx, b"doc", Mode::Detached)
    .add_signer(&k1)
    .add_signer_with_options(&k2, Hash::Sha384, Some(now), Some(604800))
    .armor(true)
    .build_to_memory()?;
# Ok::<(), rnp::Error>(())

Encrypt and decrypt

# use rnp::*;
# let ctx = Context::new()?;
# let key = KeyBuilder::new(Algorithm::Rsa).bits(2048)
#     .userid("enc <enc@example.com>")
#     .add_usage(KeyUsage::EncryptComms).build(&ctx)?;
let mut ct = Output::to_memory()?;
Encryptor::new(&ctx, b"secret")?
    .add_recipient(&key)
    .armor(true)
    .aead(AeadType::Ocb)
    .build(&mut ct)?;
let ciphertext = ct.into_bytes()?;

let result = Decryptor::new(&ctx, &ciphertext).build()?;
assert_eq!(result.plaintext(), b"secret");
# Ok::<(), rnp::Error>(())

ASCII armor, packet dumps, JSON serialization

# use rnp::*;
let armored = enarmor(b"\x88\x01...", ContentType::Binary)?;
let raw = dearmor(&armored)?;
let json = dump_packets_to_json(&ctx, &raw, JsonDumpFlags::empty())?;
let key_json = key.to_json(JsonFlags::empty())?;
# Ok::<(), rnp::Error>(())

Security profile and feature queries

# use rnp::*;
let ctx = Context::new()?;
let rule = SecurityRule::new(
    SecurityLevel::Default,
    SecurityFlags::empty(),
    FeatureType::PublicKey,
    "RSA",
)?;
ctx.add_security_rule(&rule)?;
let iters = calculate_iterations(Hash::Sha256, 100_000_000)?;
let features = supported_features()?;
assert!(supports_feature(FeatureType::HashAlgorithm, "SHA256")?);
# Ok::<(), rnp::Error>(())

Secret-string hygiene

SecretString is a Vec<u8> wrapper that zeros its bytes on Drop via rnp_buffer_clear. request_password returns one; user-supplied passwords that you want to scrub should also live in a SecretString.

PQC and crypto-refresh

Gated on the pqc and crypto-refresh Cargo features. The crate probes the linked librnp at runtime (librnp_supports_pqc) so a binary that enables PQC still degrades cleanly on a non-PQC librnp.

#[cfg(feature = "pqc")]
{
    if rnp::librnp_supports_pqc()? {
        let key = KeyBuilder::new(Algorithm::Rsa)
            .bits(2048)
            .userid("alice")
            .add_pqc_encryption_subkey(PqcAlgorithm::MlKem768X25519)
            .add_pqc_signing_subkey(PqcAlgorithm::MlDsa65Ed25519)
            .build(&ctx)?;
    }
}

Version and debug

println!("librnp {}", rnp::version_string());
let (maj, min, patch) = rnp::version::decompose();
println!("backend: {}", rnp::version::backend_string());

// Emit librnp diagnostic output to stderr (or a named file).
rnp::version::enable_debug("stderr");
rnp::version::disable_debug();

Linking

rnp-rs links against a system-installed librnp (-lrnp) by default. Use --features vendored to skip that requirement entirely.

macOS (Homebrew)

brew install rnp

Linux

# Fedora
sudo dnf install librnp-devel

# Debian/Ubuntu (if packaged)
sudo apt install librnp-dev

Pointing at a source checkout

RNP_INCLUDE_DIR=/path/to/rnp/install/include \
RNP_LIB_DIR=/path/to/rnp/install/lib \
cargo build

Vendored (no system librnp)

cargo build --features vendored

build.rs selects prebuilt/<target>/ matching your target triple and statically links librnp.a + libsexpp.a + libjson-c.a. Botan 3 is still dynamic at this stage — install via brew install botan (macOS) or your distro's botan package. Pre-builts are produced by the .github/workflows/prebuild.yml matrix for x86_64/aarch64 Linux and macOS (native runners).

Architecture

Three layers, top to bottom:

1. src/ffi.rs — bindgen-generated include! of $OUT_DIR/bindings.rs. The module is #![allow(non_camel_case_types, non_snake_case, dead_code)] because we mirror the C API verbatim.
2. src/error.rs — Error (snafu), Result<T>, and check(rnp_result_t) that maps non-zero to Error::Rnp { code, message } via rnp_result_to_string.
3. Safe wrappers — one directory module per OpenPGP concern:
   • context.rs, key/, uid.rs, subkey.rs, keygen/, signature.rs, encrypt/, verify/, armor.rs, dump.rs, security.rs, signature_handle/, key_signature_builder/, callbacks/, secret.rs, ops/ (IO + string-conversion helpers).

Every handle type borrows its parent (via PhantomData) and owns a Drop that calls the matching rnp_*_handle_destroy. Never add unsafe impl Send — librnp handles are not thread-safe.

License

BSD-2-Clause, matching the upstream RNP project. See LICENSE.md.