libsession 0.1.8

Session messenger core library - cryptography, config management, networking
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# libsession

[![Build](https://github.com/intellisoftalpin/libsession-rust/actions/workflows/build.yml/badge.svg)](https://github.com/intellisoftalpin/libsession-rust/actions/workflows/build.yml)
[![Tests](https://github.com/intellisoftalpin/libsession-rust/actions/workflows/test.yml/badge.svg)](https://github.com/intellisoftalpin/libsession-rust/actions/workflows/test.yml)
[![Coverage](https://codecov.io/gh/intellisoftalpin/libsession-rust/graph/badge.svg)](https://codecov.io/gh/intellisoftalpin/libsession-rust)
[![Crates.io](https://img.shields.io/crates/v/libsession.svg)](https://crates.io/crates/libsession)
[![Documentation](https://docs.rs/libsession/badge.svg)](https://docs.rs/libsession)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0--only-blue.svg)](LICENSE)

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`:

```toml
[dependencies]
libsession = "0.1"
```

### Key generation

```rust
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

```rust
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

```rust
use libsession::crypto::hash;

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

## Building

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

```sh
cargo build
cargo test
```

## License

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