http-signatures 0.8.0

// This file is part of HTTP Signatures

// HTTP Signatures is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.

// HTTP Signatures is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.

// You should have received a copy of the GNU General Public License
// along with HTTP Signatures  If not, see <http://www.gnu.org/licenses/>.

//! HTTP Signatures, an implementation of [the http signatures specification](https://tools.ietf.org/html/draft-cavage-http-signatures-09)
//!
//! The base crate provides types for creating and verifying signatures, and the features
//! `use_hyper`, `use_reqwest`, and `use_rocket` provide implementations of required traits for
//! easily using HTTP Signatures with web applications.
//!
//! # Creating an HTTP Signature
//!
//! To get a string that would be the contents of an HTTP Request's Authorization header, a few
//! steps must be taken. The method, path, and query must be known, furthermore, there must be at
//! least one item in the headers hashmap, if there is not, the HTTP Signature creation will fail.
//!
//! ```rust
//! # extern crate ring;
//! # extern crate http_signatures;
//! #
//! # use ring::signature::RSAKeyPair;
//! use http_signatures::{
//!     CreateKey,
//! #   Error,
//!     HttpSignature,
//! #   Input,
//!     ShaSize,
//! #   SignatureAlgorithm,
//!     REQUEST_TARGET,
//! };
//! #
//! # use std::{fs::File, collections::BTreeMap, io::Read};
//! #
//! # fn run() -> Result<(), Error> {
//! # let mut priv_key = File::open("tests/assets/private.der")?;
//! # let mut priv_key_vec = Vec::new();
//! # priv_key.read_to_end(&mut priv_key_vec)?;
//! # let priv_key_input = Input::from(&priv_key_vec);
//! # let priv_key = RSAKeyPair::from_der(priv_key_input).unwrap();
//!
//! let method = "GET";
//! let path = "/test";
//! let query = "key=value";
//!
//! let mut headers: BTreeMap<String, Vec<String>> = BTreeMap::new();
//! headers.insert("Accept".into(), vec!["application/json".into()]);
//! headers.insert(
//!     REQUEST_TARGET.into(),
//!     vec![format!("{} {}?{}", method.to_lowercase(), path, query)],
//! );
//!
//! let priv_creation_key = CreateKey::rsa(priv_key, ShaSize::SHA512);
//! let key_id = "1".into();
//!
//! let auth_header = HttpSignature::new(key_id, priv_creation_key, headers)?
//!     .authorization_header()?;
//!
//! println!("Authorization: {}", auth_header);
//! # Ok(())
//! # }
//! # fn main() { run().unwrap(); }
//! ```
//!
//! # Verifying an HTTP Signature
//!
//! ```rust
//! # extern crate ring;
//! # extern crate http_signatures;
//! #
//! # use ring::signature::RSAKeyPair;
//! use http_signatures::{
//!     prelude::*,
//! #   CreateKey,
//!     VerifyKey,
//! #   Error,
//! #   HttpSignature,
//! #   Input,
//! #   ShaSize,
//!     SignedHeader,
//! #   REQUEST_TARGET,
//! };
//! #
//! # use std::{fs::File, collections::BTreeMap, io::Read};
//! #
//! # fn some_auth_header() -> Result<String, Error> {
//! #
//! # let mut priv_key_file = File::open("tests/assets/private.der")?;
//! # let mut priv_key_vec = Vec::new();
//! # priv_key_file.read_to_end(&mut priv_key_vec)?;
//! # let priv_key_input = Input::from(&priv_key_vec);
//! # let priv_key = RSAKeyPair::from_der(priv_key_input).unwrap();
//! # let priv_creation_key = CreateKey::rsa(priv_key, ShaSize::SHA512);
//! #
//! # let method = "GET";
//! # let path = "/test";
//! # let query = "key=value";
//! # let mut headers: BTreeMap<String, Vec<String>> = BTreeMap::new();
//! #
//! # headers.insert("Accept".into(), vec!["application/json".into()]);
//! # headers.insert(
//! #     REQUEST_TARGET.into(),
//! #     vec![format!("{} {}?{}", method.to_lowercase(), path, query)],
//! # );
//! # let key_id = "1".into();
//! # let auth_header = HttpSignature::new(key_id, priv_creation_key, headers)?
//! #   .authorization_header()?;
//! #
//! # Ok(auth_header)
//! # }
//!
//! # fn run() -> Result<(), Error> {
//! # let auth_header = some_auth_header()?;
//! # let mut pub_key_file = File::open("tests/assets/public.der")?;
//! # let mut pub_key_vec = Vec::new();
//! # pub_key_file.read_to_end(&mut pub_key_vec)?;
//!
//! let mut headers = Vec::new();
//! headers.push(("Accept".into(), "application/json".into()));
//!
//! let method = "GET";
//! let path = "/test";
//! let query = "key=value";
//!
//! let auth_header = SignedHeader::new(&auth_header)?;
//! auth_header
//!     .verify(&headers, method, path, Some(query), VerifyKey::unchecked_from_vec(pub_key_vec))?;
//!
//! # Ok(())
//! # }
//! # fn main() { run().unwrap(); }
//! ```

#[cfg(feature = "use_actix_web")]
pub mod use_actix_web_client;
#[cfg(feature = "use_actix_web")]
pub mod use_actix_web_server;
#[cfg(feature = "use_hyper")]
pub mod use_hyper_client;
#[cfg(feature = "use_hyper")]
pub mod use_hyper_server;
#[cfg(feature = "use_reqwest")]
pub mod use_reqwest;
#[cfg(feature = "use_rocket")]
pub mod use_rocket;

mod create;
mod error;
pub mod prelude;
mod verify;

use std::str::FromStr;

use ring::{
    digest::{Algorithm, SHA256, SHA384, SHA512},
    signature::{
        RSAEncoding, VerificationAlgorithm, RSA_PKCS1_2048_8192_SHA256, RSA_PKCS1_2048_8192_SHA384,
        RSA_PKCS1_2048_8192_SHA512, RSA_PKCS1_SHA256, RSA_PKCS1_SHA384, RSA_PKCS1_SHA512,
    },
};

use self::error::DecodeError;

pub use self::{
    create::{CreateKey, HttpSignature},
    error::Error,
    verify::{SignedHeader, VerifyKey},
};

pub const REQUEST_TARGET: &str = "(request-target)";

/// Variations of the Sha hashing function.
///
/// This stuct is used to tell the RSA and HMAC signature functions how big the sha hash should be.
/// It currently offers three variations.
#[derive(Clone, Copy, Debug)]
pub enum ShaSize {
    /// SHA256
    SHA256,

    /// SHA384
    SHA384,

    /// SHA512
    SHA512,
}

impl ShaSize {
    pub fn hmac_algorithm(self) -> &'static Algorithm {
        match self {
            ShaSize::SHA256 => &SHA256,
            ShaSize::SHA384 => &SHA384,
            ShaSize::SHA512 => &SHA512,
        }
    }

    pub fn rsa_algorithm(self) -> &'static dyn RSAEncoding {
        match self {
            ShaSize::SHA256 => &RSA_PKCS1_SHA256,
            ShaSize::SHA384 => &RSA_PKCS1_SHA384,
            ShaSize::SHA512 => &RSA_PKCS1_SHA512,
        }
    }

    pub fn verification_algorithm(self) -> &'static dyn VerificationAlgorithm {
        match self {
            ShaSize::SHA256 => &RSA_PKCS1_2048_8192_SHA256,
            ShaSize::SHA384 => &RSA_PKCS1_2048_8192_SHA384,
            ShaSize::SHA512 => &RSA_PKCS1_2048_8192_SHA512,
        }
    }
}

/// Which algorithm should be used to create an HTTP header.
///
/// This library uses Ring 0.11.0 for creating and verifying hashes, so this determines whether the
/// library will use Ring's RSA Signatures or Rings's HMAC signatures.
#[derive(Clone, Copy, Debug)]
pub enum SignatureAlgorithm {
    /// RSA
    RSA(ShaSize),
    /// HMAC
    HMAC(ShaSize),
}

/// Convert an `&str` into a `SignatureAlgorithm`
impl FromStr for SignatureAlgorithm {
    type Err = DecodeError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "rsa-sha256" => Ok(SignatureAlgorithm::RSA(ShaSize::SHA256)),
            "rsa-sha384" => Ok(SignatureAlgorithm::RSA(ShaSize::SHA384)),
            "rsa-sha512" => Ok(SignatureAlgorithm::RSA(ShaSize::SHA512)),
            "hmac-sha256" => Ok(SignatureAlgorithm::HMAC(ShaSize::SHA256)),
            "hmac-sha384" => Ok(SignatureAlgorithm::HMAC(ShaSize::SHA384)),
            "hmac-sha512" => Ok(SignatureAlgorithm::HMAC(ShaSize::SHA512)),
            e => Err(DecodeError::InvalidAlgorithm(e.into())),
        }
    }
}

/// Convert a `SignatureAlgorithm` into an `&str`
impl From<SignatureAlgorithm> for &'static str {
    fn from(alg: SignatureAlgorithm) -> Self {
        match alg {
            SignatureAlgorithm::RSA(size) => match size {
                ShaSize::SHA256 => "rsa-sha256",
                ShaSize::SHA384 => "rsa-sha384",
                ShaSize::SHA512 => "rsa-sha512",
            },
            SignatureAlgorithm::HMAC(size) => match size {
                ShaSize::SHA256 => "hmac-sha256",
                ShaSize::SHA384 => "hmac-sha384",
                ShaSize::SHA512 => "hmac-sha512",
            },
        }
    }
}

#[cfg(test)]
mod tests {
    use ring::{
        hmac::{self, SigningKey},
        rand,
        signature::RSAKeyPair,
    };
    use untrusted::Input;

    use std::{collections::BTreeMap, fs::File};

    use crate::{
        create::{CreateKey, HttpSignature},
        verify::{SignedHeader, VerifyKey},
        ShaSize, REQUEST_TARGET,
    };

    #[test]
    fn hmac_256_can_sign_and_verify() {
        hmac_can_sign_and_verify(ShaSize::SHA256);
    }

    #[test]
    fn hmac_384_can_sign_and_verify() {
        hmac_can_sign_and_verify(ShaSize::SHA384);
    }

    #[test]
    fn hmac_512_can_sign_and_verify() {
        hmac_can_sign_and_verify(ShaSize::SHA512);
    }

    #[test]
    fn rsa_256_can_sign_and_verify() {
        rsa_can_sign_and_verify(ShaSize::SHA256);
    }

    #[test]
    fn rsa_384_can_sign_and_verify() {
        rsa_can_sign_and_verify(ShaSize::SHA384);
    }

    #[test]
    fn rsa_512_can_sign_and_verify() {
        rsa_can_sign_and_verify(ShaSize::SHA512);
    }

    fn hmac_can_sign_and_verify(sha_size: ShaSize) {
        let algorithm = sha_size.hmac_algorithm();
        let rng = rand::SystemRandom::new();
        let len = hmac::recommended_key_len(&algorithm);
        let mut key_vec: Vec<u8> = Vec::new();
        for _ in 0..len {
            key_vec.push(0);
        }
        let _ =
            SigningKey::generate_serializable(&algorithm, &rng, key_vec.as_mut_slice()).unwrap();
        let key = SigningKey::new(&algorithm, key_vec.as_ref());
        let creation_key = CreateKey::hmac(key, sha_size);

        let method = "GET";
        let path = "/test";
        let query = "key=value";

        let mut headers_one: BTreeMap<String, Vec<String>> = BTreeMap::new();
        headers_one.insert("Accept".into(), vec!["application/json".into()]);
        headers_one.insert(
            REQUEST_TARGET.into(),
            vec![format!("{} {}?{}", method.to_lowercase(), path, query)],
        );

        let mut headers_two = Vec::new();
        headers_two.push(("Accept".into(), "application/json".into()));

        let key_id = "1".into();

        let auth_header = HttpSignature::new(key_id, creation_key, headers_one)
            .unwrap()
            .authorization_header()
            .unwrap();

        let auth_header = SignedHeader::new(&auth_header).unwrap();

        auth_header
            .verify(
                &headers_two,
                method,
                path,
                Some(query),
                VerifyKey::unchecked_from_vec(key_vec),
            )
            .unwrap();
    }

    fn rsa_can_sign_and_verify(sha_size: ShaSize) {
        use std::io::Read;

        let mut priv_key = File::open("tests/assets/private.der").unwrap();
        let mut priv_key_vec = Vec::new();
        priv_key.read_to_end(&mut priv_key_vec).unwrap();
        let priv_key_input = Input::from(&priv_key_vec);
        let priv_key = RSAKeyPair::from_der(priv_key_input).unwrap();
        let priv_creation_key = CreateKey::rsa(priv_key, sha_size);

        let mut pub_key = File::open("tests/assets/public.der").unwrap();
        let mut pub_key_vec = Vec::new();
        pub_key.read_to_end(&mut pub_key_vec).unwrap();

        let method = "GET";
        let path = "/test";
        let query = "key=value";

        let mut headers_one: BTreeMap<String, Vec<String>> = BTreeMap::new();
        headers_one.insert("Accept".into(), vec!["application/json".into()]);
        headers_one.insert(
            REQUEST_TARGET.into(),
            vec![format!("{} {}?{}", method.to_lowercase(), path, query)],
        );

        let mut headers_two = Vec::new();
        headers_two.push(("Accept".into(), "application/json".into()));

        let key_id = "1".into();

        let auth_header = HttpSignature::new(key_id, priv_creation_key, headers_one)
            .unwrap()
            .signature_header()
            .unwrap();

        let auth_header = SignedHeader::new(&auth_header).unwrap();

        auth_header
            .verify(
                &headers_two,
                method,
                path,
                Some(query),
                VerifyKey::unchecked_from_vec(pub_key_vec),
            )
            .unwrap();
    }
}