libsession 0.1.3

Session messenger core library - cryptography, config management, networking
Documentation

libsession

Build Tests Coverage Crates.io Documentation License: GPL-3.0

Rust implementation of the Session messenger core library. Provides cryptography, distributed configuration management, onion-routed networking, and protocol definitions used by Session clients.

Modules

crypto

Cryptographic primitives and message encryption:

  • Key generation -- Ed25519 and X25519 key pairs
  • Session encryption -- sealed-box encryption for 1:1 messages, group encryption with per-recipient keys
  • Blinding -- Blind15/Blind25 identity hiding for community messaging
  • Multi-recipient encryption -- encrypt a single message for multiple recipients
  • Attachments -- deterministic XChaCha20-Poly1305 streaming encryption with padding
  • Hashing -- BLAKE2b with configurable output size
  • Key conversion -- Ed25519 to Curve25519 and XEd25519 operations

config

Distributed configuration management for multi-device sync:

  • UserProfile -- display name, avatar, settings
  • Contacts -- contact list with approval states
  • UserGroups -- group and community memberships
  • ConvoInfoVolatile -- conversation metadata (mute, pin, read state)
  • Local -- device-local settings
  • Groups -- group info, members, and key rotation

Each config type supports merge-based conflict resolution, encrypted push/pull to the Session swarm, and dirty-state tracking.

network

Onion-routed communication through the Session service node network:

  • Onion requests -- 3-hop encrypted routing through service nodes
  • QUIC transport -- QUIC-based connections with TLS via rustls
  • Snode pool -- service node discovery and swarm management
  • Request queue -- scheduling, retry logic, and path selection
  • Backends -- file server and open group (community) server support

protocol

Protocol constants, version strings, and Session Pro payment proof verification.

util

Shared utilities: bencode serialization, zstd compression, Session ID validation, logging setup.

proto

Generated protobuf bindings for Session message envelopes and WebSocket protocol messages.

Usage

Add to your Cargo.toml:

[dependencies]
libsession = "0.1"

Key generation

use libsession::crypto::ed25519;
use libsession::crypto::curve25519;

// Generate an Ed25519 key pair
let (public_key, secret_key) = ed25519::ed25519_key_pair();

// Convert to Curve25519 for X25519 key exchange
let curve_pub = curve25519::to_curve25519_pubkey(&public_key);

Message encryption

use libsession::crypto::session_encrypt::{encrypt_for_recipient, decrypt_incoming};
use libsession::crypto::types::SessionIdPrefix;

// Encrypt a message for a recipient
let ciphertext = encrypt_for_recipient(
    &sender_ed_seckey,
    &recipient_x25519_pubkey,
    b"hello",
    SessionIdPrefix::Standard,
).unwrap();

Hashing

use libsession::crypto::hash;

let digest = hash::hash(32, b"input data", None).unwrap();

Building

Requires Rust 1.93+ and a protobuf compiler (protoc).

cargo build
cargo test

License

This project is licensed under the GNU General Public License v3.0 -- see the LICENSE file for details.