p≡p MIME library
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

72 lines
3.3 KiB

  1. # Build Instructions
  2. ## Requirements
  3. * Boost (1.63 or newer)
  4. * libiconv
  5. (for Windows: https://github.com/pffang/libiconv-for-Windows )
  6. * pEpEngine – see next section
  7. * GoogleTest (GTest) – not to use library, but to run the unittests. :-)
  8. (for Windows you might follow these instructions:
  9. <https://docs.microsoft.com/en-us/visualstudio/test/how-to-use-google-test-for-cpp?view=vs-2019>)
  10. ## Solve the cyclic dependency to pEpEngine
  11. To build p≡p MIME it's necessary that header files of p≡p engine are already
  12. installed. Because of the dependency loop of p≡p MIME needing these headers and
  13. p≡p engine depending on p≡p MIME you best do things in this sequence:
  14. 1. cd pEpEngine && make -C src install_headers
  15. 1. cd pEpMIME/src && make install
  16. 1. cd pEpEngine && make install
  17. The build of p≡p MIME can be customized. Makefile variable PREFIX is the
  18. install directory. The environment variables CXXFLAGS and LDFLAGS are being
  19. used. So a typical build on macOS i.e. looks like this:
  20. CXXFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib make PREFIX=$HOME -j4 all install
  21. # Design criteria of pEpMIME
  22. ## Normalization
  23. pEpMIME "normalizes" the MIME messages during parsing, and uses some heuristics especially for
  24. non-MIME-compliant inputs. The generated `struct message` always
  25. * contains UTF-8 NFC-compliant text in `longmsg` and `longmsg_formatted`
  26. * contains appropriate MIME headers, e.g. `Mime-Type` and `charset`
  27. *
  28. The MIME generator also serializes data in a special and predictive manner:
  29. * Non-7bit data in MIME leaves' headers and bodies are always base64 encoded. "quoted printable"
  30. encoding is never generated.
  31. * MIME delimiter are short and predictive "=pEp=#=", where `#` is the smallest possible
  32. hexadecimal number so the delimiter does not occur in the message.
  33. Due to this normalization there is *no* round-trip guarantee that a generated MIME message is
  34. identical to the original MIME message:
  35. 1) "MIME_text" --> `struct message` --> "MIME_text2"
  36. "MIME text" and "MIME_text2" usually differ due to normalization
  37. 2) `struct message msg1` --> "MIME_text" --> `struct message msg2`
  38. The content of `msg1` and `msg2` is identical, except …
  39. (*FIXME*: AFAIK there are special bizarre cases, but I don't remember at the moment)
  40. ## Special Headers
  41. Additionally pEpMIME adds some internal annotations into `message->opt_fields` using keys that start
  42. with ":pEp:MIME:", a string that can never occur in MIME messages, so they cannot be set by external
  43. attackers. The MIME generator of pEpMIME is aware of these special header lines, acts appropriately
  44. and skips *any* element in `message->opt_fields` that start with ":", so they will never occur as
  45. MIME header in the generated MIME message.
  46. Adapters and clients are allowed to use these special header fields and might also define their own
  47. (with another prefix, so they won't interfere with future pEpMIME headers).
  48. Currently these special headers are used by pEpMIME:
  49. * `:pEp:MIME:longmsg:format` and `:pEp:MIME:longmsg:delsp`: to store the special annotations for
  50. plaintext bodies, according to RFC 3676 <https://datatracker.ietf.org/doc/html/rfc3676>.
  51. * `:pEp:MIME:attachment1:forwarded`: represents the flag `has_possible_pEp_msg` / `has_pEp_msg_attachment`.
  52. This field is used only internally and does not occur in the returned `struct message`.