trelent-hyok 0.1.12

A Rust library implementing Hold Your Own Key (HYOK) encryption patterns with support for multiple cloud providers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! DEK generation and management.
//!
//! This module provides a flexible system for generating Data Encryption Keys (DEKs)
//! using different strategies:
//!
//! - Fixed-length cryptographically secure random keys
//! - String-based keys for testing (debug feature)
//! - Custom key generation implementations
//!
//! The module ensures consistent key generation across the library while allowing
//! for customization when needed.

pub mod key_generator;

use crate::error::generator::GeneratorError;

use self::key_generator::DEKKeyGenerator;

#[cfg(feature = "debug")]
use crate::dek::generator::key_generator::string::StringGenerator;
use key_generator::{custom::CustomGenerator, fixed::FixedLengthGenerator};

/// A trait for types that can generate Data Encryption Keys (DEK).
///
/// This trait provides a higher-level interface compared to `DEKKeyGenerator`,
/// with additional error handling and validation. Implementations should ensure:
///
/// - Secure key generation
/// - Proper error handling
/// - Consistent key formats
/// - Appropriate key lengths
///
/// # Example
/// ```no_run
/// use hyokashi::{DEKGeneratorTrait, GeneratorError};
///
/// struct MyGenerator;
///
/// impl DEKGeneratorTrait for MyGenerator {
///     fn new_dek(&self) -> Result<Vec<u8>, GeneratorError> {
///         // Implement secure key generation...
///         # Ok(vec![])
///     }
/// }
/// ```
pub trait DEKGeneratorTrait {
    /// Generates a new Data Encryption Key.
    ///
    /// # Errors
    ///
    /// Returns a `GeneratorError` if key generation fails due to:
    /// - Insufficient entropy
    /// - Invalid parameters
    /// - System errors
    fn new_dek(&self) -> Result<Vec<u8>, GeneratorError>;
}

/// Available strategies for generating Data Encryption Keys.
///
/// This enum provides different approaches to key generation:
///
/// - `Fixed`: Cryptographically secure random keys of a specified length
/// - `String`: String-based keys for testing (requires "debug" feature)
/// - `Custom`: User-defined key generation logic
///
/// # Feature Flags
///
/// - `debug`: Enables string-based key generation for testing
///
/// # Security
///
/// For production use:
/// - Prefer the `Fixed` variant with appropriate key lengths
/// - Avoid the `String` variant (testing only)
/// - Ensure custom implementations follow cryptographic best practices
///
/// # Example
/// ```no_run
/// use hyokashi::DEKGenerator;
///
/// // Create a fixed-length key generator (recommended for production)
/// let generator = DEKGenerator::Fixed(FixedLengthGenerator::new(32));
///
/// // Generate a new key
/// let key = generator.new_dek()?;
/// assert_eq!(key.len(), 32);
/// ```
pub enum DEKGenerator {
    /// A generator that produces random keys of a fixed length
    Fixed(FixedLengthGenerator),
    #[cfg(feature = "debug")]
    /// A debug-only generator that converts strings to keys
    String(StringGenerator),
    /// A generator with custom key generation logic
    Custom(CustomGenerator),
}

impl DEKGenerator {
    /// Generates a new Data Encryption Key using the selected generation strategy.
    ///
    /// # Errors
    ///
    /// Returns a `GeneratorError` if key generation fails. This could be due to:
    /// - Random number generator failure for `Fixed` variant
    /// - Custom generator errors for `Custom` variant
    pub fn new_dek(&self) -> Result<Vec<u8>, GeneratorError> {
        (
            match self {
                DEKGenerator::Fixed(generator) => generator.generate_key(),
                #[cfg(feature = "debug")]
                DEKGenerator::String(generator) => generator.generate_key(),
                DEKGenerator::Custom(generator) => generator.generate_key(),
            }
        ).map_err(|e| GeneratorError::GenerateKeyError(e))
    }
}