katzenpost_thin_client 0.0.16

This rust crate provides an async thin client library for Katzenpost, a post quantum decryption mixnet.
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
118
119

# katzenpost_thin_client

*A thin client for sending and receiving messages via the Katzenpost
mix network.*

This crate provides an async Rust thin client library for
interacting with a [Katzenpost](https://katzenpost.network/) mixnet.

A mix network is a type of anonymous communications network. A
thin client library is code you may use as a dependency in your
application so that it can anonymously interact with services on
the mix network. The Katzenpost client daemon (`kpclientd`) is a
multiplexing client; many applications on the same device may use
their thin client libraries to connect to the daemon and interact
with mixnet services concurrently. All cryptographic operations,
including PQ Noise transport, Sphinx packet construction, and ARQ
retransmission, are performed by the daemon, not by this library.


## Pigeonhole, in brief

Beyond simple request-response services, Katzenpost provides a
storage layer called Pigeonhole. Applications communicate through
encrypted, append-only streams composed of fixed-size, padded Boxes,
sharded across storage replicas via consistent hashing. Access is
governed by cryptographic capabilities: a write capability appends
messages or places tombstones, whilst a separate read capability
decrypts and verifies without conferring any ability to write.
Streams are single-writer, multi-reader, and unlinkable to outside
observers. Storage is ephemeral: Boxes are garbage-collected after
roughly two weeks, so Pigeonhole is not intended for long-term
archival storage. For a developer-oriented introduction, see
[Understanding Pigeonhole](https://katzenpost.network/docs/pigeonhole_explained/).


## Documentation

- [Thin Client How-to Guide](https://katzenpost.network/docs/thin_client_howto/), task-oriented examples in Go, Rust, and Python.
- [Thin Client API Reference](https://katzenpost.network/docs/thin_client_api_reference/), the unified API reference for all three languages.
- [Rust API reference](https://docs.rs/katzenpost_thin_client/latest/katzenpost_thin_client/) on docs.rs.
- [Understanding Pigeonhole](https://katzenpost.network/docs/pigeonhole_explained/), conceptual background on Pigeonhole.
- [Build from source](https://katzenpost.network/docs/build_from_source/), the canonical record of pinned versions for `kpclientd` and the thin clients.


## Installation

Add the crate to your `Cargo.toml`:

```toml
[dependencies]
katzenpost_thin_client = "0.0.11"
```

Please consult
[Build from source](https://katzenpost.network/docs/build_from_source/)
for the version pinned alongside the rest of the stack; that page
is the canonical record for `kpclientd`, the Go reference thin
client, the Rust and Python thin clients, and `katzenqt`.


## pigeonhole-cp

The crate also ships a small command-line utility, `pigeonhole-cp`,
for sending and receiving files to and from Pigeonhole channels.
It is gated behind the `cli` feature:

```bash
cargo build --release --features cli --bin pigeonhole-cp
```

Its source is at
[`src/bin/pigeonhole_cp.rs`](https://github.com/katzenpost/thin_client/blob/main/src/bin/pigeonhole_cp.rs)
and serves as a worked example of the persistent Pigeonhole API.


## Running the tests

The `tests/` directory contains the integration suite, which doubles
as a working reference for the API. The tests expect a running
Katzenpost mixnet; the most convenient way to obtain one is the
docker test mixnet shipped with the
[Katzenpost monorepo](https://github.com/katzenpost/katzenpost).
Full instructions are in
[Docker test network](https://katzenpost.network/docs/admin_guide/docker.html);
the short form is:

```bash
cd katzenpost/docker
make start wait run-ping
```

The mixnet runs `kpclientd` inside a container exposed on
`127.0.0.1:64331`, and writes a thin client configuration to
`voting_mixnet/client/thinclient.toml`. The test suite uses the
preconfigured fixture at `testdata/thinclient.toml`, which dials
the daemon on that port. Run the suite with:

```bash
cargo test --features cli
```


## Compatibility

This crate is intended to be used with the version of `kpclientd`
listed in
[Build from source](https://katzenpost.network/docs/build_from_source/).


## Contributions

This is a work in progress, and we welcome feedback from developers
who try to use it. Pull requests are welcome at
<https://github.com/katzenpost/thin_client>.


## License

AGPLv3.