2017-08-21 18:33:41 +03:00
|
|
|
# hydroxide
|
2017-09-03 21:21:22 +03:00
|
|
|
|
2017-12-03 13:32:33 +02:00
|
|
|
A third-party, open-source ProtonMail bridge. For power users only, designed to
|
|
|
|
run on a server.
|
|
|
|
|
2018-01-13 12:40:21 +02:00
|
|
|
hydroxide supports CardDAV, IMAP and SMTP.
|
2017-09-03 21:21:22 +03:00
|
|
|
|
2017-12-03 13:40:18 +02:00
|
|
|
Rationale:
|
|
|
|
|
|
|
|
* No GUI, only a CLI (so it runs in headless environments)
|
|
|
|
* Standard-compliant (we don't care about Microsoft Outlook)
|
|
|
|
* Fully open-source
|
|
|
|
|
2019-05-12 11:21:30 +03:00
|
|
|
Feel free to join the IRC channel: ##emersion on irc.freenode.net.
|
|
|
|
|
2019-03-22 22:08:15 +02:00
|
|
|
## How does it work?
|
|
|
|
|
|
|
|
hydroxide is a server that translates standard protocols (SMTP, IMAP, CardDAV)
|
|
|
|
into ProtonMail API requests. It allows you to use your preferred e-mail clients
|
|
|
|
and `git-send-email` with ProtonMail.
|
|
|
|
|
|
|
|
+-----------------+ +-------------+ ProtonMail +--------------+
|
|
|
|
| | IMAP, SMTP | | API | |
|
|
|
|
| E-mail client <-------------> hydroxide <--------------> ProtonMail |
|
|
|
|
| | | | | |
|
|
|
|
+-----------------+ +-------------+ +--------------+
|
|
|
|
|
2017-12-09 15:22:54 +02:00
|
|
|
## Setup
|
|
|
|
|
2018-01-13 12:40:21 +02:00
|
|
|
### Go
|
2017-12-09 15:22:54 +02:00
|
|
|
|
2019-03-22 22:08:15 +02:00
|
|
|
hydroxide is implemented in Go. Head to [Go website](https://golang.org) for
|
|
|
|
setup information.
|
2017-12-09 15:22:54 +02:00
|
|
|
|
2019-03-22 22:08:15 +02:00
|
|
|
### Installing
|
2017-12-09 15:22:54 +02:00
|
|
|
|
2019-03-22 22:08:15 +02:00
|
|
|
Start by installing hydroxide:
|
2017-12-09 15:22:54 +02:00
|
|
|
|
|
|
|
```shell
|
2020-07-08 05:28:37 +03:00
|
|
|
git clone https://github.com/emersion/hydroxide.git
|
|
|
|
GO111MODULE=on go build ./cmd/hydroxide
|
2017-12-09 15:22:54 +02:00
|
|
|
```
|
2017-09-03 21:21:22 +03:00
|
|
|
|
2019-03-22 22:08:15 +02:00
|
|
|
Then you'll need to login to ProtonMail via hydroxide, so that hydroxide can
|
|
|
|
retrieve e-mails from ProtonMail. You can do so with this command:
|
2017-09-09 16:37:03 +03:00
|
|
|
|
2017-09-03 21:21:22 +03:00
|
|
|
```shell
|
2017-09-09 16:37:03 +03:00
|
|
|
hydroxide auth <username>
|
2017-12-03 13:32:33 +02:00
|
|
|
```
|
|
|
|
|
2019-03-22 22:08:15 +02:00
|
|
|
Once you're logged in, a "bridge password" will be printed. Don't close your
|
|
|
|
terminal yet, as this password is not stored anywhere by hydroxide and will be
|
|
|
|
needed when configuring your e-mail client.
|
|
|
|
|
|
|
|
Your ProtonMail credentials are stored on disk encrypted with this bridge
|
|
|
|
password (a 32-byte random password generated when logging in).
|
|
|
|
|
2017-12-09 15:22:54 +02:00
|
|
|
## Usage
|
|
|
|
|
|
|
|
hydroxide can be used in multiple modes.
|
|
|
|
|
2019-07-18 19:20:29 +03:00
|
|
|
> Don't start hydroxide multiple times, instead you can use `hydroxide serve`.
|
|
|
|
> This requires ports 1025 (smtp), 1143 (imap), and 8080 (carddav).
|
2019-06-29 18:11:42 +03:00
|
|
|
|
2019-03-22 22:08:15 +02:00
|
|
|
### SMTP
|
|
|
|
|
|
|
|
To run hydroxide as an SMTP server:
|
|
|
|
|
|
|
|
```shell
|
|
|
|
hydroxide smtp
|
|
|
|
```
|
|
|
|
|
|
|
|
Once the bridge is started, you can configure your e-mail client with the
|
|
|
|
following settings:
|
|
|
|
|
|
|
|
* Hostname: `localhost`
|
|
|
|
* Port: 1025
|
|
|
|
* Security: none
|
|
|
|
* Username: your ProtonMail username
|
|
|
|
* Password: the bridge password (not your ProtonMail password)
|
|
|
|
|
2017-12-03 13:32:33 +02:00
|
|
|
### CardDAV
|
|
|
|
|
|
|
|
You must setup an HTTPS reverse proxy to forward requests to `hydroxide`.
|
|
|
|
|
|
|
|
```shell
|
2017-12-02 17:23:06 +02:00
|
|
|
hydroxide carddav
|
2017-09-03 21:21:22 +03:00
|
|
|
```
|
|
|
|
|
2017-09-09 16:37:03 +03:00
|
|
|
Tested on GNOME (Evolution) and Android (DAVDroid).
|
2017-09-03 21:21:22 +03:00
|
|
|
|
2018-01-13 12:40:21 +02:00
|
|
|
### IMAP
|
|
|
|
|
|
|
|
For now, it only supports unencrypted local connections.
|
|
|
|
|
|
|
|
```shell
|
|
|
|
hydroxide imap
|
|
|
|
```
|
|
|
|
|
2017-09-03 21:21:22 +03:00
|
|
|
## License
|
|
|
|
|
|
|
|
MIT
|