randogoth/smol.place
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rewrite landing page as a smolmail primer and fix broken license and reference links

Browse source
This commit is contained in:
randogoth 2026-10-09 09:47:23 +03:00
parent 4f43575808
commit 6939790caa
4 changed files with 533 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

96
index.md
View file

@ -1,49 +1,99 @@
# smolmail
A small decentralised mail protocol with cypherpunk leanings, encrypted end to end. It is simple enough that writing your own client is an afternoon of fun.
A small, decentralised mail system where every message is encrypted end to end. It's simple enough that you can write your own client in an afternoon.
You get an address, a key and a message. That's all there is to it.
- **One key is your identity.** Back up 32 bytes and you've backed up everything.
- **Only the recipient can read your mail.** Servers store sealed envelopes they can't open.
- **No middlemen.** Your client delivers straight to the recipient's server.
There are five operations and no way to add more. Underneath sit four cryptographic primitives that have been around long enough to be boring. Your identity is a single 32-byte key, and that key is the only thing you ever have to back up. Nothing expires, and nobody vouches for anybody: you pin a server's key the first time you connect, and from then on your client only has to check that it still matches.
[Open webmail](https://webmail.smol.place) · [Read the specification](SPEC.md)
Each message is sealed with a key that exists for that message alone and is discarded straight after, which leaves nothing behind to trace or to forge.
## How smolmail compares
Keeping spam out does not require anyone to read your mail. Every mailbox has a limit on how much it will hold, and a stranger needs a token from you before the server will accept their message. The server can turn mail away, but it cannot open it. Your client talks straight to the recipient's server, with nothing in between.
| | Email | PGP email | smolmail |
| --- | --- | --- | --- |
| Server reads mail | Yes | No | No |
| Server sees sender | Yes | Yes | No |
| Spam filter reads mail | Yes | Partly | No |
| Relayed by other servers | Yes | Yes | No |
| Needs the internet | Yes | Yes | No\* |
Your name is yours on that server because you signed for it with your key, and nobody without that key can claim it. If you ever have to switch keys, your old key signs over to the new one and your name follows. Messages still sent to the old key arrive as before, so contacts can catch up in their own time.
\* Only when the server is also reachable over Reticulum. See "Beyond the internet" below.
## Send your first message
## Get started
Get started with a @smol.place address. Pin our server's public key before you connect:
### Use webmail
> `po3cxpzjrt73dypt2rplskbkywizr44afhqthaa5x47mfpe4kesq`
Go to [webmail.smol.place](https://webmail.smol.place) to register a @smol.place address and start sending encrypted mail. Nothing to install.
Your smol mail client checks it on every connection, so you always know you're talking to us and never an impostor.
A browser client depends on the site that serves it, because the code is loaded fresh each time you open the page. For long-term use, a native client that pins our server key gives you stronger guarantees.
Not sure what any of this means? No problem! Just visit our [Webmail Client](http://webmail.smol.place) to register your address and start sending encrypted messages.
### Use a native client
## Identity
Connect to `smol.place` on port `1961`, and pin this server key before you connect:
The only secret is a 32-byte master. Back that up and nothing else: the Ed25519 signing key, the encryption key derived from it, and the key that issues accept tokens all come out of it. One thing to hold, move between servers, print on paper or scan from a screen.
> `po3cxpzjrt73dypt2rplskbkywizr44afhqthaa5x47mfpe4kesq`
Signatures prove authorship. A throwaway key per message means a stolen identity key cannot decrypt anything already sent.
Your client checks the key every time it connects, so it always knows it's talking to us and not an impostor.
## Addressing
### Write your own client
The whole protocol is five operations and four well-known cryptographic building blocks, with no extensions and nothing to negotiate. [SPEC.md](SPEC.md) has everything you need.
## How it works
### Your key is you
Your identity is a single 32-byte secret called the master. Your signing key, your encryption key and the key that lets people write to you all come from it. Back up the master and nothing else. You can print it on paper or scan it from a screen. ([SPEC §2](SPEC.md#2-identity))
### Your address
```
alice@example.org short form, resolved via the server
smol://alice@example.org/mfrggzdfmztwq2lknnwg23tpo… self-certifying, carries its own key
alice@smol.place short form, looked up on the server
smol://alice@smol.place/mfrggzdfmztwq2lknnwg23tpo… full form, carries alice's key
```
The short form is typeable. The long form carries the key itself, so an address shared by QR code, contact file or link needs no trust in any server at all. Either way, changing servers never changes an identity.
The short form is easy to type. The full form contains the key itself, so a contact you add from a link or QR code doesn't depend on any server telling the truth. To check a contact in person or on the phone, compare fingerprints: the first 20 characters of the key, read in groups of four. ([SPEC §3](SPEC.md#3-addressing))
Keys learned from a server are pinned on first use. Later changes need a rotation certificate signed by the previous key, or explicit confirmation.
### Every message is sealed
## Cryptography
Each message is locked with a key made for that message alone, then thrown away. The envelope names the recipient but not the sender, so the server can't see who writes to whom. Inside, the message is signed, so the recipient knows who wrote it and that nobody changed it. ([SPEC §5](SPEC.md#5-message-format))
Ed25519 · X25519 · ChaCha20-Poly1305 · SHA-256. Four established primitives, no novel cryptography, nothing else anywhere in the protocol. Transport is TCP with a Noise handshake. No certificates, no CA, no expiry.
### Mail from strangers
Servers can't read your mail, so they can't filter spam by content. Instead, you give each person you correspond with an accept token. Mail that carries a token goes to your main mailbox. Mail without one goes to a small requests area that holds less and clears out sooner. Anyone can still write to you, but nobody can fill your mailbox. Your client decides what to do with each message after opening it. ([SPEC §5.8](SPEC.md#58-accept-tokens))
### Changing keys
If you need a new key, your old key and your new key both sign a handover, and your address moves to the new key. Mail sent to your old key still arrives, so your contacts can catch up in their own time. Clients show you when a contact's key changes. ([SPEC §7](SPEC.md#7-key-rotation))
## What smolmail protects
The server learns which mailbox each message is for, its size, when it arrived and was collected, and the IP address you connect from. It doesn't learn the sender, the subject, the content or which messages belong together.
Some things smolmail doesn't protect:
- **Your stored mail, if your master is stolen.** Someone holding your master can read every message you've received that's still stored. Keep it safe. Your master can't open mail you've sent to others, because the key that sealed it was thrown away.
- **Who wrote a message.** Messages are signed, so a recipient can prove to others that you wrote it.
- **Traffic patterns.** Someone watching the network can see when you connect and how much you send.
Messages don't stay on the server forever. Mail in your main mailbox is kept for 30 days and mail in requests for 7 days, unless you delete it sooner. ([SPEC §9](SPEC.md#9-privacy), [§10](SPEC.md#10-servers))
## Beyond the internet
- **Reticulum.** A smolmail server can be reachable over the Reticulum network, which runs over LoRa radio, packet radio, serial links and more, with no DNS or internet needed. Your identity and messages work the same on either network. ([SPEC §13](SPEC.md#13-reticulum-transport))
- **Tor.** A server can run as a Tor onion service to hide where people connect from. No protocol changes are needed. ([SPEC §9](SPEC.md#9-privacy))
- **Browsers and restricted networks.** Browsers can't open a direct connection to port 1961, so smolmail can travel through a WebSocket on port 443. The encryption and the server key check stay exactly the same. ([WS.md](WS.md))
## Run your own server
Servers never talk to each other. Each one is an independent mailbox store, so running one is a small job. Anyone with a smolmail address can write to anyone on any other server.
The [reference client and server](https://code.randogoth.com/randogoth/smolmail) are written in Python, for both TCP and Reticulum. The [gsmol](https://code.randogoth.com/randogoth/gsmol) bridge carries smolmail over WebSocket.
## Specification
[SPEC.md](SPEC.md): wire format, operations, trust model and conformance.
[WS.md](WS.md): smolmail over WebSocket annex.
- [SPEC.md](SPEC.md): smolmail protocol, version 1.2. Message format, operations, trust model and conformance.
- [WS.md](WS.md): smolmail over WebSocket.
The specification is licensed under [CC BY-SA 4.0](LICENSES/CC-BY-SA-4.0.txt).