oboron 0.7.0

Encryption and encoding library for developer ergonomics: prefix entropy, compact outputs, high performance
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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

#[cfg(feature = "keyless")]
use crate::constants::HARDCODED_KEY_BYTES;
use crate::{format::IntoFormat, Error, MasterKey};

/// An ObtextCodec implementation that takes format on enc operation and autodetects on dec operation.
/// Unlike all other implementations (Ob, ZrbcxC32, .. .) it does not have
/// a format stored internally.
///
/// This struct allows specifying the format (scheme + encoding) at enc call time,
/// and automatically detects both scheme and encoding on dec calls.
/// It is the only ObtextCodec implementation that does full format autodetection,
/// all other implementations can only autodetect the scheme (e.g., upbc),
/// but not the encoding (e.g., base32 or base64).
///
/// # Examples
///
/// ```rust
/// # fn main() -> Result<(), oboron::Error> {
/// # #[cfg(all(feature = "aasv", feature="mock"))]
/// # {
/// # use oboron::{Omnib, MOCK1_B64};
/// # let key = oboron::generate_key();
/// let omb = Omnib::new(&key)?;
///
/// // Encode with explicit format
/// let ot1 = omb.enc("hello", "aasv.c32")?; // using explicit string
/// let ot2 = omb.enc("world", MOCK1_B64)?; // using format constant
///
/// // autodec detects both scheme and encoding
/// let pt1 = omb.autodec(&ot1)?;
/// let pt2 = omb.autodec(&ot2)?;
/// # }
/// # Ok(())
/// # }
/// ```
pub struct Omnib {
    masterkey: MasterKey,
}

impl Omnib {
    /// Create a new Omnib instance with a base64 key.
    pub fn new(key_b64: &str) -> Result<Self, Error> {
        Ok(Self {
            masterkey: MasterKey::from_base64(key_b64)?,
        })
    }

    /// Create a new Omnib instance with hardcoded key (testing only).
    #[cfg(feature = "keyless")]
    pub fn new_keyless() -> Result<Self, Error> {
        Self::from_bytes(&HARDCODED_KEY_BYTES)
    }

    /// Encrypt and encode plaintext with the specified format.
    ///
    /// Accepts either a format string (`&str`) or a `Format` instance.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # fn main() -> Result<(), oboron::Error> {
    /// # #[cfg(feature = "aasv")]
    /// # {
    /// # use oboron::{Omnib, Format, Scheme, Encoding, AASV_B64};
    /// # let key = oboron::generate_key();
    /// let omb = Omnib::new(&key)?;
    ///
    /// // Using format string
    /// let ot1 = omb.enc("hello", "aasv.b64")?;
    ///
    /// // Using Format instance
    /// let ot2 = omb.enc("hello", Format::new(Scheme::Aasv, Encoding::B64))?;
    ///
    /// // Using format constant
    /// let ot3 = omb.enc("hello", AASV_B64)?;
    /// # }
    /// # Ok(())
    /// # }
    /// ```
    #[inline]
    pub fn enc(&self, plaintext: &str, format: impl IntoFormat) -> Result<String, Error> {
        let format = format.into_format()?;
        crate::enc::enc_to_format(plaintext, format, self.masterkey.key())
    }

    /// Decode and decrypt obtext with the specified format.
    ///
    /// Accepts either a format string (`&str`) or a `Format` instance.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # fn main() -> Result<(), oboron::Error> {
    /// # #[cfg(feature = "aasv")]
    /// # {
    /// # use oboron::{Omnib, Format, Scheme, Encoding};
    /// # let key = oboron::generate_key();
    /// # let omb = Omnib::new(&key)?;
    /// # let ot = omb.enc("test", "aasv.b64")?;
    /// // Using format string
    /// let pt1 = omb.dec(&ot, "aasv.b64")?;
    ///
    /// // Using Format instance
    /// let pt2 = omb.dec(&ot, Format::new(Scheme::Aasv, Encoding::B64))?;
    /// # }
    /// # Ok(())
    /// # }
    /// ```
    #[inline]
    pub fn dec(&self, obtext: &str, format: impl IntoFormat) -> Result<String, Error> {
        let format = format.into_format()?;
        crate::dec::dec_from_format(obtext, format, self.masterkey.key())
    }

    /// Decode+decrypt with automatic scheme and encoding detection.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # fn main() -> Result<(), oboron::Error> {
    /// # #[cfg(feature = "aasv")]
    /// # {
    /// # use oboron::Omnib;
    /// # let key = oboron::generate_key();
    /// # let omb = Omnib::new(&key)?;
    /// let ot = omb.enc("hello", "aasv.b64")?;
    /// let pt2 = omb.autodec(&ot)?;  // Autodetects ob:aasv.b64
    /// assert_eq!(pt2, "hello");
    /// # }
    /// # Ok(())
    /// # }
    /// ```
    pub fn autodec(&self, obtext: &str) -> Result<String, Error> {
        crate::dec_auto::dec_any_format(&self.masterkey, obtext)
    }

    /// Get the key used by this instance.
    pub fn key(&self) -> String {
        self.masterkey.key_base64()
    }

    #[cfg(feature = "hex-keys")]
    pub fn key_hex(&self) -> String {
        self.masterkey.key_hex()
    }

    #[cfg(feature = "bytes-keys")]
    pub fn key_bytes(&self) -> &[u8; 64] {
        self.masterkey.key_bytes()
    }

    // Alt input constructors ==========================================

    /// Create a new Omnib instance with a hex key.
    #[cfg(feature = "hex-keys")]
    pub fn from_key_hex(key_hex: &str) -> Result<Self, Error> {
        Ok(Self {
            masterkey: MasterKey::from_hex(key_hex)?,
        })
    }

    /// Create a new Omnib instance from raw bytes.
    pub fn from_bytes(key_bytes: &[u8; 64]) -> Result<Self, Error> {
        Ok(Self {
            masterkey: MasterKey::from_bytes(key_bytes)?,
        })
    }
}