add design criteria of pEpMIME to README.md :-)

README.md

@@ -25,3 +25,48 @@ used. So a typical build on macOS i.e. looks like this:
 
 CXXFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib make PREFIX=$HOME -j4 all install
 
+# Design criteria of pEpMIME
+
+## Normalization
+pEpMIME "normalizes" the MIME messages during parsing, and uses some heuristics especially for
+non-MIME-compliant inputs. The generated `struct message` always
+
+* contains UTF-8 NFC-compliant text in `longmsg` and `longmsg_formatted`
+* contains appropriate MIME headers, e.g. `Mime-Type` and `charset`
+* …
+
+The MIME generator also serializes data in a special and predictive manner:
+* Non-7bit data in MIME leaves' headers and bodies are always base64 encoded. "quoted printable"
+  encoding is never generated.
+* MIME delimiter are short and predictive "=pEp=#=", where `#` is the smallest possible
+hexadecimal number so the delimiter does not occur in the message.
+
+Due to this normalization there is *no* round-trip guarantee that a generated MIME message is
+identical to the original MIME message:
+
+1) "MIME_text" --> `struct message` --> "MIME_text2"
+"MIME text" and "MIME_text2" usually differ due to normalization
+
+
+2) `struct message msg1` --> "MIME_text" --> `struct message msg2`
+The content of `msg1` and `msg2` is identical, except …
+(*FIXME*: AFAIK there are special bizarre cases, but I don't remember at the moment)
+
+
+## Special Headers
+Additionally pEpMIME adds some internal annotations into `message->opt_fields` using keys that start
+with ":pEp:MIME:", a string that can never occur in MIME messages, so they cannot be set by external
+attackers. The MIME generator of pEpMIME is aware of these special header lines, acts appropriately
+and skips *any* element in `message->opt_fields` that start with ":", so they will never occur as
+MIME header in the generated MIME message.
+
+Adapters and clients are allowed to use these special header fields and might also define their own
+(with another prefix, so they won't interfere with future pEpMIME headers).
+
+Currently these special headers are used by pEpMIME:
+
+* `:pEp:MIME:longmsg:format` and `:pEp:MIME:longmsg:delsp`:  to store the special annotations for
+  plaintext bodies, according to RFC 3676 <https://datatracker.ietf.org/doc/html/rfc3676>.
+* `:pEp:MIME:attachment1:forwarded`: represents the flag `has_possible_pEp_msg` / `has_pEp_msg_attachment`.
+  This field is used only internally and does not occur in the returned `struct message`.
+