Crate http_signatures [] [src]

HTTP Signatures, an implementation of the http signatures specification

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.

use http_signatures::{HttpSignature, SignatureAlgorithm, ShaSize};
use http_signatures::REQUEST_TARGET;

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 algorithm = SignatureAlgorithm::RSA(ShaSize::FiveTwelve);
let key_id = "1".into();

let auth_header = HttpSignature::new(key_id, priv_key, algorithm, headers)?
    .authorization_header()?;

println!("Authorization: {}", auth_header);

Verifying an HTTP Signature

To verify a header, one must implement a type called GetKey. This type is imporant because it contains the information required to convert a key id, represented as &str, into a Key. This can be done by accessing some external state, or by storing the required state in the struct that implements GetKey.

use http_signatures::{GetKey, SignedHeader};

struct MyKeyGetter;

impl GetKey for MyKeyGetter {
    type Key = File;
    type Error = Error;

    fn get_key(self, _key_id: &str) -> Result<Self::Key, Self::Error> {
        File::open("tests/assets/public.der").map_err(Error::from)
    }
}

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

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

let key_getter = MyKeyGetter;

let auth_header = SignedHeader::new(&auth_header)?;
auth_header
    .verify(&headers, method, path, Some(query), key_getter)?;

Modules

use_hyper_client

Available with the use_hyper feature. This modulde defines the AsHttpSignature and WithHttpSignature traits for hyper::Request.

use_hyper_server

Available with the use_hyper feature. This module defines VerifyHeader for hyper::server::Request.

use_reqwest

Available with the use_reqwest feature. This module defines AsHttpSignature and WithHttpSignature for reqwest::Request.

use_rocket

Available with the use_rocket feature. This module defines VerifyHeader for rocket::Request.

Structs

HttpSignature

The HttpSignature struct, this is the entry point for creating Authorization or Signature headers. It contains all the values required for generation.

SignedHeader

The SignedHeader struct is the direct reasult of reading in the Authorization or Signature header from a given request.

Enums

Error

The root Error

ShaSize

Variations of the Sha hashing function.

SignatureAlgorithm

Which algorithm should be used to create an HTTP header.

Constants

REQUEST_TARGET

Traits

AsHttpSignature

AsHttpSignature defines a trait for getting an Authorization or Signature Header string from any type that implements it. It provides three methods: as_http_signature, which implementors must define, and authorization_header and signature_header, which use as_http_signature to create the header string.

GetKey

The GetKey trait is used during HTTP Signature verification to access the required decryption key based on a given key_id.

VerifyHeader

The VerifyHeader trait is meant to be implemented for the request types from http libraries (such as Hyper and Rocket). This trait makes verifying requests much easier, since the verify_authorization_header() and verify_signature_header() methods can be called directly on a Request type.

WithHttpSignature

WithHttpSignature defines a trait for adding Authorization and Signature headers to another library's request or response object.