# Mesozoa

Why not Anubis? Because it provides no build instructions and only supports Docker.

Why not using Realm completely? Because the hook system is useless and only allows filtering.

## Install

Must be used behind a reverse proxy providing `X-Forwarded-For`.

## Challenge protocol

### Challenge generation

Sent by the server as a cookie.

`secret <- chosen randomly, long term`

`salt <- chosen randomly, not stored`

`timestamp <- UNIX time in seconds, 64 bits, big endian`

`ua <- User-Agent from request header`

`ip <- X-Forwarded-For from request header (client's IP)`

`set-cookie: mesozoa-challenge=BASE64(salt || timestamp || SHA3-256(secret || salt || timestamp || ip || "/" || ua))`

Where `BASE64` is unpadded.

### Challenge verification

Request must contain both cookies `mesozoa-challenge` and `mesozoa-proof`.

## Security

### Network handling and HTTP parsing

This implementation uses cheap tricks and regexes, is probably not fully compliant to HTTP specs, etc.
You should probably not expose it directly to an open network.
Please use it behind a safer reverse proxy like Apache or Nginx.

### Length-extension attack

SHA3 (used as a MAC in the challenge cookie) is not vulnerable. Values in the hash are either fixed-length, safe, or delimited.

SHA2 (used for PoW) is vulnerable but nonce is at the beginning so this is not a problem.

### PoW

I would like a better PoW: memory-bound and ideally non-parallel. Cuckoo seems a good candidate.

## License

[Support me via LiberaPay](https://liberapay.com/tuxmain/donate)

GNU AGPL v3, CopyLeft 2025 Pascal Engélibert [(why copyleft?)](https://txmn.tk/blog/why-copyleft/)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, version 3 of the License.  
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.  
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.