//! Amazon SES over SMTP, configured from AWS-style variables when `SMTP_URL` //! is not set (so the credentials can sit in `.env.secrets` as they are). //! //! Accepted (upper or lower case): //! * `SES_SMTP_USERNAME` + `SES_SMTP_PASSWORD`: SMTP credentials from the SES console; //! * or `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (or another name from //! `KEY_NAMES` / `SECRET_NAMES`, e.g. `ses_auth_key` + `ses_secret`): an IAM //! key allowed `ses:SendRawEmail`; the SMTP //! password is derived from it as AWS documents. If the "secret" already is //! an SMTP password, it is used as it is. //! * `SES_REGION` / `AWS_REGION` / `AWS_DEFAULT_REGION` (default `eu-central-1`), //! `SES_SMTP_PORT` (default 2587, STARTTLS: DigitalOcean blocks 25, 465 and 587). use base64::Engine; use base64::engine::general_purpose::STANDARD; use hmac::{Hmac, Mac}; use sha2::Sha256; pub const DEFAULT_REGION: &str = "eu-central-1"; /// Names the access key id may have in a secrets file. const KEY_NAMES: &[&str] = &[ "SES_ACCESS_KEY_ID", "AWS_ACCESS_KEY_ID", "SES_AUTH_KEY", "SES_ACCESS_KEY", "SES_KEY", "AWS_AUTH_KEY", "AWS_ACCESS_KEY", "AUTH_KEY", ]; /// Names the secret access key may have. const SECRET_NAMES: &[&str] = &[ "SES_SECRET_ACCESS_KEY", "AWS_SECRET_ACCESS_KEY", "SES_SECRET", "SES_SECRET_KEY", "SES_AUTH_SECRET", "AWS_SECRET", "AWS_SECRET_KEY", "AUTH_SECRET", ]; const DEFAULT_PORT: u16 = 2587; /// The first set variable among `names`, each tried in upper and lower case. fn var(lookup: &impl Fn(&str) -> Option, names: &[&str]) -> Option<(String, String)> { names.iter().find_map(|name| { [name.to_string(), name.to_lowercase()] .into_iter() .find_map(|n| lookup(&n).map(|v| v.trim().to_owned()).filter(|v| !v.is_empty()).map(|v| (n, v))) }) } /// The SES SMTP address and a description for the log (no secrets), if credentials are set. pub fn smtp_url(lookup: impl Fn(&str) -> Option) -> anyhow::Result> { let region = var(&lookup, &["SES_REGION", "AWS_REGION", "AWS_DEFAULT_REGION"]).map_or(DEFAULT_REGION.into(), |(_, v)| v); if !region.chars().all(|c| c.is_ascii_alphanumeric() || c == '-') { anyhow::bail!("invalid SES region '{region}'"); } let port: u16 = match var(&lookup, &["SES_SMTP_PORT"]) { Some((_, p)) => p.parse().map_err(|e| anyhow::anyhow!("invalid SES_SMTP_PORT '{p}': {e}"))?, None => DEFAULT_PORT, }; let smtp = var(&lookup, &["SES_SMTP_USERNAME", "SES_SMTP_USER"]).zip(var(&lookup, &["SES_SMTP_PASSWORD"])); let (user, password, source) = if let Some(((name, user), (_, password))) = smtp { (user, password, name) } else { let key = var(&lookup, KEY_NAMES); let secret = var(&lookup, SECRET_NAMES); match (key, secret) { (Some((name, key)), Some((_, secret))) => { let password = if is_smtp_password(&secret) { secret } else { smtp_password(&secret, ®ion) }; (key, password, name) } (None, None) => return Ok(None), _ => anyhow::bail!("SES: both the access key id and the secret access key are needed"), } }; let url = format!("smtp://{}:{}@email-smtp.{region}.amazonaws.com:{port}?tls=required", encode(&user), encode(&password)); Ok(Some((url, format!("Amazon SES {region}:{port}, credentials from {source}")))) } /// The SES SMTP password of an IAM secret access key (AWS docs, "Obtaining /// Amazon SES SMTP credentials": signature version 4, `SendRawEmail`). pub fn smtp_password(secret: &str, region: &str) -> String { fn sign(key: &[u8], msg: &str) -> Vec { let mut mac = Hmac::::new_from_slice(key).expect("HMAC takes any key length"); mac.update(msg.as_bytes()); mac.finalize().into_bytes().to_vec() } let mut signature = sign(format!("AWS4{secret}").as_bytes(), "11111111"); for part in [region, "ses", "aws4_request", "SendRawEmail"] { signature = sign(&signature, part); } let mut bytes = vec![0x04]; bytes.extend(signature); STANDARD.encode(bytes) } /// An SMTP password is a version byte (4) and a 32-byte signature, in base64; /// an IAM secret key is 40 characters. fn is_smtp_password(s: &str) -> bool { s.len() == 44 && STANDARD.decode(s).is_ok_and(|b| b.len() == 33 && b[0] == 0x04) } /// Percent-encoding for the user and password part of a URL. fn encode(s: &str) -> String { s.bytes() .map(|b| match b { b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => (b as char).to_string(), _ => format!("%{b:02X}"), }) .collect() } #[cfg(test)] mod tests { use std::collections::HashMap; use super::*; fn env(pairs: &[(&str, &str)]) -> impl Fn(&str) -> Option { let map: HashMap = pairs.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect(); move |k| map.get(k).cloned() } #[test] fn derives_the_smtp_password() { // The value of AWS's Python example (docs: "Obtaining Amazon SES SMTP credentials") for this made-up key. let password = smtp_password("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "eu-central-1"); assert_eq!(password, "BF0/eIJm0ruTHsSjOkRuOGzGF+zeSyE3aiRzrzUQ8LwG"); assert!(is_smtp_password(&password)); assert!(!is_smtp_password("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")); } #[test] fn url_from_variables() { assert!(smtp_url(env(&[])).unwrap().is_none()); let (url, about) = smtp_url(env(&[ ("aws_access_key_id", "AKIAEXAMPLE"), ("aws_secret_access_key", "BF0/eIJm0ruTHsSjOkRuOGzGF+zeSyE3aiRzrzUQ8LwG"), ])) .unwrap() .unwrap(); // already an SMTP password: kept, with + and / encoded assert_eq!( url, "smtp://AKIAEXAMPLE:BF0%2FeIJm0ruTHsSjOkRuOGzGF%2BzeSyE3aiRzrzUQ8LwG@email-smtp.eu-central-1.amazonaws.com:2587?tls=required" ); assert_eq!(about, "Amazon SES eu-central-1:2587, credentials from aws_access_key_id"); let (url, _) = smtp_url(env(&[ ("SES_SMTP_USERNAME", "AKIA2"), ("SES_SMTP_PASSWORD", "a/b+c="), ("SES_REGION", "eu-west-1"), ])) .unwrap() .unwrap(); assert_eq!(url, "smtp://AKIA2:a%2Fb%2Bc%3D@email-smtp.eu-west-1.amazonaws.com:2587?tls=required"); assert!(smtp_url(env(&[("AWS_ACCESS_KEY_ID", "AKIA")])).is_err()); // other common names; a real secret key is turned into the SMTP password let (url, about) = smtp_url(env(&[("ses_auth_key", "AKIA3"), ("ses_secret", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")])) .unwrap() .unwrap(); assert!( url.starts_with("smtp://AKIA3:BF0%2FeIJm0ruTHsSjOkRuOGzGF%2BzeSyE3aiRzrzUQ8LwG@email-smtp.eu-central-1.") ); assert!(about.ends_with("from ses_auth_key")); } }