package dkim

  1. Overview
  2. Docs
Implementation of DKIM in OCaml

Install 

dune-project
 Dependency

github.com Readme Changelog MIT License Edit opam file Versions (2)

Authors

  1. R
    Romain Calascibetta <romain.calascibetta@gmail.com>

Maintainers

  1. R
    Romain Calascibetta <romain.calascibetta@gmail.com>

Sources

dkim-0.6.0.tbz
sha256=ac1c14a5a323685feae840cc2b70501b02d976699c765b38ba9055483eeed7d4
sha512=7ec76d26136c2e285ecffa420a8f4b49dfae67dca7a94178654f3ad873bc01dbb1bb8b75d00c5d83f30f13f9e592fbf47d08612cf9120c4edad25260e5c43abe

doc/dkim/Dkim/index.html

Module DkimSource

Sourcemodule Sigs : sig ... end
Sourcetype (+'a, 'err) or_err = ('a, [> `Msg of string ] as 'err) result
Sourcetype newline =
  1. | CRLF
  2. | LF
Sourcetype map
Sourcetype signed
Sourcetype unsigned
Sourcetype 'a dkim
Sourcetype server
Sourcetype body
Sourceval pp_dkim : 'a dkim Fmt.t
Sourceval pp_server : server Fmt.t
Sourceval equal_server : server -> server -> bool
Sourcetype extracted = {
  1. dkim_fields : (Mrmime.Field_name.t * Unstrctrd.t * map) list;
  2. fields : (Mrmime.Field_name.t * Unstrctrd.t) list;
  3. prelude : string;
}
Sourceval extract_dkim : ?newline:newline -> ?size:int -> 'flow -> 't Sigs.state -> (module Sigs.FLOW with type backend = 't and type flow = 'flow) -> ((extracted, _) or_err, 't) Sigs.io

extract_dkim ?newline flow state (module Flow) reads flow with Input/Output scheduler represented by state and primitives implemented by (module Flow). ?newline specifies kind of contents (CRLF from network or LF from database like maildir).

It tries to extract DKIM-Signature fields with values, others fields and give a prelude of the body of the email (given by flow).

Sourceval post_process_dkim : map -> (signed dkim, _) or_err

post_process_dkim map from an already parsed DKIM-Signature represented by map, we compute a post process analyze (check required/optional well formed values) and return a safe representation of DKIM-Signature, dkim, which can be used by verify.

Sourceval selector : 'a dkim -> [ `raw ] Domain_name.t

selector dkim returns the selector of the DKIM-Signature field.

Selectors might indicate the names of office locations, the signing date, or even an individual user.

Sourceval domain : 'a dkim -> [ `raw ] Domain_name.t

domain dkim returns the domain which signed the mail.

Sourceval fields : 'a dkim -> Mrmime.Field_name.t list
Sourceval domain_name : 'a dkim -> ([ `raw ] Domain_name.t, [> `Msg of string ]) result

domain_name dkim returns the full domain-name where the DNS TXT record can be get.

Sourceval extract_server : 't -> 'backend Sigs.state -> (module Sigs.DNS with type backend = 'backend and type t = 't) -> 'a dkim -> ((map, _) or_err, 'backend) Sigs.io

extract_server dns state (module Dns) dkim gets public-key noticed by dkim from authority server over DNS protocol (with Input/Output scheduler represented by state and primitives implemented by (module Dns)).

Sourceval post_process_server : map -> (server, _) or_err

post_process_server map from an already parsed TXT record (given by a DNS service) represented by map, we compute a post-process analyze (check required/optional well formed values) and return a safe representation of the public-key, server, which can be used by verify.

Sourceval extract_body : ?newline:newline -> 'flow -> 'backend Sigs.state -> (module Sigs.FLOW with type backend = 'backend and type flow = 'flow) -> prelude:string -> simple:(string option -> unit) -> relaxed:(string option -> unit) -> [ `Consume of (unit, 'backend) Sigs.io ]

extract_body ?newline flow state (module Flow) ~prelude extracts a thin representation of the body of the email. It should follow extract_dkim with prelude and with flow, state, (module Flow) and ?newline arguments. It returns a body which can be used by verify.

Sourceval expired : epoch:(unit -> int64) -> signed dkim -> bool

expired ~epoch dkim returns true if the signature is expired. verify with the given dkim will returns true but it does not process the real verification, which will obviously fails otherwise due to the obsolete public/private key available by the signer.

Sourcetype ('a, 'backend) stream = unit -> ('a option, 'backend) Sigs.io
Sourceval verify : 'backend Sigs.state -> epoch:(unit -> int64) -> (Mrmime.Field_name.t * Unstrctrd.t) list -> (Mrmime.Field_name.t * Unstrctrd.t) -> simple:(string, 'backend) stream -> relaxed:(string, 'backend) stream -> signed dkim -> server -> (bool, 'backend) Sigs.io

verify fields (dkim_field_name, dkim_value) dkim server body verifies the given email (represented by body. fields and (dkim_field_name, dkim_value)) with a signature dkim and the public-key represented by server.

It returns true if signature is correct or false if something is wrong.

Establishing the exact cause of a failed verification if difficult:

  • selector can not be found.
  • Public-key was updated.
  • DKIM-Signature is not well-formed.
  • etc.

At least, dkim provides some logs to highlight where the verification failed. Finally, the given email should be treated the same as all unverified email - regardless of whether or not it looks like it was signed.

Sourcetype algorithm = [
  1. | `RSA
]
Sourcetype hash = [
  1. | `SHA1
  2. | `SHA256
]
Sourcetype canonicalization = [
  1. | `Simple
  2. | `Relaxed
]
Sourcetype query = [
  1. | `DNS of [ `TXT ]
]
Sourceval v : ?version:int -> ?fields:Mrmime.Field_name.t list -> selector:[ `raw ] Domain_name.t -> ?algorithm:algorithm -> ?hash:hash -> ?canonicalization:(canonicalization * canonicalization) -> ?length:int -> ?query:query -> ?timestamp:int64 -> ?expiration:int64 -> [ `raw ] Domain_name.t -> unsigned dkim
Sourcemodule Encoder : sig ... end
Sourceval sign : key:Mirage_crypto_pk.Rsa.priv -> ?newline:newline -> 'flow -> 't Sigs.state -> both:'t Sigs.both -> (module Sigs.FLOW with type backend = 't and type flow = 'flow) -> (module Sigs.STREAM with type backend = 't) -> unsigned dkim -> (signed dkim, 't) Sigs.io

sign ~key ~newline flow state (module Flow) dkim returns a signed dkim value which can be serialized into the given email (represented by flow). According to dkim, it will sign some fields and the body.

The returned signed dkim can be serialized with:

  let dkim_field = Prettym.to_string Dkim.Encoder.as_field dkim
Sourceval server_of_dkim : key:Mirage_crypto_pk.Rsa.priv -> 'a dkim -> server

server_of_dkim returns the required server value from a dkim value. The user is able to store the associated server value into the DNS TXT record with server_to_string such as:

  let str = Dkim.server_to_string (Dkim.server_of_dkim ~key dkim) in
  nsupdate (Dkim.domain_name dkim) `TXT str
Sourceval server_to_string : server -> string

server_to_string server generates a string from the given server value to be able to store the string into the DNS TXT record.

/

Sourceval remove_signature_of_raw_dkim : Unstrctrd.t -> Unstrctrd.t
Sourceval relaxed_field_canonicalization : Mrmime.Field_name.t -> Unstrctrd.t -> (string -> unit) -> unit
Sourcemodule Body : sig ... end
Sourceval parse_dkim_field_value : Unstrctrd.t -> (map, [> `Msg of string ]) result
Sourceval field_dkim_signature : Mrmime.Field_name.t