imap/dkim2_mi.h

DKIM2 Message-Instance calculation.

Cyrus documents its own modifications but never signs: everything here produces a Message-Instance header field for some other hop to sign. Section numbers cited throughout are draft-ietf-dkim-dkim2-spec-06.

Enums

enum dkim2_mi_result

Outcome of dkim2_mi_calculate()

Values:

enumerator DKIM2_MI_NONE

no Message-Instance is needed

enumerator DKIM2_MI_ADDED

mi_out holds the new header field value

enumerator DKIM2_MI_CHAIN_MISMATCH

incoming message doesn't match its own MI

Functions

enum dkim2_mi_result dkim2_mi_calculate(const char *before_hdrs, size_t beforelen, const char *after_hdrs, size_t afterlen, const char *body, size_t bodylen, bool verify, struct buf *mi_out)

Build a Message-Instance value documenting the change from before_hdrs to after_hdrs, with hashes over after_hdrs and body. The body is hashed but never diffed: a caller that alters the body must not use this.

Parameters:

  • before_hdrs -- header block as it arrived

  • beforelen -- length of before_hdrs

  • after_hdrs -- header block as it stands now

  • afterlen -- length of after_hdrs

  • body -- message body, unchanged between the two blocks

  • bodylen -- length of body

  • verify -- hash before_hdrs too and check it against the highest-numbered Message-Instance already on the message, so that an earlier hop's undeclared change isn't attributed to this one

  • mi_out -- [out] the header field value, set only on DKIM2_MI_ADDED

Returns:

what was decided; DKIM2_MI_CHAIN_MISMATCH means verify failed

void dkim2_body_hash(const char *body, size_t bodylen, struct buf *b64)

§6.1 body hash: base64 of the sha256.

Parameters:

  • body -- message body

  • bodylen -- length of body

  • b64 -- [out] the encoded hash

void dkim2_header_hash(const char *hdrs, size_t len, struct buf *b64)

§6.2 header fields hash: base64 of the sha256.

Parameters:

  • hdrs -- header block, canonicalised and ordered internally

  • len -- length of hdrs

  • b64 -- [out] the encoded hash

char *dkim2_gen_recipes(const char *before_hdrs, size_t beforelen, const char *after_hdrs, size_t afterlen)

§5.1 Recipes to turn after_hdrs back into before_hdrs. Any difference that exists can always be expressed, since a "d" step can emit any value in any order.

Parameters:

  • before_hdrs -- header block to be reconstructed

  • beforelen -- length of before_hdrs

  • after_hdrs -- header block to reconstruct it from

  • afterlen -- length of after_hdrs

Returns:

a JSON string the caller frees, or NULL if no signed header field differs