age_setup/
lib.rs

1//! # age‑setup – Simple, Secure X25519 Key Pair Generation for Age
2//!
3//! This crate provides a one‑function API for generating X25519 key pairs
4//! compatible with the [**age** encryption tool](https://age-encryption.org/).
5//! Every generated key pair is automatically validated and protected by
6//! memory‑zeroisation, so you can focus on encrypting data without worrying
7//! about cryptographic details or secret leakage.
8//!
9//! ## Design
10//!
11//! The crate is organised into small, focused modules:
12//!
13//! | Module | Responsibility |
14//! |--------|----------------|
15//! | [`generator`] | The main entry point – generates a fresh [`KeyPair`]. |
16//! | [`keypair`]   | The [`KeyPair`] struct that holds a [`PublicKey`] and a [`SecretKey`]. |
17//! | [`public_key`] | A validated wrapper for age public keys (prefix `age1`). |
18//! | [`secret_key`] | A validated wrapper for age secret keys, with zeroisation on drop. |
19//! | [`security`]   | Low‑level memory‑zeroisation helpers (public, reusable). |
20//! | [`validation`] | Internal sanity checks used by [`PublicKey`] and [`SecretKey`]. |
21//! | [`errors`]     | All error types returned by the crate. |
22//!
23//! ## Quick start
24//!
25//! ```rust
26//! use age_setup::build_keypair;
27//!
28//! fn main() -> age_setup::Result<()> {
29//!     let kp = build_keypair()?;
30//!     println!("Public key: {}", kp.public);    // age1...
31//!     println!("Secret key: {}", kp.secret);    // [REDACTED]
32//!     Ok(())
33//! }
34//! ```
35//!
36//! ## Feature flags
37//!
38//! This crate does not expose any feature flags itself; it inherits the
39//! default TLS backend from the `age` crate (`rustls`). You can switch to
40//! native‑TLS by enabling the corresponding feature in `age`.
41
42pub mod errors;
43pub mod generator;
44pub mod keypair;
45pub mod public_key;
46pub mod secret_key;
47pub mod security;
48pub mod validation;
49
50// ---------------------------------------------------------------------------
51// Public re‑exports – everything you need to generate and work with key pairs
52// ---------------------------------------------------------------------------
53
54/// All error types used by the crate.
55///
56/// Re‑exports:
57/// - [`errors::Error`] – the main error enum (generation + validation).
58/// - [`errors::GenerationError`] – errors that can occur during key creation.
59/// - [`errors::ValidationError`] – errors for invalid public/secret key formats.
60/// - [`errors::Result`] – a convenience alias for `std::result::Result<T, Error>`.
61pub use errors::{Error, GenerationError, Result, ValidationError};
62
63/// The core function that generates a new X25519 key pair.
64///
65/// See [`generator::build_keypair`] for detailed documentation.
66pub use generator::build_keypair;
67
68/// A validated, memory‑safe age key pair.
69///
70/// Contains a [`PublicKey`] and a [`SecretKey`]. Obtained exclusively via
71/// [`build_keypair`].
72pub use keypair::KeyPair;
73
74/// A validated age public key that always starts with `age1`.
75///
76/// Safe to display, share, and clone.
77pub use public_key::PublicKey;
78
79/// A validated age secret key that is automatically zeroised when dropped.
80///
81/// Its [`Display`] and [`Debug`] implementations print `[REDACTED]` to prevent
82/// accidental exposure.
83pub use secret_key::SecretKey;
age_setup/lib.rs

age_setup/
lib.rs
