#![deny(clippy::unwrap_used, clippy::expect_used)]
use alloc::vec::Vec;
use crate::core::VerifyOptions;
use crate::core::crypto::verify_hmac_sha256;
use crate::core::error::VerifyError;
use crate::core::headers::HeaderMap;
use crate::core::secret::Secret;
pub(crate) const SIGNATURE_HEADER: &str = "X-Hub-Signature-256";
const SIGNATURE_PREFIX: &str = "sha256=";
const SIGNATURE_LEN_BYTES: usize = 32;
pub(crate) fn verify(
headers: &dyn HeaderMap,
raw_body: &[u8],
secret: &Secret,
_options: &VerifyOptions,
) -> Result<(), VerifyError> {
let value = headers
.get(SIGNATURE_HEADER)
.ok_or(VerifyError::MissingHeader {
header: SIGNATURE_HEADER,
})?;
let provided = parse_signature(value)?;
if verify_hmac_sha256(secret.as_bytes(), raw_body, &provided) {
Ok(())
} else {
Err(VerifyError::SignatureMismatch)
}
}
fn parse_signature(value: &str) -> Result<Vec<u8>, VerifyError> {
if value.is_empty() {
return Err(VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "header is empty",
});
}
let hex_part = match value.get(..SIGNATURE_PREFIX.len()) {
Some(prefix) if prefix.eq_ignore_ascii_case(SIGNATURE_PREFIX) => {
&value[SIGNATURE_PREFIX.len()..]
}
_ => {
return Err(VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "missing `sha256=` prefix",
});
}
};
if hex_part.is_empty() {
return Err(VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "empty signature after `sha256=` prefix",
});
}
let bytes = hex::decode(hex_part).map_err(|_| VerifyError::BadEncoding {
reason: "signature is not valid hexadecimal",
})?;
if bytes.len() != SIGNATURE_LEN_BYTES {
return Err(VerifyError::BadEncoding {
reason: "signature does not decode to 32 bytes",
});
}
Ok(bytes)
}
#[cfg(test)]
mod tests {
use super::SIGNATURE_HEADER;
use crate::core::error::VerifyError;
use crate::core::secret::Secret;
use crate::verify;
use std::time::Duration;
const OFFICIAL_SECRET: &str = "It's a Secret to Everybody";
const OFFICIAL_BODY: &[u8] = b"Hello, World!";
const OFFICIAL_SIGNATURE: &str =
"757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17";
const EMPTY_BODY_SIGNATURE: &str =
"66a0c074deaa0f489ead6537e0d32f9a344b90bbeda705b6ed45ecd3b413fb40";
const UNICODE_BODY_SIGNATURE: &str =
"815772f88bf8950c7457b57856f4b33ca9d07e7ef7a50646b067b4a613f735c4";
fn github_headers(signature: &str) -> Vec<(String, String)> {
vec![(SIGNATURE_HEADER.to_string(), format!("sha256={signature}"))]
}
fn verify_official(body: &[u8], signature: &str) -> Result<(), VerifyError> {
verify(
crate::Provider::GitHub,
&github_headers(signature),
body,
&Secret::new(OFFICIAL_SECRET),
Default::default(),
)
}
#[test]
fn official_vector_from_github_docs() {
assert_eq!(verify_official(OFFICIAL_BODY, OFFICIAL_SIGNATURE), Ok(()));
}
#[test]
fn locally_constructed_boundary_bodies_verify() {
assert_eq!(verify_official(b"", EMPTY_BODY_SIGNATURE), Ok(()));
assert_eq!(
verify_official("héllo, 🦀 world!".as_bytes(), UNICODE_BODY_SIGNATURE),
Ok(())
);
}
#[test]
fn header_name_lookup_is_case_insensitive() {
let result = verify(
crate::Provider::GitHub,
&[(
"x-hub-signature-256",
"sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17",
)],
OFFICIAL_BODY,
&Secret::new(OFFICIAL_SECRET),
Default::default(),
);
assert_eq!(result, Ok(()));
}
#[test]
fn uppercase_hex_is_accepted() {
let upper = OFFICIAL_SIGNATURE.to_ascii_uppercase();
assert_eq!(verify_official(OFFICIAL_BODY, &upper), Ok(()));
}
#[test]
fn negative_flipped_signature_byte_fails() {
let sig = format!(
"{}{}{}",
&OFFICIAL_SIGNATURE[..10],
if OFFICIAL_SIGNATURE[10..11] == *"0" {
"1"
} else {
"0"
},
&OFFICIAL_SIGNATURE[11..]
);
assert_ne!(sig, OFFICIAL_SIGNATURE);
assert_eq!(
verify_official(OFFICIAL_BODY, &sig),
Err(VerifyError::SignatureMismatch)
);
}
#[test]
fn tampered_body_fails() {
let tampered = b"Hello, World?";
assert_eq!(
verify_official(tampered, OFFICIAL_SIGNATURE),
Err(VerifyError::SignatureMismatch)
);
}
#[test]
fn wrong_secret_fails() {
let result = verify(
crate::Provider::GitHub,
&github_headers(OFFICIAL_SIGNATURE),
OFFICIAL_BODY,
&Secret::new("a different secret"),
Default::default(),
);
assert_eq!(result, Err(VerifyError::SignatureMismatch));
}
#[test]
fn max_age_has_no_effect_for_github() {
let options = crate::core::VerifyOptions {
max_age: Some(Duration::ZERO),
..crate::core::VerifyOptions::default()
};
let result = verify(
crate::Provider::GitHub,
&github_headers(OFFICIAL_SIGNATURE),
OFFICIAL_BODY,
&Secret::new(OFFICIAL_SECRET),
options,
);
assert_eq!(result, Ok(()));
}
#[test]
fn missing_header_errors_distinctly() {
let result = verify(
crate::Provider::GitHub,
&Vec::<(String, String)>::new(),
OFFICIAL_BODY,
&Secret::new(OFFICIAL_SECRET),
Default::default(),
);
assert_eq!(
result,
Err(VerifyError::MissingHeader {
header: SIGNATURE_HEADER
})
);
}
#[test]
fn malformed_header_shapes_error_distinctly() {
let cases: &[(&str, VerifyError)] = &[
(
"",
VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "header is empty",
},
),
(
"sha256=",
VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "empty signature after `sha256=` prefix",
},
),
(
"deadbeef",
VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "missing `sha256=` prefix",
},
),
(
"sha1=deadbeef",
VerifyError::MalformedHeader {
header: SIGNATURE_HEADER,
reason: "missing `sha256=` prefix",
},
),
];
for &(value, expected) in cases {
let result = verify(
crate::Provider::GitHub,
&[(SIGNATURE_HEADER, value)],
OFFICIAL_BODY,
&Secret::new(OFFICIAL_SECRET),
Default::default(),
);
assert_eq!(result, Err(expected), "input: {value:?}");
}
}
#[test]
fn bad_encoding_errors_distinctly() {
let cases: &[&str] = &[
"sha256=zzzz",
"sha256=abc",
"sha256=deadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
];
for &value in cases {
let result = verify(
crate::Provider::GitHub,
&[(SIGNATURE_HEADER, value)],
OFFICIAL_BODY,
&Secret::new(OFFICIAL_SECRET),
Default::default(),
);
match result {
Err(VerifyError::BadEncoding { .. }) => {}
other => panic!("expected BadEncoding for {value:?}, got {other:?}"),
}
}
}
}