use crate::{CanaryKind, Error, Result, json_escape};
use rand::seq::SliceRandom;
use rand::{Rng, RngExt};
use std::time::{SystemTime, UNIX_EPOCH};
mod encoding {
const BASE64URL_ALPHABET: &[u8; 64] =
b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
pub(super) fn hex(input: &[u8]) -> String {
const HEX_ALPHABET: &[u8; 16] = b"0123456789abcdef";
let mut output = String::with_capacity(input.len() * 2);
for byte in input {
output.push(HEX_ALPHABET[(byte >> 4) as usize] as char);
output.push(HEX_ALPHABET[(byte & 0x0f) as usize] as char);
}
output
}
pub(super) fn base64url(input: &[u8]) -> String {
let mut output = String::with_capacity(input.len().div_ceil(3) * 4);
for chunk in input.chunks(3) {
let b0 = u32::from(chunk[0]);
let b1 = u32::from(*chunk.get(1).unwrap_or(&0));
let b2 = u32::from(*chunk.get(2).unwrap_or(&0));
let triple = (b0 << 16) | (b1 << 8) | b2;
output.push(BASE64URL_ALPHABET[((triple >> 18) & 0x3f) as usize] as char);
output.push(BASE64URL_ALPHABET[((triple >> 12) & 0x3f) as usize] as char);
if chunk.len() > 1 {
output.push(BASE64URL_ALPHABET[((triple >> 6) & 0x3f) as usize] as char);
}
if chunk.len() > 2 {
output.push(BASE64URL_ALPHABET[(triple & 0x3f) as usize] as char);
}
}
output
}
}
pub trait Generator: Send + Sync {
fn generate(&self) -> Result<String>;
}
pub fn generate(kind: &CanaryKind) -> Result<String> {
generate_using(kind, &mut rand::rng())
}
pub fn generate_using<R: Rng>(kind: &CanaryKind, rng: &mut R) -> Result<String> {
match kind {
CanaryKind::Password => Ok(PasswordGenerator::default().generate_using(rng)),
CanaryKind::ApiKey => Ok(ApiKeyGenerator::default().generate_using(rng)),
CanaryKind::Token => Ok(TokenGenerator::default().generate_using(rng)),
CanaryKind::Jwt => Ok(JwtGenerator::default().generate_using(rng)),
CanaryKind::DbUrl => Ok(DbUrlGenerator::default().generate_using(rng)),
CanaryKind::PrivateKey => Ok(PrivateKeyGenerator::default().generate_using(rng)),
CanaryKind::Custom(name) => {
let label = sanitize_label(name);
let prefix = format!("ct_{label}");
let generator = CustomGenerator::new(prefix, 16)?;
Ok(generator.generate_using(rng))
}
}
}
const PASSWORD_UPPER: &[u8] = b"ABCDEFGHJKLMNPQRSTUVWXYZ";
const PASSWORD_LOWER: &[u8] = b"abcdefghijkmnopqrstuvwxyz";
const PASSWORD_DIGITS: &[u8] = b"23456789";
const PASSWORD_SYMBOLS: &[u8] = b"!@#$%^&*()-_=+[]{}";
const PASSWORD_ALL: &[u8] =
b"ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789!@#$%^&*()-_=+[]{}";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PasswordGenerator {
length: usize,
}
impl PasswordGenerator {
pub const MIN_LENGTH: usize = 16;
pub const MAX_LENGTH: usize = 256;
pub fn new(length: usize) -> Result<Self> {
validate_length(length, Self::MIN_LENGTH, Self::MAX_LENGTH)?;
Ok(Self { length })
}
#[must_use]
pub fn length(&self) -> usize {
self.length
}
#[must_use]
pub fn generate_using<R: Rng>(&self, rng: &mut R) -> String {
let mut chars = Vec::with_capacity(self.length);
chars.push(random_char(rng, PASSWORD_UPPER));
chars.push(random_char(rng, PASSWORD_LOWER));
chars.push(random_char(rng, PASSWORD_DIGITS));
chars.push(random_char(rng, PASSWORD_SYMBOLS));
for _ in 4..self.length {
chars.push(random_char(rng, PASSWORD_ALL));
}
chars.shuffle(rng);
String::from_utf8(chars).expect("password alphabet contains only ASCII bytes")
}
}
impl Default for PasswordGenerator {
fn default() -> Self {
Self { length: 24 }
}
}
impl Generator for PasswordGenerator {
fn generate(&self) -> Result<String> {
Ok(self.generate_using(&mut rand::rng()))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ApiKeyGenerator {
prefix: String,
bytes: usize,
}
impl ApiKeyGenerator {
pub const MIN_BYTES: usize = 16;
pub const MAX_BYTES: usize = 64;
pub fn new(prefix: impl Into<String>, bytes: usize) -> Result<Self> {
validate_byte_count(bytes, Self::MIN_BYTES, Self::MAX_BYTES)?;
Ok(Self {
prefix: prefix.into(),
bytes,
})
}
#[must_use]
pub fn prefix(&self) -> &str {
&self.prefix
}
#[must_use]
pub fn bytes(&self) -> usize {
self.bytes
}
#[must_use]
pub fn generate_using<R: Rng>(&self, rng: &mut R) -> String {
let mut random_bytes = vec![0u8; self.bytes];
rng.fill_bytes(&mut random_bytes);
let encoded = encoding::hex(&random_bytes);
if self.prefix.is_empty() {
encoded
} else {
format!("{}_{}", self.prefix, encoded)
}
}
}
impl Default for ApiKeyGenerator {
fn default() -> Self {
Self {
prefix: "ct_ak".to_owned(),
bytes: 24,
}
}
}
impl Generator for ApiKeyGenerator {
fn generate(&self) -> Result<String> {
Ok(self.generate_using(&mut rand::rng()))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TokenGenerator {
prefix: String,
bytes: usize,
}
impl TokenGenerator {
pub const MIN_BYTES: usize = 16;
pub const MAX_BYTES: usize = 64;
pub fn new(prefix: impl Into<String>, bytes: usize) -> Result<Self> {
validate_byte_count(bytes, Self::MIN_BYTES, Self::MAX_BYTES)?;
Ok(Self {
prefix: prefix.into(),
bytes,
})
}
#[must_use]
pub fn prefix(&self) -> &str {
&self.prefix
}
#[must_use]
pub fn bytes(&self) -> usize {
self.bytes
}
#[must_use]
pub fn generate_using<R: Rng>(&self, rng: &mut R) -> String {
let mut random_bytes = vec![0u8; self.bytes];
rng.fill_bytes(&mut random_bytes);
let encoded = encoding::base64url(&random_bytes);
if self.prefix.is_empty() {
encoded
} else {
format!("{}_{}", self.prefix, encoded)
}
}
}
impl Default for TokenGenerator {
fn default() -> Self {
Self {
prefix: "ct_tok".to_owned(),
bytes: 32,
}
}
}
impl Generator for TokenGenerator {
fn generate(&self) -> Result<String> {
Ok(self.generate_using(&mut rand::rng()))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct JwtGenerator {
issuer: String,
subject: String,
ttl_secs: u64,
}
impl JwtGenerator {
#[must_use]
pub fn new(issuer: impl Into<String>, subject: impl Into<String>, ttl_secs: u64) -> Self {
Self {
issuer: issuer.into(),
subject: subject.into(),
ttl_secs,
}
}
#[must_use]
pub fn issuer(&self) -> &str {
&self.issuer
}
#[must_use]
pub fn subject(&self) -> &str {
&self.subject
}
#[must_use]
pub fn ttl_secs(&self) -> u64 {
self.ttl_secs
}
#[must_use]
pub fn generate_using<R: Rng>(&self, rng: &mut R) -> String {
let header = r#"{"alg":"HS256","typ":"JWT"}"#;
let mut jti_bytes = [0u8; 16];
rng.fill_bytes(&mut jti_bytes);
let jti = encoding::hex(&jti_bytes);
let now = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_secs();
let exp = now.saturating_add(self.ttl_secs);
let payload = format!(
r#"{{"iss":"{}","sub":"{}","jti":"{}","iat":{},"exp":{},"canarytrap":true}}"#,
json_escape(&self.issuer),
json_escape(&self.subject),
jti,
now,
exp,
);
let mut signature_bytes = [0u8; 32];
rng.fill_bytes(&mut signature_bytes);
format!(
"{}.{}.{}",
encoding::base64url(header.as_bytes()),
encoding::base64url(payload.as_bytes()),
encoding::base64url(&signature_bytes),
)
}
}
impl Default for JwtGenerator {
fn default() -> Self {
Self {
issuer: "canarytrap".to_owned(),
subject: "canary".to_owned(),
ttl_secs: 3600,
}
}
}
impl Generator for JwtGenerator {
fn generate(&self) -> Result<String> {
Ok(self.generate_using(&mut rand::rng()))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DbUrlGenerator {
scheme: String,
user: String,
host: String,
port: u16,
database: String,
password_bytes: usize,
}
impl DbUrlGenerator {
pub const MIN_PASSWORD_BYTES: usize = 16;
pub const MAX_PASSWORD_BYTES: usize = 64;
pub fn new(
scheme: impl Into<String>,
user: impl Into<String>,
host: impl Into<String>,
port: u16,
database: impl Into<String>,
password_bytes: usize,
) -> Result<Self> {
validate_byte_count(
password_bytes,
Self::MIN_PASSWORD_BYTES,
Self::MAX_PASSWORD_BYTES,
)?;
Ok(Self {
scheme: scheme.into(),
user: user.into(),
host: host.into(),
port,
database: database.into(),
password_bytes,
})
}
#[must_use]
pub fn generate_using<R: Rng>(&self, rng: &mut R) -> String {
let mut password_bytes = vec![0u8; self.password_bytes];
rng.fill_bytes(&mut password_bytes);
let password = encoding::hex(&password_bytes);
format!(
"{scheme}://{user}:{password}@{host}:{port}/{database}",
scheme = self.scheme,
user = self.user,
password = password,
host = self.host,
port = self.port,
database = self.database,
)
}
}
impl Default for DbUrlGenerator {
fn default() -> Self {
Self {
scheme: "postgres".to_owned(),
user: "canary".to_owned(),
host: "localhost".to_owned(),
port: 5432,
database: "canary".to_owned(),
password_bytes: 16,
}
}
}
impl Generator for DbUrlGenerator {
fn generate(&self) -> Result<String> {
Ok(self.generate_using(&mut rand::rng()))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PrivateKeyGenerator {
bytes: usize,
line_width: usize,
}
impl PrivateKeyGenerator {
pub const MIN_BYTES: usize = 16;
pub const MAX_BYTES: usize = 128;
pub fn new(bytes: usize, line_width: usize) -> Result<Self> {
validate_byte_count(bytes, Self::MIN_BYTES, Self::MAX_BYTES)?;
if line_width == 0 {
return Err(Error::InvalidLength(line_width));
}
Ok(Self { bytes, line_width })
}
#[must_use]
pub fn generate_using<R: Rng>(&self, rng: &mut R) -> String {
let mut random_bytes = vec![0u8; self.bytes];
rng.fill_bytes(&mut random_bytes);
let hex_body = encoding::hex(&random_bytes);
let mut body = String::with_capacity(hex_body.len() + hex_body.len() / self.line_width);
for (index, ch) in hex_body.chars().enumerate() {
if index > 0 && index % self.line_width == 0 {
body.push('\n');
}
body.push(ch);
}
format!(
"-----BEGIN FAKE CANARY PRIVATE KEY-----\n{body}\n-----END FAKE CANARY PRIVATE KEY-----\n"
)
}
}
impl Default for PrivateKeyGenerator {
fn default() -> Self {
Self {
bytes: 32,
line_width: 64,
}
}
}
impl Generator for PrivateKeyGenerator {
fn generate(&self) -> Result<String> {
Ok(self.generate_using(&mut rand::rng()))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CustomGenerator {
prefix: String,
bytes: usize,
}
impl CustomGenerator {
pub const MIN_BYTES: usize = 16;
pub const MAX_BYTES: usize = 64;
pub fn new(prefix: impl Into<String>, bytes: usize) -> Result<Self> {
validate_byte_count(bytes, Self::MIN_BYTES, Self::MAX_BYTES)?;
Ok(Self {
prefix: prefix.into(),
bytes,
})
}
#[must_use]
pub fn generate_using<R: Rng>(&self, rng: &mut R) -> String {
let mut random_bytes = vec![0u8; self.bytes];
rng.fill_bytes(&mut random_bytes);
let encoded = encoding::hex(&random_bytes);
if self.prefix.is_empty() {
encoded
} else {
format!("{}_{}", self.prefix, encoded)
}
}
}
impl Default for CustomGenerator {
fn default() -> Self {
Self {
prefix: "ct_custom".to_owned(),
bytes: 16,
}
}
}
impl Generator for CustomGenerator {
fn generate(&self) -> Result<String> {
Ok(self.generate_using(&mut rand::rng()))
}
}
fn random_char<R: Rng>(rng: &mut R, alphabet: &'static [u8]) -> u8 {
let index = rng.random_range(0..alphabet.len());
alphabet[index]
}
fn validate_length(value: usize, min: usize, max: usize) -> Result<()> {
if value < min || value > max {
return Err(Error::InvalidLength(value));
}
Ok(())
}
fn validate_byte_count(value: usize, min: usize, max: usize) -> Result<()> {
if value < min || value > max {
return Err(Error::InvalidByteCount(value));
}
Ok(())
}
fn sanitize_label(input: &str) -> String {
let sanitized: String = input
.chars()
.filter_map(|ch| match ch {
'a'..='z' | 'A'..='Z' | '0'..='9' | '-' | '_' => Some(ch.to_ascii_lowercase()),
_ => None,
})
.collect();
if sanitized.is_empty() {
"custom".to_owned()
} else {
sanitized
}
}
#[cfg(test)]
mod tests {
use super::encoding;
use super::{
ApiKeyGenerator, CustomGenerator, DbUrlGenerator, Generator, JwtGenerator,
PasswordGenerator, PrivateKeyGenerator, TokenGenerator, generate, generate_using,
};
use crate::{CanaryKind, Error};
use rand::{SeedableRng, rngs::StdRng};
use std::collections::HashSet;
fn seeded_rng() -> StdRng {
StdRng::seed_from_u64(42)
}
#[test]
fn hex_encoding_is_lowercase() {
assert_eq!(encoding::hex(&[]), "");
assert_eq!(encoding::hex(&[0x00]), "00");
assert_eq!(encoding::hex(&[0xff]), "ff");
assert_eq!(encoding::hex(&[0x01, 0x23, 0xab, 0xcd]), "0123abcd");
}
#[test]
fn base64url_encoding_matches_known_vectors() {
assert_eq!(encoding::base64url(b""), "");
assert_eq!(encoding::base64url(b"f"), "Zg");
assert_eq!(encoding::base64url(b"fo"), "Zm8");
assert_eq!(encoding::base64url(b"foo"), "Zm9v");
assert_eq!(encoding::base64url(b"foob"), "Zm9vYg");
assert_eq!(encoding::base64url(b"fooba"), "Zm9vYmE");
assert_eq!(encoding::base64url(b"foobar"), "Zm9vYmFy");
}
#[test]
fn password_generator_uses_expected_length() {
let generator = PasswordGenerator::default();
let password = generator.generate_using(&mut seeded_rng());
assert_eq!(password.len(), 24);
}
#[test]
fn password_generator_contains_all_character_classes() {
let generator = PasswordGenerator::default();
let password = generator.generate_using(&mut seeded_rng());
assert!(password.chars().any(|ch| ch.is_ascii_uppercase()));
assert!(password.chars().any(|ch| ch.is_ascii_lowercase()));
assert!(password.chars().any(|ch| ch.is_ascii_digit()));
assert!(password.chars().any(|ch| "!@#$%^&*()-_=+[]{}".contains(ch)));
}
#[test]
fn password_generator_rejects_invalid_length() {
assert_eq!(
PasswordGenerator::new(PasswordGenerator::MIN_LENGTH - 1),
Err(Error::InvalidLength(PasswordGenerator::MIN_LENGTH - 1))
);
assert_eq!(
PasswordGenerator::new(PasswordGenerator::MAX_LENGTH + 1),
Err(Error::InvalidLength(PasswordGenerator::MAX_LENGTH + 1))
);
}
#[test]
fn password_generator_is_deterministic_with_same_seed() {
let generator = PasswordGenerator::default();
let first = generator.generate_using(&mut seeded_rng());
let second = generator.generate_using(&mut seeded_rng());
assert_eq!(first, second);
}
#[test]
fn api_key_generator_uses_prefix_and_hex() {
let generator = ApiKeyGenerator::default();
let api_key = generator.generate_using(&mut seeded_rng());
assert!(api_key.starts_with("ct_ak_"));
let random_part = api_key
.strip_prefix("ct_ak_")
.expect("api key should have prefix");
assert_eq!(random_part.len(), 24 * 2);
assert!(random_part.chars().all(|ch| ch.is_ascii_hexdigit()));
}
#[test]
fn api_key_generator_rejects_invalid_bytes() {
assert_eq!(
ApiKeyGenerator::new("ct_ak", ApiKeyGenerator::MIN_BYTES - 1),
Err(Error::InvalidByteCount(ApiKeyGenerator::MIN_BYTES - 1))
);
}
#[test]
fn token_generator_uses_prefix_and_base64url() {
let generator = TokenGenerator::default();
let token = generator.generate_using(&mut seeded_rng());
assert!(token.starts_with("ct_tok_"));
let random_part = token
.strip_prefix("ct_tok_")
.expect("token should have prefix");
assert!(
random_part
.chars()
.all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_')
);
}
#[test]
fn jwt_generator_has_three_parts() {
let generator = JwtGenerator::default();
let jwt = generator.generate_using(&mut seeded_rng());
assert_eq!(jwt.matches('.').count(), 2);
}
#[test]
fn jwt_generator_parts_are_base64url() {
let generator = JwtGenerator::default();
let jwt = generator.generate_using(&mut seeded_rng());
for part in jwt.split('.') {
assert!(!part.is_empty());
assert!(
part.chars()
.all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_')
);
}
}
#[test]
fn db_url_generator_has_expected_shape() {
let generator = DbUrlGenerator::default();
let url = generator.generate_using(&mut seeded_rng());
assert!(url.starts_with("postgres://canary:"));
assert!(url.contains("@localhost:5432/canary"));
}
#[test]
fn private_key_generator_has_fake_pem_shape() {
let generator = PrivateKeyGenerator::default();
let key = generator.generate_using(&mut seeded_rng());
assert!(key.starts_with("-----BEGIN FAKE CANARY PRIVATE KEY-----"));
assert!(
key.trim_end()
.ends_with("-----END FAKE CANARY PRIVATE KEY-----")
);
assert!(key.contains('\n'));
}
#[test]
fn custom_generator_uses_prefix() {
let generator =
CustomGenerator::new("ct_ldap", 16).expect("custom generator should be valid");
let value = generator.generate_using(&mut seeded_rng());
assert!(value.starts_with("ct_ldap_"));
}
#[test]
fn generate_supports_all_builtin_kinds() {
let kinds = [
CanaryKind::Password,
CanaryKind::ApiKey,
CanaryKind::Token,
CanaryKind::Jwt,
CanaryKind::DbUrl,
CanaryKind::PrivateKey,
CanaryKind::custom("ldap"),
];
for kind in kinds {
let value = generate(&kind).expect("generation should succeed");
assert!(!value.is_empty());
}
}
#[test]
fn generate_using_sanitizes_custom_kind_label() {
let mut rng = seeded_rng();
let kind = CanaryKind::Custom("LDAP bind".to_owned());
let value = generate_using(&kind, &mut rng).expect("generation should succeed");
assert!(value.starts_with("ct_ldapbind_"));
}
#[test]
fn generated_values_are_unique() {
let mut values = HashSet::new();
for _ in 0..100 {
let value = generate(&CanaryKind::ApiKey).expect("generation should succeed");
assert!(values.insert(value), "generated values should be unique");
}
}
#[test]
fn generator_trait_object_can_be_used() {
let generator: Box<dyn Generator> = Box::new(PasswordGenerator::default());
let value = generator.generate().expect("generation should succeed");
assert_eq!(value.len(), 24);
}
}