misfin/specification.gmi

# The Misfin mail protocol (prototype B)

## 1 Overview

Misfin is a client-server mail transport protocol, broadly similar to SMTP and heavily influenced by Gemini. All connections follow the pattern request-response, and are closed at the end of this transaction.

Misfin servers on TCP/IP should be bound to port 1958, which is unprivledged and should be accessible without administrator permissions on most systems. 

### 1.1 Misfin transactions

The sole type of Misfin transaction delivers a message from a client to a server. This transaction proceeds as so:

C: Opens connection
S: Accepts connection
C/S: Complete TLS handshake
C/S: Validate peer's certificate[s]
C: Sends one CRLF terminated line - the request
S: Sends one CRLF terminated line - the response
C/S: Closes connection, handling response if not OK

Both clients and servers should gracefully handle connections that close before they are expected to.

### 1.2 Misfin request scheme

A single request line is sent by the Misfin client to a Misfin server, following this structure:
```
misfin://<MAILBOX>@<HOSTNAME><SPACE><MESSAGE><CR><LF>
```
MAILBOX is the user receiving the message.
HOSTNAME is the domain name that points to the Misfin server.
SPACE is a single space character, i.e. the byte 0x20.

The remainder of the request following the SPACE, and up until the terminating CRLF, makes up the MESSAGE, which is assumed to be Gemtext. All strings are UTF-8 encoded, and the entire request should not exceed 2048 bytes.

By including the hostname of the server in the request, advanced Misfin servers can host mailboxes for multiple domains on the same host. Servers are not required to implement this feature, and are only expected to service mail for a single domain.

### 1.3 Misfin response scheme

The Misfin server will send a single response line to the requesting client, following this structure:
```
<STATUS><SPACE><META><CR><LF>
```
STATUS is a two-digit numeric status code.
META is a string whose meaning is defined by the status code.

Like requests, response strings are UTF-8 encoded and should not exceed 2048 bytes in length. After the response is sent, the transaction is finished, and the connection should be closed. 

## 2 Status codes

Misfin servers send a two-digit status code in their response to the client, which either confirms the message was delivered, or explains why it wasn't. The status code's category is indicated by the first digit, so simple clients only need to read the first character of the response to know, broadly, what it should do.

These status codes are designed to be compatible with Gemini's, so developers comfortable with Gemini status codes should intuitively know the meaning of Misfin status codes. 

### 2.1 1x (INPUT)
These codes are reserved, and must not be sent by a Misfin server.

### 2.2 2x (SUCCESS)
Status codes beginning with 2 are SUCCESS status codes, which mean that the client's message has been delivered.

#### 20 <fingerprint> - MESSAGE DELIVERED
The message was delivered successfully. The META tag is the fingerprint of the recipient's certificate, in SHA256 format.

### 2.3 3x (REDIRECT)

Status codes beginning with 3 are REDIRECT status codes, which tell the client to resend their request to a different Misfin server.

#### 30 <address> - SEND HERE INSTEAD
The mailbox has moved to a different address, and this message should be resent to that address.

#### 31 <address> - SEND HERE FOREVER
The mailbox has moved to a different address, and all future messages should be sent to that address.

### 2.4 4x (TEMPORARY FAILURE)

Status codes beginning with 4 are TEMPORARY FAILURE status codes, which mean the request did not succeed, but might succeed if retried in the future.

#### 40 - TEMPORARY ERROR
The mailserver experienced a transient issue, and the message should be resent.

#### 41 - SERVER IS UNAVAILABLE
The mailserver can't accept mail right now.

#### 42 - CGI ERROR
A mailserver script ran for your message, but experienced an error.

#### 43 - PROXYING ERROR
There was a problem accepting mail for that domain, but it might resolve itself.

#### 44 - SLOW DOWN
You are being rate limited - wait before trying to send more mail.

#### 45 - MAILBOX FULL
The mailbox isn't accepting mail right now, but it might in the future.

### 2.5 5x (PERMANENT FAILURE)

Status codes beginning with 5 are PERMANENT FAILURE status codes, which mean the request did not succeed, and should not be retried.

#### 50 - PERMANENT ERROR
Something is wrong with the mailserver, and you should not try to resend your message.

#### 51 - MAILBOX DOESN'T EXIST 
The mailbox you are trying to send to doesn't exist, and the mailserver won't accept your message.

#### 52 - MAILBOX GONE
The mailbox you are trying to send to existed once, but doesn't anymore, and it isn't coming back.

#### 53 - DOMAIN NOT SERVICED
This mailserver doesn't serve mail for the hostname you provided.

#### 59 - BAD REQUEST
Your request is malformed, and won't be accepted by the mailserver.

### 2.6 6x (AUTHENTICATION FAILURE)

Status codes beginning with 6 are AUTHENTICATION FAILURE status codes, which mean that there was an issue with the client's certificate.

#### 60 - CERTIFICATE REQUIRED
This mailserver doesn't accept anonymous mail, and you need to repeat your request with a certificate.

#### 61 - UNAUTHORIZED SENDER
Your certificate was validated, but you are not allowed to send mail to that mailbox.

#### 62 - CERTIFICATE INVALID
Your certificate might be legitimate, but it has a problem - it is expired, or it doesn't point to a valid Misfin identity, etc.

#### 63 - YOU'RE A LIAR
Your certificate matches an identity that the mailserver recognizes, but the fingerprint has changed, so it doesn't recognize you.

#### 64 - PROVE IT
The mailserver needs you to complete a task to confirm that you are a legitimate sender. (This is reserved for a Hashcash style anti-spam measure).

## 3 TLS

The use of TLS is mandatory for Misfin transactions. The minimum permissible version of TLS allowed for transactions is TLS 1.2, but clients and servers may choose a more recent version of TLS to support and disallow connections from earlier versions.

Misfin clients and servers must send a TLS "close-notify" prior to closing the connection, so that a complete transaction can be distinguished from one that has ended prematurely.

### 3.1 Misfin identity certificates

Senders and recipients are identified via self-signed x509 certificates, sent as part of a Misfin transaction's TLS handshake. Senders are not required to send a certificate, but are strongly urged to do so, and mailservers should require sender certificates (unless you really know what you are doing).

A Misfin identity consists of a mailbox name, the hostname of the user's mailserver, and a human-readable description of the mailbox or user (the blurb). The mailbox and blurb are stored in the USER_ID and COMMON_NAME fields, respectively, of the certificate's Distinguished Name (as per RFC 4514). The hostname is stored as a DNS record in the certificate's SUBJECT_ALT_NAME extension, to be compatible with Server Name Indication (SNI). Other fields in the subject and issuer names can be present, but are not required to be present, and should not be relied on by Misfin utilities.

A Misfin address is written as "mailbox@hostname", or "blurb (mailbox@hostname)" in longform.

Multiple mailboxes can be serviced by a single mailserver; in this case, the mailserver's certificate should be self-signed, and each mailbox certificate should be signed by the mailserver certificate, so other clients and servers can confirm that those mailboxes actually exist on the mailserver. Mailserver certificates used this way should have the CA constraint set to True, so the mailserver certificate can cryptographically verify its mailbox certificates.

### 3.2 Certificate validation

Misfin clients and servers send certificates during a transaction, but have no obligation to verify these certificates; however, this is highly, highly discouraged.

Like Gemini, the default validation method for certificates is TOFU, or Trust on First Use. Misfin clients and servers should store the fingerprint of a received certificate the first time it is received, and subsequent certificates from that client or server should be matched against the stored fingerprint. 

Advanced Misfin servers may perform CA validation in addition to TOFU. In this scheme, upon receiving a message from a sender with an unrecognized host, the Misfin server may perform a single blank request to the sender's host, and store its certificate. That stored certificate can then be used to verify the certificates of senders purporting to be from that host.

Certificates may be signed by other CAs; Misfin servers may choose to verify these signatures, but are not required to.

### 3.3 Security implications

TOFU is a better-than-nothing strategy that should be suitable for most Misfin users; as long as you've successfully interacted with a legitimate sender once, future attempts to intercept or forge interactions with them will fail.

CA validation is even better; you only need to have an uncompromised connection to a server once, and you can then verify the legitimacy of anyone reporting to have a mailbox with them. This method also has the effect of disallowing messages from senders that are not associated with a Misfin server, which might be desireable in some cases.

Since the sender of a message is identified solely by their certificate, it is not possible to spoof the sender's address in a way that is not visible to the recipient. For instance, you could generate a new, self-signed certificate claiming to be bob@example.com, and send mail pretending to be Bob; however, any replies to those messages will be delivered to the Misfin server at example.com, and not to you.