use aes_gcm::{
Aes256Gcm,
aead::{Aead, Generate, KeyInit, Nonce, Payload},
};
use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
use std::fmt;
use zeroize::Zeroize;
const ENVELOPE_PREFIX: &str = "RULLST";
const LEGACY_ENVELOPE_PREFIX: &str = "ENC";
const ENVELOPE_VERSION: &str = "v2";
const LEGACY_ENVELOPE_VERSION: &str = "v1";
const DEFAULT_KEY_ID: &str = "default";
const KEY_LENGTH: usize = 32;
const NONCE_LENGTH: usize = 12;
const TAG_LENGTH: usize = 16;
const MAX_KEY_ID_LENGTH: usize = 128;
const AAD_DOMAIN: &[u8] = b"rullst-security:field-encryption:aes-256-gcm";
pub struct VaultSecret<T: Zeroize> {
inner: T,
}
impl<T: Zeroize> VaultSecret<T> {
pub fn new(value: T) -> Self {
Self { inner: value }
}
pub fn expose_secret(&self) -> &T {
&self.inner
}
}
impl<T: Zeroize> Drop for VaultSecret<T> {
fn drop(&mut self) {
self.inner.zeroize();
}
}
impl<T: Zeroize> fmt::Debug for VaultSecret<T> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "VaultSecret(***REDACTED***)")
}
}
impl<T: Zeroize> fmt::Display for VaultSecret<T> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "***REDACTED***")
}
}
#[derive(Debug, thiserror::Error, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum VaultError {
#[error("AES-256-GCM keys must be exactly {expected} bytes; received {actual}")]
InvalidKeyLength {
expected: usize,
actual: usize,
},
#[error("field-encryption key identifiers cannot be empty")]
EmptyKeyId,
#[error("field-encryption key identifier is too long (maximum {maximum}, received {actual})")]
KeyIdTooLong {
maximum: usize,
actual: usize,
},
#[error(
"field-encryption key identifiers may contain only ASCII letters, digits, '.', '_' and '-'"
)]
InvalidKeyId,
#[error("invalid field-encryption envelope")]
InvalidEnvelope,
#[error("legacy irreversible field-encryption envelope '{version}' cannot be decrypted")]
LegacyIrreversibleEnvelope {
version: String,
},
#[error("unsupported field-encryption envelope version '{version}'")]
UnsupportedEnvelopeVersion {
version: String,
},
#[error("invalid base64 encoding in field-encryption envelope component '{component}'")]
InvalidEnvelopeEncoding {
component: &'static str,
},
#[error("invalid AES-GCM nonce length (expected {expected}, received {actual})")]
InvalidNonceLength {
expected: usize,
actual: usize,
},
#[error("encrypted payload is too short (minimum {minimum}, received {actual})")]
CiphertextTooShort {
minimum: usize,
actual: usize,
},
#[error("operating-system randomness is unavailable")]
RandomnessUnavailable,
#[error("AES-256-GCM encryption failed")]
EncryptionFailed,
#[error("AES-256-GCM authentication failed")]
AuthenticationFailed,
#[error("decrypted field is not valid UTF-8")]
InvalidPlaintextUtf8,
#[error("field-encryption key '{key_id}' was not found in the keyring")]
KeyNotFound {
key_id: String,
},
}
impl From<VaultError> for crate::error::SecurityError {
fn from(error: VaultError) -> Self {
Self::VaultError(error.to_string())
}
}
pub struct FieldEncryptor;
impl FieldEncryptor {
pub const KEY_LENGTH: usize = KEY_LENGTH;
pub const ENVELOPE_VERSION: &'static str = ENVELOPE_VERSION;
pub fn encrypt(plain_text: &str, secret_key: impl AsRef<[u8]>) -> Result<String, VaultError> {
Self::encrypt_with_aad(plain_text, secret_key, b"")
}
pub fn encrypt_with_aad(
plain_text: &str,
secret_key: impl AsRef<[u8]>,
aad: &[u8],
) -> Result<String, VaultError> {
Self::encrypt_with_key_id(plain_text, secret_key, DEFAULT_KEY_ID, aad)
}
pub fn encrypt_with_key_id(
plain_text: &str,
secret_key: impl AsRef<[u8]>,
key_id: impl Into<String>,
aad: &[u8],
) -> Result<String, VaultError> {
let key_id = key_id.into();
validate_key_id(&key_id)?;
let cipher = create_cipher(secret_key.as_ref())?;
let nonce =
Nonce::<Aes256Gcm>::try_generate().map_err(|_| VaultError::RandomnessUnavailable)?;
let authenticated_data = build_authenticated_data(&key_id, aad);
let ciphertext = cipher
.encrypt(
&nonce,
Payload {
msg: plain_text.as_bytes(),
aad: &authenticated_data,
},
)
.map_err(|_| VaultError::EncryptionFailed)?;
Ok(format!(
"{ENVELOPE_PREFIX}:{ENVELOPE_VERSION}:{key_id}:{}:{}",
URL_SAFE_NO_PAD.encode(nonce),
URL_SAFE_NO_PAD.encode(ciphertext)
))
}
pub fn decrypt(cipher_text: &str, secret_key: impl AsRef<[u8]>) -> Result<String, VaultError> {
Self::decrypt_with_aad(cipher_text, secret_key, b"")
}
pub fn decrypt_with_aad(
cipher_text: &str,
secret_key: impl AsRef<[u8]>,
aad: &[u8],
) -> Result<String, VaultError> {
let envelope = parse_envelope(cipher_text)?;
decrypt_envelope(&envelope, secret_key.as_ref(), aad)
}
pub fn decrypt_with_keyring(
cipher_text: &str,
keyring: &[(&str, &[u8])],
aad: &[u8],
) -> Result<String, VaultError> {
let envelope = parse_envelope(cipher_text)?;
let key = keyring
.iter()
.find_map(|(key_id, key)| (*key_id == envelope.key_id).then_some(*key))
.ok_or_else(|| VaultError::KeyNotFound {
key_id: envelope.key_id.to_string(),
})?;
decrypt_envelope(&envelope, key, aad)
}
pub fn envelope_key_id(cipher_text: &str) -> Result<&str, VaultError> {
Ok(parse_envelope(cipher_text)?.key_id)
}
}
struct ParsedEnvelope<'a> {
key_id: &'a str,
nonce: Vec<u8>,
ciphertext: Vec<u8>,
}
fn create_cipher(secret_key: &[u8]) -> Result<Aes256Gcm, VaultError> {
if secret_key.len() != KEY_LENGTH {
return Err(VaultError::InvalidKeyLength {
expected: KEY_LENGTH,
actual: secret_key.len(),
});
}
Aes256Gcm::new_from_slice(secret_key).map_err(|_| VaultError::InvalidKeyLength {
expected: KEY_LENGTH,
actual: secret_key.len(),
})
}
fn validate_key_id(key_id: &str) -> Result<(), VaultError> {
if key_id.is_empty() {
return Err(VaultError::EmptyKeyId);
}
if key_id.len() > MAX_KEY_ID_LENGTH {
return Err(VaultError::KeyIdTooLong {
maximum: MAX_KEY_ID_LENGTH,
actual: key_id.len(),
});
}
if !key_id.bytes().all(is_valid_key_id_byte) {
return Err(VaultError::InvalidKeyId);
}
Ok(())
}
const fn is_valid_key_id_byte(byte: u8) -> bool {
byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-')
}
fn build_authenticated_data(key_id: &str, caller_aad: &[u8]) -> Vec<u8> {
let mut aad = Vec::new();
aad.extend_from_slice(AAD_DOMAIN);
aad.push(0);
aad.extend_from_slice(ENVELOPE_VERSION.as_bytes());
aad.push(0);
aad.extend_from_slice(key_id.as_bytes());
aad.push(0);
aad.extend_from_slice(caller_aad);
aad
}
fn parse_envelope(cipher_text: &str) -> Result<ParsedEnvelope<'_>, VaultError> {
let mut fields = cipher_text.split(':');
if !matches!(
fields.next(),
Some(ENVELOPE_PREFIX | LEGACY_ENVELOPE_PREFIX)
) {
return Err(VaultError::InvalidEnvelope);
}
let version = fields.next().ok_or(VaultError::InvalidEnvelope)?;
if version == LEGACY_ENVELOPE_VERSION {
return Err(VaultError::LegacyIrreversibleEnvelope {
version: version.to_string(),
});
}
if version != ENVELOPE_VERSION {
return Err(VaultError::UnsupportedEnvelopeVersion {
version: version.to_string(),
});
}
let key_id = fields.next().ok_or(VaultError::InvalidEnvelope)?;
let encoded_nonce = fields.next().ok_or(VaultError::InvalidEnvelope)?;
let encoded_ciphertext = fields.next().ok_or(VaultError::InvalidEnvelope)?;
if fields.next().is_some() {
return Err(VaultError::InvalidEnvelope);
}
validate_key_id(key_id)?;
let nonce = URL_SAFE_NO_PAD
.decode(encoded_nonce)
.map_err(|_| VaultError::InvalidEnvelopeEncoding { component: "nonce" })?;
if nonce.len() != NONCE_LENGTH {
return Err(VaultError::InvalidNonceLength {
expected: NONCE_LENGTH,
actual: nonce.len(),
});
}
let ciphertext = URL_SAFE_NO_PAD.decode(encoded_ciphertext).map_err(|_| {
VaultError::InvalidEnvelopeEncoding {
component: "ciphertext",
}
})?;
if ciphertext.len() < TAG_LENGTH {
return Err(VaultError::CiphertextTooShort {
minimum: TAG_LENGTH,
actual: ciphertext.len(),
});
}
Ok(ParsedEnvelope {
key_id,
nonce,
ciphertext,
})
}
fn decrypt_envelope(
envelope: &ParsedEnvelope<'_>,
secret_key: &[u8],
aad: &[u8],
) -> Result<String, VaultError> {
let cipher = create_cipher(secret_key)?;
let nonce = Nonce::<Aes256Gcm>::try_from(envelope.nonce.as_slice()).map_err(|_| {
VaultError::InvalidNonceLength {
expected: NONCE_LENGTH,
actual: envelope.nonce.len(),
}
})?;
let authenticated_data = build_authenticated_data(envelope.key_id, aad);
let plaintext = cipher
.decrypt(
&nonce,
Payload {
msg: &envelope.ciphertext,
aad: &authenticated_data,
},
)
.map_err(|_| VaultError::AuthenticationFailed)?;
match String::from_utf8(plaintext) {
Ok(plaintext) => Ok(plaintext),
Err(error) => {
let mut plaintext = error.into_bytes();
plaintext.zeroize();
Err(VaultError::InvalidPlaintextUtf8)
}
}
}
#[cfg(test)]
mod tests;
#[cfg(kani)]
#[cfg_attr(mutants, mutants::skip)]
mod kani_proofs {
use super::*;
#[kani::proof]
fn proof_key_id_byte_policy() {
let byte: u8 = kani::any();
let expected = byte.is_ascii_uppercase()
|| byte.is_ascii_lowercase()
|| byte.is_ascii_digit()
|| matches!(byte, b'.' | b'_' | b'-');
assert_eq!(is_valid_key_id_byte(byte), expected);
}
}