viadkim/
lib.rs

1// viadkim – implementation of the DKIM specification
2// Copyright © 2022–2024 David Bürgin <dbuergin@gluet.ch>
3//
4// This program is free software: you can redistribute it and/or modify it under
5// the terms of the GNU General Public License as published by the Free Software
6// Foundation, either version 3 of the License, or (at your option) any later
7// version.
8//
9// This program is distributed in the hope that it will be useful, but WITHOUT
10// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11// FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
12// details.
13//
14// You should have received a copy of the GNU General Public License along with
15// this program. If not, see <https://www.gnu.org/licenses/>.
16
17//! A library implementing the *DomainKeys Identified Mail* (DKIM) specification
18//! described in [RFC 6376].
19//!
20//! This library provides both high-level APIs for signing and verifying, as
21//! well as low-level APIs that cover the various DKIM protocol areas.
22//!
23//! The high-level API can be used to sign email messages using DKIM signatures
24//! (module [`signer`]), and to verify such signatures (module [`verifier`]).
25//! Most users will want to deal with DKIM via these APIs. For convenience, all
26//! the relevant items are re-exported at the top level.
27//!
28//! The high-level API exposes various configuration options for both the
29//! signing and verification process. It is, however, closed, and not
30//! extensible. Instead, the low-level building blocks are provided in various
31//! additional modules. They contain basic helpers for cryptography,
32//! canonicalisation, encoding, etc. Users familiar with DKIM could use these
33//! building blocks to build their own signing and verification facilities.
34//!
35//! # Usage
36//!
37//! The types [`Signer`] and [`Verifier`] provide the entry points to signing
38//! and verifying with viadkim.
39//!
40//! See the examples for `Signer` and `Verifier` for basic usage.
41//!
42//! # Cargo features
43//!
44//! The feature **`hickory-resolver`** makes an implementation of trait
45//! [`LookupTxt`][crate::verifier::LookupTxt] available for the [Hickory DNS
46//! resolver]. `LookupTxt` is the abstraction used for DNS resolution during
47//! verification.
48//!
49//! The feature **`pre-rfc8301`** reverts cryptographic algorithm and key usage
50//! back to before [RFC 8301]: it lowers the minimum RSA key size to 512 bits,
51//! and enables the insecure, historic SHA-1 hash algorithm. In the API and
52//! implementation, wherever there is support for the SHA-256 hash algorithm,
53//! with this feature additional support for SHA-1 becomes available. This is a
54//! legacy compatibility feature, its use is discouraged.
55//!
56//! # Trace logging
57//!
58//! This library uses the [tracing] crate for internal trace logging. For
59//! insight into library operation, install a [tracing
60//! subscriber][tracing-subscriber] and enable logging at `trace` level.
61//!
62//! [RFC 6376]: https://www.rfc-editor.org/rfc/rfc6376
63//! [RFC 8301]: https://www.rfc-editor.org/rfc/rfc8301
64//! [Hickory DNS resolver]: https://crates.io/crates/hickory-resolver
65//! [tracing]: https://crates.io/crates/tracing
66//! [tracing-subscriber]: https://crates.io/crates/tracing-subscriber
67
68// Trace logging: logging about internal operation via `tracing::trace!` is done
69// only in the high-level API in modules `signer` and `verifier`.
70
71// Throughout, where RFC 6376 is quoted in comments, section numbers are
72// referred to with the symbol ‘§’ (also where RFC 6376 is not mentioned).
73
74pub mod canonicalize;
75pub mod crypto;
76pub mod header;
77pub mod message_hash;
78mod parse;
79pub mod quoted_printable;
80pub mod record;
81pub mod signature;
82pub mod signer;
83pub mod tag_list;
84mod util;
85pub mod verifier;
86
87pub use crate::{
88    crypto::SigningKey,
89    header::{FieldBody, FieldName, HeaderField, HeaderFields},
90    signature::{DomainName, Selector, SigningAlgorithm},
91    signer::{sign, RequestError, SignRequest, Signer, SigningError, SigningOutput, SigningResult},
92    util::{decode_base64, encode_base64, Base64Error, CanonicalStr},
93    verifier::{
94        verify, Config, DkimResult, VerificationError, VerificationResult, VerificationStatus,
95        Verifier,
96    },
97};
viadkim/lib.rs

viadkim/
lib.rs
