#![deny(clippy::unwrap_used, clippy::expect_used)]
use alloc::vec::Vec;
use base64::Engine as _;
use base64::{
alphabet,
engine::{DecodePaddingMode, GeneralPurpose, GeneralPurposeConfig},
};
use crate::core::VerifyOptions;
use crate::core::crypto::verify_hmac_sha256;
use crate::core::error::VerifyError;
use crate::core::headers::HeaderMap;
use crate::core::replay::{check_replay, parse_timestamp};
use crate::core::secret::Secret;
pub(crate) const ID_HEADER: &str = "webhook-id";
pub(crate) const TIMESTAMP_HEADER: &str = "webhook-timestamp";
pub(crate) const SIGNATURE_HEADER: &str = "webhook-signature";
const SCHEME: &str = "v1";
const SECRET_PREFIX: &str = "whsec_";
const SIGNATURE_LEN_BYTES: usize = 32;
static SECRET_B64: GeneralPurpose = GeneralPurpose::new(
&alphabet::STANDARD,
GeneralPurposeConfig::new()
.with_decode_allow_trailing_bits(true)
.with_decode_padding_mode(DecodePaddingMode::Indifferent),
);
pub(crate) fn verify(
headers: &dyn HeaderMap,
raw_body: &[u8],
secret: &Secret,
options: &VerifyOptions,
) -> Result<(), VerifyError> {
let id_raw = headers
.get(ID_HEADER)
.ok_or(VerifyError::MissingHeader { header: ID_HEADER })?;
let signature_value = headers
.get(SIGNATURE_HEADER)
.ok_or(VerifyError::MissingHeader {
header: SIGNATURE_HEADER,
})?;
let timestamp_raw = headers
.get(TIMESTAMP_HEADER)
.ok_or(VerifyError::MissingHeader {
header: TIMESTAMP_HEADER,
})?;
let key = decode_secret(secret.as_bytes())?;
let provided_signatures = parse_signatures(signature_value)?;
let timestamp = parse_timestamp(TIMESTAMP_HEADER, timestamp_raw)?;
let mut signed_string =
Vec::with_capacity(id_raw.len() + 1 + timestamp_raw.len() + 1 + raw_body.len());
signed_string.extend_from_slice(id_raw.as_bytes());
signed_string.push(b'.');
signed_string.extend_from_slice(timestamp_raw.as_bytes());
signed_string.push(b'.');
signed_string.extend_from_slice(raw_body);
let matched = provided_signatures
.iter()
.any(|sig| verify_hmac_sha256(&key, &signed_string, sig));
if !matched {
return Err(VerifyError::SignatureMismatch);
}
check_replay(timestamp, options)
}
fn decode_secret(secret: &[u8]) -> Result<Vec<u8>, VerifyError> {
let as_str = core::str::from_utf8(secret).map_err(|_| VerifyError::InvalidSecret {
reason: "secret must be valid UTF-8",
})?;
let encoded = as_str.strip_prefix(SECRET_PREFIX).unwrap_or(as_str);
if encoded.is_empty() {
return Err(VerifyError::InvalidSecret {
reason: "secret is empty",
});
}
let key = SECRET_B64
.decode(encoded)
.map_err(|_| VerifyError::InvalidSecret {
reason: "secret is not valid standard-alphabet base64 after any `whsec_` prefix",
})?;
if key.is_empty() {
return Err(VerifyError::InvalidSecret {
reason: "decoded signing key must not be empty",
});
}
Ok(key)
}
fn parse_signatures(value: &str) -> Result<Vec<Vec<u8>>, VerifyError> {
if value.is_empty() {
return Err(VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "header is empty",
});
}
let mut signatures = Vec::new();
for element in value.split(' ') {
let Some((version, encoded)) = element.split_once(',') else {
continue;
};
if version != SCHEME {
continue;
}
if encoded.is_empty() {
return Err(VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "empty signature after `v1,` prefix",
});
}
let bytes = base64::engine::general_purpose::STANDARD
.decode(encoded)
.map_err(|_| VerifyError::BadEncoding {
reason: "signature is not valid standard-alphabet base64",
})?;
if bytes.len() != SIGNATURE_LEN_BYTES {
return Err(VerifyError::BadEncoding {
reason: "signature does not decode to 32 bytes",
});
}
signatures.push(bytes);
}
if signatures.is_empty() {
return Err(VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "no `v1,` signature present",
});
}
Ok(signatures)
}
#[cfg(test)]
mod tests {
use super::{ID_HEADER, SECRET_PREFIX, SIGNATURE_HEADER, TIMESTAMP_HEADER};
use crate::core::error::VerifyError;
use crate::core::options::VerifyOptions;
use crate::core::secret::Secret;
use crate::test_helpers::clocked_at;
use crate::verify;
use std::time::Duration;
const SECRET: &str = concat!("whsec_", "MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw");
fn whsec(encoded: &str) -> String {
format!("{SECRET_PREFIX}{encoded}")
}
const MSG_ID: &str = "msg_p5jXN8AQM9LWM0D4loKWxJek";
const TIMESTAMP: u64 = 1_614_265_330;
const BODY: &[u8] = br#"{"test": 2432232314}"#;
const SIGNATURE: &str = "g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=";
const INVALID_SIGNATURE: &str = "g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OA=";
const STALE_SIGNATURE: &str = "Ceo5qEr07ixe2NLpvHk3FH9bwy/WavXrAFQ/9tdO6mc=";
const EMPTY_BODY_SIGNATURE: &str = "v48jdbgvh29KJz2Qc+ghw8G6vG3nAKnujWBg8oM/62A=";
const UNICODE_BODY_SIGNATURE: &str = "97lN0xDmMiBOfUlhcvdbJPqKzUcBmyfgBUIzq1ocPOk=";
const UNPADDED_SECRET_23B_SIGNATURE: &str = "LVOXivKoo4FWasi/IaHvzhE/u+7/cu2AME+zS/nXqzk=";
const UNPADDED_SECRET_25B_SIGNATURE: &str = "yK2tMbA6BHPrMEJ1lLv7UlJJbgFoqGenJkiajZ29evg=";
fn verify_with(
body: &[u8],
id: &str,
signature_value: &str,
timestamp_value: &str,
secret: &Secret,
options: VerifyOptions,
) -> Result<(), VerifyError> {
verify(
crate::Provider::StandardWebhooks,
&[
(ID_HEADER, id),
(SIGNATURE_HEADER, signature_value),
(TIMESTAMP_HEADER, timestamp_value),
],
body,
secret,
options,
)
}
fn verify_fresh(body: &[u8], signature: &str) -> Result<(), VerifyError> {
verify_with(
body,
MSG_ID,
&format!("v1,{signature}"),
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
)
}
#[test]
fn official_vector_verifies() {
assert_eq!(verify_fresh(BODY, SIGNATURE), Ok(()));
}
#[test]
fn official_negative_vector_fails() {
assert_eq!(
verify_fresh(BODY, INVALID_SIGNATURE),
Err(VerifyError::SignatureMismatch)
);
}
#[test]
fn boundary_bodies_verify() {
assert_eq!(verify_fresh(b"", EMPTY_BODY_SIGNATURE), Ok(()));
assert_eq!(
verify_fresh("héllo, 🦀 world!".as_bytes(), UNICODE_BODY_SIGNATURE),
Ok(())
);
}
#[test]
fn header_names_are_case_insensitive() {
let result = verify(
crate::Provider::StandardWebhooks,
&[
("WEBHOOK-ID", MSG_ID),
("Webhook-Signature", format!("v1,{SIGNATURE}").as_str()),
("webhook-TIMESTAMP", TIMESTAMP.to_string().as_str()),
],
BODY,
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(result, Ok(()));
}
#[test]
fn secret_prefix_is_optional_and_padding_tolerant() {
let variants = [
(SECRET.to_string(), SIGNATURE),
("MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw".to_string(), SIGNATURE),
(
whsec("MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaS="),
UNPADDED_SECRET_23B_SIGNATURE,
),
(
whsec("MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaS"),
UNPADDED_SECRET_23B_SIGNATURE,
),
(
whsec("MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwBr=="),
UNPADDED_SECRET_25B_SIGNATURE,
),
(
whsec("MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwBr"),
UNPADDED_SECRET_25B_SIGNATURE,
),
];
for (variant, signature) in variants {
let result = verify_with(
BODY,
MSG_ID,
&format!("v1,{signature}"),
&TIMESTAMP.to_string(),
&Secret::new(variant.clone()),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(result, Ok(()), "variant: {variant}");
}
}
#[test]
fn rotation_any_matching_v1_is_accepted() {
let value = format!(
"v1,{STALE_SIGNATURE} v2,{STALE_SIGNATURE} v1,{SIGNATURE} v1a,{STALE_SIGNATURE}"
);
assert_eq!(
verify_with(
BODY,
MSG_ID,
&value,
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
),
Ok(())
);
let reordered = format!(
"v1a,{STALE_SIGNATURE} v1,{SIGNATURE} v2,{STALE_SIGNATURE} v1,{STALE_SIGNATURE}"
);
assert_eq!(
verify_with(
BODY,
MSG_ID,
&reordered,
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
),
Ok(())
);
}
#[test]
fn negative_flipped_base64_character_fails() {
let flipped = format!("{}A{}", &SIGNATURE[..10], &SIGNATURE[11..]);
assert_ne!(flipped, SIGNATURE);
assert_eq!(
verify_fresh(BODY, &flipped),
Err(VerifyError::SignatureMismatch)
);
}
#[test]
fn tampered_body_fails() {
assert_eq!(
verify_fresh(br#"{"test": 2432232315}"#, SIGNATURE),
Err(VerifyError::SignatureMismatch)
);
}
#[test]
fn tampered_id_and_timestamp_fail_signature_check() {
let forged_id = verify_with(
BODY,
"msg_forged",
&format!("v1,{SIGNATURE}"),
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(forged_id, Err(VerifyError::SignatureMismatch));
let forged_ts = verify_with(
BODY,
MSG_ID,
&format!("v1,{SIGNATURE}"),
&(TIMESTAMP - 1).to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(forged_ts, Err(VerifyError::SignatureMismatch));
}
#[test]
fn wrong_secret_fails() {
let result = verify_with(
BODY,
MSG_ID,
&format!("v1,{SIGNATURE}"),
&TIMESTAMP.to_string(),
&Secret::new(whsec("MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSX")),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(result, Err(VerifyError::SignatureMismatch));
}
#[test]
fn replay_old_timestamp_out_of_tolerance() {
let result = verify_with(
BODY,
MSG_ID,
&format!("v1,{SIGNATURE}"),
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP + 301, Some(Duration::from_secs(300))),
);
assert_eq!(
result,
Err(VerifyError::TimestampOutOfTolerance {
skew: Duration::from_secs(301),
max_age: Duration::from_secs(300),
})
);
}
#[test]
fn replay_future_timestamp_out_of_tolerance() {
let result = verify_with(
BODY,
MSG_ID,
&format!("v1,{SIGNATURE}"),
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP - 301, Some(Duration::from_secs(300))),
);
assert_eq!(
result,
Err(VerifyError::TimestampOutOfTolerance {
skew: Duration::from_secs(301),
max_age: Duration::from_secs(300),
})
);
}
#[test]
fn replay_within_tolerance_verifies_at_window_edges() {
for now in [TIMESTAMP - 300, TIMESTAMP + 300] {
let result = verify_with(
BODY,
MSG_ID,
&format!("v1,{SIGNATURE}"),
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(now, Some(Duration::from_secs(300))),
);
assert_eq!(result, Ok(()), "now = {now}");
}
}
#[test]
fn disabled_max_age_accepts_stale_signatures() {
let result = verify_with(
BODY,
MSG_ID,
&format!("v1,{SIGNATURE}"),
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP + 86_400 * 365, None),
);
assert_eq!(result, Ok(()));
}
#[test]
fn missing_headers_error_distinctly() {
let missing_id = verify(
crate::Provider::StandardWebhooks,
&[(SIGNATURE_HEADER, format!("v1,{SIGNATURE}").as_str())],
BODY,
&Secret::new(SECRET),
Default::default(),
);
assert_eq!(
missing_id,
Err(VerifyError::MissingHeader { header: ID_HEADER })
);
let missing_signature = verify(
crate::Provider::StandardWebhooks,
&[
(ID_HEADER, MSG_ID),
(TIMESTAMP_HEADER, TIMESTAMP.to_string().as_str()),
],
BODY,
&Secret::new(SECRET),
Default::default(),
);
assert_eq!(
missing_signature,
Err(VerifyError::MissingHeader {
header: SIGNATURE_HEADER
})
);
let missing_timestamp = verify(
crate::Provider::StandardWebhooks,
&[
(ID_HEADER, MSG_ID),
(SIGNATURE_HEADER, format!("v1,{SIGNATURE}").as_str()),
],
BODY,
&Secret::new(SECRET),
Default::default(),
);
assert_eq!(
missing_timestamp,
Err(VerifyError::MissingHeader {
header: TIMESTAMP_HEADER
})
);
let all_missing = verify(
crate::Provider::StandardWebhooks,
&Vec::<(String, String)>::new(),
BODY,
&Secret::new(SECRET),
Default::default(),
);
assert_eq!(
all_missing,
Err(VerifyError::MissingHeader { header: ID_HEADER })
);
}
#[test]
fn invalid_secrets_error_distinctly() {
let cases = [
"whsec_".to_string(),
String::new(),
"whsec_this is not base64!!".to_string(),
"whsec_====".to_string(),
];
for variant in cases {
let result = verify_with(
BODY,
MSG_ID,
&format!("v1,{SIGNATURE}"),
&TIMESTAMP.to_string(),
&Secret::new(variant.clone()),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
match result {
Err(VerifyError::InvalidSecret { .. }) => {}
other => panic!("expected InvalidSecret for {variant:?}, got {other:?}"),
}
}
}
#[test]
fn verify_any_rotation_succeeds_with_one_garbled_key() {
let secrets = [
Secret::new("whsec_this is not base64!!"),
Secret::new(SECRET),
];
let signature_value = format!("v1,{SIGNATURE}");
let timestamp_value = TIMESTAMP.to_string();
let result = crate::verify_any(
crate::Provider::StandardWebhooks,
&[
(ID_HEADER, MSG_ID),
(SIGNATURE_HEADER, signature_value.as_str()),
(TIMESTAMP_HEADER, timestamp_value.as_str()),
],
BODY,
&secrets,
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(result, Ok(()));
}
#[test]
fn verify_any_reports_invalid_secret_when_every_key_is_garbled() {
let secrets = [
Secret::new("whsec_this is not base64!!"),
Secret::new("whsec_===="),
];
let signature_value = format!("v1,{SIGNATURE}");
let timestamp_value = TIMESTAMP.to_string();
let result = crate::verify_any(
crate::Provider::StandardWebhooks,
&[
(ID_HEADER, MSG_ID),
(SIGNATURE_HEADER, signature_value.as_str()),
(TIMESTAMP_HEADER, timestamp_value.as_str()),
],
BODY,
&secrets,
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(
result,
Err(VerifyError::InvalidSecret {
reason: "secret is not valid standard-alphabet base64 after any `whsec_` prefix",
})
);
}
#[test]
fn verify_any_mixed_garbled_and_mismatched_reports_mismatch() {
let secrets = [
Secret::new("whsec_this is not base64!!"),
Secret::new(whsec("MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSX")),
];
let signature_value = format!("v1,{SIGNATURE}");
let timestamp_value = TIMESTAMP.to_string();
let result = crate::verify_any(
crate::Provider::StandardWebhooks,
&[
(ID_HEADER, MSG_ID),
(SIGNATURE_HEADER, signature_value.as_str()),
(TIMESTAMP_HEADER, timestamp_value.as_str()),
],
BODY,
&secrets,
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(result, Err(VerifyError::SignatureMismatch));
}
#[test]
fn malformed_signature_header_errors_distinctly() {
let cases: Vec<(String, VerifyError)> = vec![
(
String::new(),
VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "header is empty",
},
),
(
format!("v2,{SIGNATURE} v1a,{SIGNATURE}"),
VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "no `v1,` signature present",
},
),
(
"v1,".to_string(),
VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "empty signature after `v1,` prefix",
},
),
(
"garbage also-garbage".to_string(),
VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "no `v1,` signature present",
},
),
];
for (value, expected) in cases {
let result = verify_with(
BODY,
MSG_ID,
&value,
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(result, Err(expected), "input: {value:?}");
}
}
#[test]
fn bad_encoding_errors_distinctly() {
let cases: Vec<String> = vec![
"v1,zzzz".to_string(),
"v1,abc".to_string(),
"v1,HcZO8dIixs4vWL0zK+0uBpwLgW0=".to_string(),
format!("v1,{SIGNATURE} v1,nothex"),
];
for value in cases {
let result = verify_with(
BODY,
MSG_ID,
&value,
&TIMESTAMP.to_string(),
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
match result {
Err(VerifyError::BadEncoding { .. }) => {}
other => panic!("expected BadEncoding for {value:?}, got {other:?}"),
}
}
}
#[test]
fn malformed_timestamp_header_errors_distinctly() {
let cases: Vec<(String, VerifyError)> = vec![
(
String::new(),
VerifyError::MalformedHeader {
header: TIMESTAMP_HEADER,
reason: "header is empty",
},
),
(
"not-a-number".to_string(),
VerifyError::MalformedHeader {
header: TIMESTAMP_HEADER,
reason: "timestamp is not a valid unix timestamp",
},
),
(
format!("-{TIMESTAMP}"),
VerifyError::MalformedHeader {
header: TIMESTAMP_HEADER,
reason: "timestamp is not a valid unix timestamp",
},
),
(
"1614265330.5".to_string(),
VerifyError::MalformedHeader {
header: TIMESTAMP_HEADER,
reason: "timestamp is not a valid unix timestamp",
},
),
(
"99999999999999999999999".to_string(),
VerifyError::MalformedHeader {
header: TIMESTAMP_HEADER,
reason: "timestamp overflows unix seconds",
},
),
];
for (value, expected) in cases {
let result = verify_with(
BODY,
MSG_ID,
&format!("v1,{SIGNATURE}"),
&value,
&Secret::new(SECRET),
clocked_at(TIMESTAMP, Some(Duration::from_secs(300))),
);
assert_eq!(result, Err(expected), "input: {value:?}");
}
}
}