299 lines
8.7 KiB
Rust
299 lines
8.7 KiB
Rust
#![deny(missing_docs)]
|
|
|
|
//! # HTTP Signature Normaliztion
|
|
//! _An HTTP Signatures library that leaves the signing to you_
|
|
//!
|
|
//! - [crates.io](https://crates.io/crates/http-signature-normalization)
|
|
//! - [docs.rs](https://docs.rs/http-signature-normalization)
|
|
//! - [Join the discussion on Matrix](https://matrix.to/#/!IRQaBCMWKbpBWKjQgx:asonix.dog?via=asonix.dog)
|
|
//!
|
|
//! Http Signature Normalization is a minimal-dependency crate for producing HTTP Signatures with user-provided signing and verification. The API is simple; there's a series of steps for creation and verification with types that ensure reasonable usage.
|
|
//!
|
|
//! ```rust
|
|
//! use chrono::Duration;
|
|
//! use http_signature_normalization::Config;
|
|
//! use std::collections::BTreeMap;
|
|
//!
|
|
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! let config = Config {
|
|
//! expires_after: Duration::seconds(5),
|
|
//! };
|
|
//!
|
|
//! let headers = BTreeMap::new();
|
|
//!
|
|
//! let signature_header_value = config
|
|
//! .begin_sign("GET", "/foo?bar=baz", headers)
|
|
//! .sign("my-key-id".to_owned(), |signing_string| {
|
|
//! // sign the string here
|
|
//! Ok(signing_string.to_owned()) as Result<_, Box<dyn std::error::Error>>
|
|
//! })?
|
|
//! .signature_header();
|
|
//!
|
|
//! let mut headers = BTreeMap::new();
|
|
//! headers.insert("Signature".to_owned(), signature_header_value);
|
|
//!
|
|
//! let verified = config
|
|
//! .begin_verify("GET", "/foo?bar=baz", headers)?
|
|
//! .verify(|sig, signing_string| {
|
|
//! // Verify the signature here
|
|
//! sig == signing_string
|
|
//! });
|
|
//!
|
|
//! assert!(verified);
|
|
//! Ok(())
|
|
//! }
|
|
//! ```
|
|
|
|
use chrono::{DateTime, Duration, Utc};
|
|
use std::{collections::BTreeMap, error::Error, fmt};
|
|
|
|
pub mod create;
|
|
pub mod verify;
|
|
|
|
use self::{
|
|
create::Unsigned,
|
|
verify::{ParseSignatureError, ParsedHeader, Unverified, ValidateError},
|
|
};
|
|
|
|
const REQUEST_TARGET: &'static str = "(request-target)";
|
|
const CREATED: &'static str = "(created)";
|
|
const EXPIRES: &'static str = "(expires)";
|
|
|
|
const KEY_ID_FIELD: &'static str = "keyId";
|
|
const ALGORITHM_FIELD: &'static str = "algorithm";
|
|
const ALGORITHM_VALUE: &'static str = "hs2019";
|
|
const CREATED_FIELD: &'static str = "created";
|
|
const EXPIRES_FIELD: &'static str = "expires";
|
|
const HEADERS_FIELD: &'static str = "headers";
|
|
const SIGNATURE_FIELD: &'static str = "signature";
|
|
|
|
#[derive(Clone, Debug)]
|
|
/// Configuration for signing and verifying signatures
|
|
///
|
|
/// Currently, the only configuration provided is how long a signature should be considered valid
|
|
/// before it expires.
|
|
pub struct Config {
|
|
/// How long a singature is valid
|
|
pub expires_after: Duration,
|
|
}
|
|
|
|
#[derive(Debug)]
|
|
/// Error preparing a header for validation
|
|
///
|
|
/// This could be due to a missing header, and unparsable header, or an expired header
|
|
pub enum PrepareVerifyError {
|
|
/// Error validating the header
|
|
Validate(ValidateError),
|
|
/// Error parsing the header
|
|
Parse(ParseSignatureError),
|
|
}
|
|
|
|
impl Config {
|
|
/// Perform the neccessary operations to produce an [`Unsigned`] type, which can be used to
|
|
/// sign the header
|
|
pub fn begin_sign(
|
|
&self,
|
|
method: &str,
|
|
path_and_query: &str,
|
|
headers: BTreeMap<String, String>,
|
|
) -> Unsigned {
|
|
let mut headers = headers
|
|
.into_iter()
|
|
.map(|(k, v)| (k.to_lowercase(), v))
|
|
.collect();
|
|
let sig_headers = build_headers_list(&headers);
|
|
|
|
let created = Utc::now();
|
|
let expires = created + self.expires_after;
|
|
|
|
let signing_string = build_signing_string(
|
|
method,
|
|
path_and_query,
|
|
Some(created),
|
|
Some(expires),
|
|
&sig_headers,
|
|
&mut headers,
|
|
);
|
|
|
|
Unsigned {
|
|
signing_string,
|
|
sig_headers,
|
|
created,
|
|
expires,
|
|
}
|
|
}
|
|
|
|
/// Perform the neccessary operations to produce and [`Unerified`] type, which can be used to
|
|
/// verify the header
|
|
pub fn begin_verify(
|
|
&self,
|
|
method: &str,
|
|
path_and_query: &str,
|
|
headers: BTreeMap<String, String>,
|
|
) -> Result<Unverified, PrepareVerifyError> {
|
|
let mut headers: BTreeMap<String, String> = headers
|
|
.into_iter()
|
|
.map(|(k, v)| (k.to_lowercase().to_owned(), v))
|
|
.collect();
|
|
|
|
let header = headers
|
|
.remove("authorization")
|
|
.or_else(|| headers.remove("signature"))
|
|
.ok_or(ValidateError::Missing)?;
|
|
|
|
let parsed_header: ParsedHeader = header.parse()?;
|
|
let unvalidated = parsed_header.into_unvalidated(method, path_and_query, &mut headers);
|
|
|
|
Ok(unvalidated.validate(self.expires_after)?)
|
|
}
|
|
}
|
|
|
|
fn build_headers_list(btm: &BTreeMap<String, String>) -> Vec<String> {
|
|
let http_header_keys: Vec<String> = btm.keys().cloned().collect();
|
|
|
|
let mut sig_headers = vec![
|
|
REQUEST_TARGET.to_owned(),
|
|
CREATED.to_owned(),
|
|
EXPIRES.to_owned(),
|
|
];
|
|
|
|
sig_headers.extend(http_header_keys);
|
|
|
|
sig_headers
|
|
}
|
|
|
|
fn build_signing_string(
|
|
method: &str,
|
|
path_and_query: &str,
|
|
created: Option<DateTime<Utc>>,
|
|
expires: Option<DateTime<Utc>>,
|
|
sig_headers: &[String],
|
|
btm: &mut BTreeMap<String, String>,
|
|
) -> String {
|
|
let request_target = format!("{} {}", method.to_string().to_lowercase(), path_and_query);
|
|
|
|
btm.insert(REQUEST_TARGET.to_owned(), request_target.clone());
|
|
if let Some(created) = created {
|
|
btm.insert(CREATED.to_owned(), created.timestamp().to_string());
|
|
}
|
|
if let Some(expires) = expires {
|
|
btm.insert(EXPIRES.to_owned(), expires.timestamp().to_string());
|
|
}
|
|
|
|
let signing_string = sig_headers
|
|
.iter()
|
|
.filter_map(|h| btm.remove(h).map(|v| format!("{}: {}", h, v)))
|
|
.collect::<Vec<_>>()
|
|
.join("\n");
|
|
|
|
signing_string
|
|
}
|
|
|
|
impl fmt::Display for PrepareVerifyError {
|
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
|
|
match *self {
|
|
PrepareVerifyError::Validate(ref e) => fmt::Display::fmt(e, f),
|
|
PrepareVerifyError::Parse(ref e) => fmt::Display::fmt(e, f),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl Error for PrepareVerifyError {
|
|
fn description(&self) -> &str {
|
|
match *self {
|
|
PrepareVerifyError::Validate(ref e) => e.description(),
|
|
PrepareVerifyError::Parse(ref e) => e.description(),
|
|
}
|
|
}
|
|
|
|
fn source(&self) -> Option<&(dyn Error + 'static)> {
|
|
match *self {
|
|
PrepareVerifyError::Validate(ref e) => Some(e),
|
|
PrepareVerifyError::Parse(ref e) => Some(e),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl From<ValidateError> for PrepareVerifyError {
|
|
fn from(v: ValidateError) -> Self {
|
|
PrepareVerifyError::Validate(v)
|
|
}
|
|
}
|
|
|
|
impl From<ParseSignatureError> for PrepareVerifyError {
|
|
fn from(p: ParseSignatureError) -> Self {
|
|
PrepareVerifyError::Parse(p)
|
|
}
|
|
}
|
|
|
|
impl Default for Config {
|
|
fn default() -> Self {
|
|
Config {
|
|
expires_after: Duration::seconds(10),
|
|
}
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::Config;
|
|
use std::collections::BTreeMap;
|
|
|
|
fn prepare_headers() -> BTreeMap<String, String> {
|
|
let mut headers = BTreeMap::new();
|
|
headers.insert(
|
|
"Content-Type".to_owned(),
|
|
"application/activity+json".to_owned(),
|
|
);
|
|
headers
|
|
}
|
|
|
|
#[test]
|
|
fn round_trip_authorization() {
|
|
let headers = prepare_headers();
|
|
let config = Config::default();
|
|
|
|
let authorization_header = config
|
|
.begin_sign("GET", "/foo?bar=baz", headers)
|
|
.sign("hi".to_owned(), |s| {
|
|
Ok(s.to_owned()) as Result<_, std::io::Error>
|
|
})
|
|
.unwrap()
|
|
.authorization_header();
|
|
|
|
let mut headers = prepare_headers();
|
|
headers.insert("Authorization".to_owned(), authorization_header);
|
|
|
|
let verified = config
|
|
.begin_verify("GET", "/foo?bar=baz", headers)
|
|
.unwrap()
|
|
.verify(|sig, signing_string| sig == signing_string);
|
|
|
|
assert!(verified);
|
|
}
|
|
|
|
#[test]
|
|
fn round_trip_signature() {
|
|
let headers = prepare_headers();
|
|
let config = Config::default();
|
|
|
|
let signature_header = config
|
|
.begin_sign("GET", "/foo?bar=baz", headers)
|
|
.sign("hi".to_owned(), |s| {
|
|
Ok(s.to_owned()) as Result<_, std::io::Error>
|
|
})
|
|
.unwrap()
|
|
.signature_header();
|
|
|
|
let mut headers = prepare_headers();
|
|
headers.insert("Signature".to_owned(), signature_header);
|
|
|
|
let verified = config
|
|
.begin_verify("GET", "/foo?bar=baz", headers)
|
|
.unwrap()
|
|
.verify(|sig, signing_string| sig == signing_string);
|
|
|
|
assert!(verified);
|
|
}
|
|
}
|