domain/crypto/mod.rs
1//! Cryptographic backends, key generation and import.
2//!
3//! This module is enabled by the `unstable-crypto` or `unstable-crypto-sign`
4//! feature flags. The `unstable-crypto` enables all features except for
5//! private key operations such as generation and signing. All features of
6//! this module are enabled with the `unstable-crypto-sign` feature flag.
7//!
8//! This crate supports OpenSSL and Ring for performing cryptography. These
9//! cryptographic backends are gated on the `openssl` and `ring` features,
10//! respectively. They offer mostly equivalent functionality, but OpenSSL
11//! supports a larger set of signing algorithms (and, for RSA keys, supports
12//! weaker key sizes). A
13#![cfg_attr(feature = "unstable-crypto-sign", doc = "[`sign`]")]
14#![cfg_attr(not(feature = "unstable-crypto-sign"), doc = "`sign`")]
15//! backend is provided for users that wish
16//! to use either or both backends at runtime.
17//!
18//! Each backend module (
19#![cfg_attr(
20 all(feature = "unstable-crypto-sign", feature = "openssl"),
21 doc = "[`openssl::sign`]"
22)]
23#![cfg_attr(
24 not(all(feature = "unstable-crypto-sign", feature = "openssl")),
25 doc = "`openssl::sign`"
26)]
27//! ,
28#![cfg_attr(
29 all(feature = "unstable-crypto-sign", feature = "ring"),
30 doc = "[`ring::sign`]"
31)]
32#![cfg_attr(
33 not(all(feature = "unstable-crypto-sign", feature = "ring")),
34 doc = "`ring::sign`"
35)]
36//! , and
37#![cfg_attr(feature = "unstable-crypto-sign", doc = "[`sign`]")]
38#![cfg_attr(not(feature = "unstable-crypto-sign"), doc = "`sign`")]
39//! )
40//! exposes a
41//! `KeyPair` type, representing a cryptographic key that can be used for
42//! signing, and a `generate()` function for creating new keys.
43//!
44//! Users can choose to bring their own cryptography by providing their own
45//! `KeyPair` type that implements the
46#![cfg_attr(feature = "unstable-crypto-sign", doc = "[`sign::SignRaw`]")]
47#![cfg_attr(not(feature = "unstable-crypto-sign"), doc = "`sign::SignRaw`")]
48//! trait.
49//!
50//! While each cryptographic backend can support a limited number of signature
51//! algorithms, even the types independent of a cryptographic backend (e.g.
52#![cfg_attr(
53 feature = "unstable-crypto-sign",
54 doc = "[`sign::SecretKeyBytes`]"
55)]
56#![cfg_attr(
57 not(feature = "unstable-crypto-sign"),
58 doc = "`sign::SecretKeyBytes`"
59)]
60//! and
61#![cfg_attr(
62 feature = "unstable-crypto-sign",
63 doc = "[`sign::GenerateParams`]"
64)]
65#![cfg_attr(
66 not(feature = "unstable-crypto-sign"),
67 doc = "`sign::GenerateParams`"
68)]
69//! ) support a limited
70//! number of algorithms. Even with custom cryptographic backends,
71//! this module can only
72//! support these algorithms.
73//!
74//! In addition to private key operations, this module provides the
75#![cfg_attr(
76 any(feature = "ring", feature = "openssl"),
77 doc = "[`common::PublicKey`]"
78)]
79#![cfg_attr(
80 not(any(feature = "ring", feature = "openssl")),
81 doc = "`common::PublicKey`"
82)]
83//! type for signature verification.
84//!
85//! The module also support computing message digests using the
86#![cfg_attr(
87 any(feature = "ring", feature = "openssl"),
88 doc = "[`common::DigestBuilder`]"
89)]
90#![cfg_attr(
91 not(any(feature = "ring", feature = "openssl")),
92 doc = "`common::DigestBuilder`"
93)]
94//! type.
95//!
96//! # Message digests
97//!
98//! Given some data compute a message digest.
99//!
100//! ```
101//! use domain::crypto::common::{DigestBuilder, DigestType};
102//!
103//! let input = "Hello World!";
104//! let mut ctx = DigestBuilder::new(DigestType::Sha256);
105//! ctx.update(input.as_bytes());
106//! ctx.finish().as_ref();
107//! ```
108//!
109//! # Signature verification
110//!
111//! Given some data, a signature, and a DNSKEY, the signature can be verified.
112//!
113//! ```no_run
114//! use domain::rdata::Dnskey;
115//! use domain::crypto::common::PublicKey;
116//! use domain::base::iana::SecurityAlgorithm;
117//!
118//! let keyraw = [0u8; 16];
119//! let input = "Hello World!";
120//! let bad_sig = [0u8; 16];
121//! let dnskey = Dnskey::new(256, 3, SecurityAlgorithm::ED25519, keyraw).unwrap();
122//! let public_key = PublicKey::from_dnskey(&dnskey).unwrap();
123//! let res = public_key.verify(input.as_bytes(), &bad_sig);
124//! println!("verify result: {res:?}");
125//! ```
126
127#![warn(missing_docs)]
128#![warn(clippy::missing_docs_in_private_items)]
129
130pub mod common;
131pub mod openssl;
132pub mod ring;
133pub mod sign;