mod custom;
mod discord;
mod dropbox;
mod github;
mod linear;
#[cfg(feature = "paypal")]
mod paypal;
#[cfg(feature = "sendgrid")]
mod sendgrid;
mod shopify;
mod slack;
mod square;
mod standard_webhooks;
mod stripe;
mod twilio;
mod zoom;
pub use custom::{CustomScheme, Encoding, HashAlg};
use core::fmt;
#[cfg(any(feature = "tower", feature = "actix"))]
use alloc::vec;
#[cfg(any(feature = "tower", feature = "actix"))]
use alloc::vec::Vec;
use crate::core::VerifyOptions;
use crate::core::error::VerifyError;
use crate::core::headers::HeaderMap;
use crate::core::secret::Secret;
#[must_use]
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Provider {
Stripe,
GitHub,
Shopify,
Slack,
Square,
Twilio,
Discord,
PayPal,
SendGrid,
Linear,
Zoom,
Dropbox,
StandardWebhooks,
Custom(CustomScheme),
}
impl fmt::Display for Provider {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Provider::Stripe => f.write_str("Stripe"),
Provider::GitHub => f.write_str("GitHub"),
Provider::Shopify => f.write_str("Shopify"),
Provider::Slack => f.write_str("Slack"),
Provider::Square => f.write_str("Square"),
Provider::Twilio => f.write_str("Twilio"),
Provider::Discord => f.write_str("Discord"),
Provider::PayPal => f.write_str("PayPal"),
Provider::SendGrid => f.write_str("SendGrid"),
Provider::Linear => f.write_str("Linear"),
Provider::Zoom => f.write_str("Zoom"),
Provider::Dropbox => f.write_str("Dropbox"),
Provider::StandardWebhooks => f.write_str("StandardWebhooks"),
Provider::Custom(scheme) => {
write!(f, "Custom({})", scheme.signature_header)
}
}
}
}
#[cfg(any(feature = "tower", feature = "actix"))]
pub(crate) fn signature_header_names(provider: &Provider) -> Vec<&'static str> {
match provider {
Provider::Stripe => vec![stripe::SIGNATURE_HEADER],
Provider::GitHub => vec![github::SIGNATURE_HEADER],
Provider::Shopify => vec![shopify::SIGNATURE_HEADER],
Provider::Slack => vec![slack::SIGNATURE_HEADER, slack::TIMESTAMP_HEADER],
Provider::Square => vec![square::SIGNATURE_HEADER],
Provider::Twilio => vec![twilio::SIGNATURE_HEADER],
Provider::Discord => {
vec![discord::SIGNATURE_HEADER, discord::TIMESTAMP_HEADER]
}
Provider::Linear => vec![linear::SIGNATURE_HEADER],
Provider::Dropbox => vec![dropbox::SIGNATURE_HEADER],
Provider::Zoom => vec![zoom::SIGNATURE_HEADER, zoom::TIMESTAMP_HEADER],
Provider::StandardWebhooks => vec![
standard_webhooks::ID_HEADER,
standard_webhooks::TIMESTAMP_HEADER,
standard_webhooks::SIGNATURE_HEADER,
],
Provider::Custom(scheme) => {
let mut names = vec![scheme.signature_header];
if let Some(timestamp) = scheme.timestamp_header {
names.push(timestamp);
}
names
}
#[cfg(feature = "sendgrid")]
Provider::SendGrid => {
vec![sendgrid::SIGNATURE_HEADER, sendgrid::TIMESTAMP_HEADER]
}
#[cfg(feature = "paypal")]
Provider::PayPal => vec![
paypal::TRANSMISSION_ID_HEADER,
paypal::TRANSMISSION_TIME_HEADER,
paypal::TRANSMISSION_SIG_HEADER,
paypal::CERT_URL_HEADER,
paypal::AUTH_ALGO_HEADER,
],
#[cfg(not(feature = "paypal"))]
Provider::PayPal => Vec::new(),
#[cfg(not(feature = "sendgrid"))]
Provider::SendGrid => Vec::new(),
}
}
pub fn verify(
provider: Provider,
headers: &dyn HeaderMap,
raw_body: &[u8],
secret: &Secret,
options: VerifyOptions,
) -> Result<(), VerifyError> {
match provider {
Provider::Discord => discord::verify(headers, raw_body, secret, &options),
Provider::GitHub => github::verify(headers, raw_body, secret, &options),
Provider::Linear => linear::verify(headers, raw_body, secret, &options),
Provider::Zoom => zoom::verify(headers, raw_body, secret, &options),
Provider::Shopify => shopify::verify(headers, raw_body, secret, &options),
Provider::Slack => slack::verify(headers, raw_body, secret, &options),
Provider::Square => square::verify(headers, raw_body, secret, &options),
Provider::Stripe => stripe::verify(headers, raw_body, secret, &options),
Provider::StandardWebhooks => {
standard_webhooks::verify(headers, raw_body, secret, &options)
}
Provider::Twilio => twilio::verify(headers, raw_body, secret, &options),
Provider::Dropbox => dropbox::verify(headers, raw_body, secret, &options),
#[cfg(feature = "paypal")]
Provider::PayPal => paypal::verify(headers, raw_body, secret, &options),
#[cfg(not(feature = "paypal"))]
Provider::PayPal => Err(VerifyError::UnsupportedProvider),
#[cfg(feature = "sendgrid")]
Provider::SendGrid => sendgrid::verify(headers, raw_body, secret, &options),
#[cfg(not(feature = "sendgrid"))]
Provider::SendGrid => Err(VerifyError::UnsupportedProvider),
Provider::Custom(scheme) => custom::verify(&scheme, headers, raw_body, secret, &options),
}
}
pub fn verify_any(
provider: Provider,
headers: &dyn HeaderMap,
raw_body: &[u8],
secrets: &[Secret],
options: VerifyOptions,
) -> Result<(), VerifyError> {
let mut first_invalid_secret: Option<VerifyError> = None;
let mut any_well_formed_mismatch = false;
for secret in secrets {
match verify(provider, headers, raw_body, secret, options.clone()) {
Ok(()) => return Ok(()),
Err(VerifyError::SignatureMismatch) => any_well_formed_mismatch = true,
Err(invalid @ VerifyError::InvalidSecret { .. }) => {
first_invalid_secret.get_or_insert(invalid);
}
Err(other) => {
return Err(other);
}
}
}
if !any_well_formed_mismatch {
if let Some(invalid) = first_invalid_secret {
return Err(invalid);
}
}
Err(VerifyError::SignatureMismatch)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::core::error::VerifyError;
use crate::core::secret::Secret;
use crate::test_helpers::clocked_at;
use std::time::Duration;
fn slack_signature(secret: &str, ts: u64, body: &[u8]) -> String {
use hmac::{Hmac, KeyInit, Mac};
use sha2::Sha256;
let mut mac = match Hmac::<Sha256>::new_from_slice(secret.as_bytes()) {
Ok(mac) => mac,
Err(_) => panic!("HMAC-SHA256 with a constant test secret cannot fail"),
};
mac.update(format!("v0:{ts}:").as_bytes());
mac.update(body);
hex::encode(mac.finalize().into_bytes())
}
const GITHUB_SECRET: &str = "It's a Secret to Everybody";
const GITHUB_BODY: &[u8] = b"Hello, World!";
const GITHUB_SIGNATURE: &str =
"sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17";
fn github_headers() -> Vec<(String, String)> {
vec![(
"X-Hub-Signature-256".to_string(),
GITHUB_SIGNATURE.to_string(),
)]
}
#[test]
fn verify_any_accepts_first_matching_secret() {
let direct = super::verify(
Provider::GitHub,
&github_headers(),
GITHUB_BODY,
&Secret::new(GITHUB_SECRET),
Default::default(),
);
assert_eq!(direct, Ok(()), "direct verify: {direct:?}");
let secrets = [
Secret::new("wrong-key"),
Secret::new(GITHUB_SECRET),
Secret::new("another-wrong-key"),
];
assert_eq!(
verify_any(
Provider::GitHub,
&github_headers(),
GITHUB_BODY,
&secrets,
Default::default(),
),
Ok(())
);
}
#[test]
fn verify_any_accepts_single_secret() {
let secrets = [Secret::new(GITHUB_SECRET)];
assert_eq!(
verify_any(
Provider::GitHub,
&github_headers(),
GITHUB_BODY,
&secrets,
Default::default(),
),
Ok(())
);
}
#[test]
fn verify_any_rejects_when_no_secret_matches() {
let secrets = [Secret::new("wrong-1"), Secret::new("wrong-2")];
assert_eq!(
verify_any(
Provider::GitHub,
&github_headers(),
GITHUB_BODY,
&secrets,
Default::default(),
),
Err(VerifyError::SignatureMismatch)
);
}
#[test]
fn verify_any_rejects_empty_slice() {
let secrets: [Secret; 0] = [];
let headers: Vec<(String, String)> = github_headers().to_vec();
assert_eq!(
verify_any(
Provider::GitHub,
&headers,
GITHUB_BODY,
&secrets,
Default::default(),
),
Err(VerifyError::SignatureMismatch)
);
}
#[test]
fn verify_any_fails_closed_on_malformed_input() {
let secrets = [Secret::new(GITHUB_SECRET)];
let empty_headers: Vec<(String, String)> = vec![];
assert_eq!(
verify_any(
Provider::GitHub,
&empty_headers,
GITHUB_BODY,
&secrets,
Default::default(),
),
Err(VerifyError::MissingHeader {
header: "X-Hub-Signature-256"
})
);
}
#[test]
fn verify_any_non_first_secret_matches() {
let secrets = [Secret::new("bad"), Secret::new(GITHUB_SECRET)];
assert_eq!(
verify_any(
Provider::GitHub,
&github_headers(),
GITHUB_BODY,
&secrets,
Default::default(),
),
Ok(())
);
}
#[test]
fn verify_any_returns_timestamp_tolerance_immediately_across_secrets() {
let slack_secret = "8f742231b10e8888abcd99yyyzzz85a5";
let slack_body = b"token=xyzz0WbapA4vBCDEFasx0q6G&team_id=T1DC2JH3J";
let stale_ts = 1_531_420_618u64;
let sig = slack_signature(slack_secret, stale_ts, slack_body);
let sig_value = format!("v0={sig}");
let ts_value = stale_ts.to_string();
let headers = [
("X-Slack-Signature", sig_value.as_str()),
("X-Slack-Request-Timestamp", ts_value.as_str()),
];
let options = clocked_at(stale_ts + 3600, Some(Duration::from_secs(300)));
assert!(
matches!(
verify(
Provider::Slack,
&headers,
slack_body,
&Secret::new(slack_secret),
options.clone(),
),
Err(VerifyError::TimestampOutOfTolerance { .. })
),
"direct verify must reject a stale timestamp"
);
let secrets = [
Secret::new("wrong-key-1"),
Secret::new("wrong-key-2"),
Secret::new(slack_secret),
];
assert!(matches!(
verify_any(Provider::Slack, &headers, slack_body, &secrets, options,),
Err(VerifyError::TimestampOutOfTolerance { .. })
));
}
#[test]
fn verify_any_multiple_secrets_affect_only_matching_not_timestamp() {
let slack_secret = "8f742231b10e8888abcd99yyyzzz85a5";
let slack_body = b"token=xyzz0WbapA4vBCDEFasx0q6G&team_id=T1DC2JH3J";
let ts = 1_531_420_618u64;
let sig = slack_signature(slack_secret, ts, slack_body);
let sig_value = format!("v0={sig}");
let ts_value = ts.to_string();
let headers = [
("X-Slack-Signature", sig_value.as_str()),
("X-Slack-Request-Timestamp", ts_value.as_str()),
];
let options = clocked_at(ts, None);
let secrets = [
Secret::new("wrong-key-1"),
Secret::new("wrong-key-2"),
Secret::new(slack_secret),
];
assert_eq!(
verify_any(Provider::Slack, &headers, slack_body, &secrets, options),
Ok(())
);
}
#[test]
fn verify_any_all_wrong_secrets_with_fresh_timestamp_is_mismatch() {
let slack_secret = "8f742231b10e8888abcd99yyyzzz85a5";
let slack_body = b"token=xyzz0WbapA4vBCDEFasx0q6G&team_id=T1DC2JH3J";
let ts = 1_531_420_618u64;
let sig = slack_signature(slack_secret, ts, slack_body);
let sig_value = format!("v0={sig}");
let ts_value = ts.to_string();
let headers = [
("X-Slack-Signature", sig_value.as_str()),
("X-Slack-Request-Timestamp", ts_value.as_str()),
];
let options = clocked_at(ts, Some(Duration::from_secs(300)));
let secrets = [Secret::new("wrong-1"), Secret::new("wrong-2")];
assert_eq!(
verify_any(Provider::Slack, &headers, slack_body, &secrets, options),
Err(VerifyError::SignatureMismatch)
);
}
#[test]
fn provider_display_names() {
use super::CustomScheme;
use crate::{Encoding, HashAlg};
assert_eq!(Provider::Stripe.to_string(), "Stripe");
assert_eq!(Provider::GitHub.to_string(), "GitHub");
assert_eq!(Provider::Shopify.to_string(), "Shopify");
assert_eq!(Provider::Slack.to_string(), "Slack");
assert_eq!(Provider::Square.to_string(), "Square");
assert_eq!(Provider::Twilio.to_string(), "Twilio");
assert_eq!(Provider::Discord.to_string(), "Discord");
assert_eq!(Provider::PayPal.to_string(), "PayPal");
assert_eq!(Provider::SendGrid.to_string(), "SendGrid");
assert_eq!(Provider::Linear.to_string(), "Linear");
assert_eq!(Provider::Zoom.to_string(), "Zoom");
assert_eq!(Provider::Dropbox.to_string(), "Dropbox");
assert_eq!(Provider::StandardWebhooks.to_string(), "StandardWebhooks");
let custom = Provider::Custom(CustomScheme {
hash: HashAlg::Sha256,
signature_header: "X-My-Sig",
timestamp_header: None,
encoding: Encoding::Hex,
prefix: None,
signed_string: |_h, b| b.to_vec(),
});
assert_eq!(custom.to_string(), "Custom(X-My-Sig)");
}
}