Add documentation to a number of elements

Author: dacut

Cargo.toml

@@ -37,4 +37,5 @@ tower = { version = "^0.4", features = [ "util" ] }
 [dev-dependencies]
 env_logger = "^0.11"
 tokio = { version = "^1.38", features = [ "macros", "rt" ] }
+tokio-test = "^0.4"
 test-log = "0.2"

src/canonical.rs

@@ -632,6 +632,14 @@ pub struct SignedHeaderRequirements {
 }
 
 impl SignedHeaderRequirements {
+    /// Create a new `SignedHeaderRequirements` structure from the provided data.
+    ///
+    /// # Parameters
+    /// * `always_present`: Headers in addition to the standard AWS SigV4 headers that must be
+    ///   present and signed.
+    /// * `if_in_request`: Headers that must be signed if they are present in the request.
+    /// * `prefixes`: Prefixes that must be signed if any headers with that prefix are present in
+    ///   the request.
     pub fn new(mut always_present: Vec<String>, mut if_in_request: Vec<String>, mut prefixes: Vec<String>) -> Self {
         always_present.sort();
         if_in_request.sort();
@@ -644,47 +652,59 @@ impl SignedHeaderRequirements {
         }
     }
 
-    #[inline]
+    /// Return the headers that must always be present in SignedHeaders.
+    #[inline(always)]
     pub fn always_present(&self) -> &[String] {
         &self.always_present
     }
 
-    #[inline]
+    /// Return the headers that must be present in SignedHeaders if they are present in the request.
+    #[inline(always)]
     pub fn if_in_request(&self) -> &[String] {
         &self.if_in_request
     }
 
-    #[inline]
+    /// Return the prefixes that must be present in SignedHeaders if any headers with that prefix.
+    #[inline(always)]
     pub fn prefixes(&self) -> &[String] {
         &self.prefixes
     }
 
+    /// Adds an additional header that must always be present in SignedHeaders.
     pub fn add_always_present(&mut self, header: &str) {
         self.always_present.push(header.to_string());
         self.always_present.sort();
         self.always_present.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
     }
 
+    /// Adds an additional header that must be present in SignedHeaders if it is present in the
+    /// request.
     pub fn add_if_in_request(&mut self, header: &str) {
         self.if_in_request.push(header.to_string());
         self.if_in_request.sort();
         self.if_in_request.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
     }
 
+    /// Adds an additional prefix that must be present in SignedHeaders if any headers with that
+    /// prefix are present in the request.
     pub fn add_prefix(&mut self, prefix: &str) {
         self.prefixes.push(prefix.to_string());
         self.prefixes.sort();
         self.prefixes.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
     }
 
+    /// Removes a header that must always be present in SignedHeaders.
     pub fn remove_always_present(&mut self, header: &str) {
         self.always_present.retain(|h| !h.eq_ignore_ascii_case(header));
     }
 
+    /// Removes a header that must be present in SignedHeaders if it is present in the request.
     pub fn remove_if_in_request(&mut self, header: &str) {
         self.if_in_request.retain(|h| !h.eq_ignore_ascii_case(header));
     }
 
+    /// Removes a prefix that must be present in SignedHeaders if any headers with that prefix are
+    /// present in the request.
     pub fn remove_prefix(&mut self, prefix: &str) {
         self.prefixes.retain(|p| !p.eq_ignore_ascii_case(prefix));
     }

src/lib.rs

@@ -1,26 +1,124 @@
-#![warn(clippy::all)]
-
-//! The `aws_sig_verify` crate provides AWS SigV4 _verification_ routines. This *is not* the library you want if you
-//! just want to call AWS services or other services that use AWS SigV4 signatures.
-//! [Rusoto](https://github.com/rusoto/rusoto) already has a library,
-//! [rusoto_signature](https://docs.rs/rusoto_signature/), that provides this functionality.
+//! AWS API request signatures verification routines.
+//!
+//! The `scratchstack_aws_signature` crate provides
+//! AWS [SigV4](http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)
+//! _validation_ routines. This *is not* the library you want if you just want to call AWS services
+//! or other services that use AWS SigV4 signatures. [Rusoto](https://github.com/rusoto/rusoto)
+//! already has a library, [rusoto_signature](https://docs.rs/rusoto_signature/), that provides
+//! this functionality.
+//!
+//! If you are attempting to perform AWS SigV4 verification using AWS-vended credentials, this
+//! library also ___will not work for you___. You need the caller's secret key (or a derivative),
+//! and AWS does not allow this for obvious reasons. Instead, you should be using [API Gateway with
+//! IAM authentication](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html).
+//!
+//! On the other hand, if you have your own ecosystem of AWS-like credentials and are developing
+//! mock-AWS services or other services that need to use AWS SigV4, this _might_ be the right
+//! crate for you.
+//!
+//! # Workflow
+//! This assumes you have a complete HTTP request (headers _and_ body) already. As a result, you may not be able to
+//! implement this as a middleware layer for a web server—those typically only provide the headers. Having the body is
+//! required for almost all modes of AWS SigV4.
+//!
+//! The typical workflow is:
+//! 1. Convert an HTTP `Request` object into a scratchstack `Request` object.
+//! 2. Create a `GetSigningKeyRequest` from this `Request`.
+//! 3. Call your service to obtain the principal and signing key for this request.
+//! 4. Verify the request using `sigv4_verify` or `sigv4_verify_at`.
+//!
+//! ## Example
+//! ```rust
+//! use chrono::{DateTime, NaiveDate, NaiveDateTime, NaiveTime, Utc};
+//! use http::Request;
+//! use scratchstack_aws_principal::{Principal, User};
+//! use scratchstack_aws_signature::{
+//!     GetSigningKeyRequest, GetSigningKeyResponse, KSecretKey, SignatureOptions,
+//!     SignedHeaderRequirements, service_for_signing_key_fn, sigv4_validate_request,
+//! };
+//! use tower::{BoxError, Service};
+//!
+//! const ACCESS_KEY: &str = "AKIAIOSFODNN7EXAMPLE";
+//! const SECRET_KEY: &str = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY";
+//! const ACCOUNT_ID: &str = "123456789012";
+//! const PARTITION: &str = "aws";
+//! const PATH: &str = "/engineering/";
+//! const REGION: &str = "us-east-1";
+//! const SERVICE: &str = "example";
+//! const USER_NAME: &str = "user";
+//! const USER_ID: &str = "AIDAQXZEAEXAMPLEUSER";
+//!
+//! // The date for which the signature calculation was made.
+//! #[allow(deprecated)]
+//! const TEST_TIMESTAMP: DateTime<Utc> = DateTime::<Utc>::from_naive_utc_and_offset(
+//!     NaiveDateTime::new(
+//!         NaiveDate::from_ymd(2021, 1, 1),
+//!         NaiveTime::from_hms(0, 0, 0)),
+//!     Utc
+//! );
+//!
+//! // This is a mock function that returns a static secret key converted into the requested type
+//! // of signing key. For actual use, you would call out to a database or other service to obtain
+//! // a signing key.
+//! async fn get_signing_key(
+//!     request: GetSigningKeyRequest)
+//! -> Result<GetSigningKeyResponse, BoxError> {
+//!     assert_eq!(request.access_key(), ACCESS_KEY);
+//!     assert_eq!(request.region(), REGION);
+//!     assert_eq!(request.service(), SERVICE);
+//!     let user = User::new(PARTITION, ACCOUNT_ID, PATH, USER_NAME)?;
+//!     let secret_key = KSecretKey::from_str(SECRET_KEY);
+//!     let signing_key = secret_key.to_ksigning(request.request_date(), REGION, SERVICE);
+//!     Ok(GetSigningKeyResponse::builder()
+//!            .principal(user)
+//!            .signing_key(signing_key)
+//!            .build()?)
+//! }
+//!
+//! // Wrap `get_signing_key` in a `tower::Service`.
+//! let mut get_signing_key_service = service_for_signing_key_fn(get_signing_key);
+//!
+//! // Normally this would come from your web framework.
+//! let req = Request::get("https://example.com")
+//!     .header("Host", "example.com")
+//!     .header("X-Amz-Date", "20210101T000000Z")
+//!     .header("Authorization", "AWS4-HMAC-SHA256 \
+//! Credential=AKIAIOSFODNN7EXAMPLE/20210101/us-east-1/example/aws4_request, \
+//! SignedHeaders=host;x-amz-date, \
+//! Signature=3ea4679d2ecf5a8293e1fb10298c82988f024a2e937e9b37876b34bb119da0bc")
+//!     .body(())
+//!     .unwrap();
+//!
+//! // The headers that _must_ be signed (beyond the default SigV4 headers) for this service.
+//! // In this case, we're not requiring any additional headers.
+//! let signed_headers = SignedHeaderRequirements::default();
 //!
-//! If you are attempting to perform AWS SigV4 verification using AWS-vended credentials, this library also
-//! ___will not work for you___. You need the caller's secret key (or a derivative), and AWS does not allow this for
-//! obvious reasons. Instead, you should be using [API Gateway with IAM
-//! authentication](https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html).
+//! // Signature options for the request. Defaults are typically used, except for S3.
+//! let signature_options = SignatureOptions::default();
 //!
-//! On the other hand, if you have your own ecosystem of AWS-like credentials and are developing mock-AWS services or
-//! just really like AWS SigV4 but can't run within AWS, this library _might_ be for you.
+//! # tokio_test::block_on(async {
+//! // Validate the request.
+//! let (parts, body, auth) = sigv4_validate_request(
+//!     req, &REGION, &SERVICE, &mut get_signing_key_service, TEST_TIMESTAMP, &signed_headers,
+//!     signature_options).await.unwrap();
 //!
-#![allow(clippy::all)]
+//! // The principal we expect to be associated with the request.
+//! let expected_principal: Principal = User::new(PARTITION, ACCOUNT_ID, PATH, USER_NAME)
+//!     .unwrap()
+//!     .into();
+//! assert_eq!(auth.principal(), &expected_principal);
+//! # });
+//! ```
+#![warn(missing_docs)]
+#![deny(rustdoc::broken_intra_doc_links)]
+#![warn(rustdoc::missing_crate_level_docs)]
 
 mod auth;
-pub mod canonical;
+mod canonical;
 mod chronoutil;
 mod crypto;
 mod error;
-pub mod signature;
+mod signature;
 mod signing_key;
 
 pub use {

src/signature.rs

@@ -23,14 +23,25 @@ pub struct SignatureOptions {
 }
 
 impl SignatureOptions {
-    #[inline]
-    pub fn url_encode_form() -> Self {
+    /// Create a `SignatureOptions` suitable for use with services that treat
+    /// `application/x-www-form-urlencoded` bodies as part of the query string.
+    ///
+    /// Some AWS services require this behavior. This typically happens when a query string is too
+    /// long to fit in the URL, so a `GET` request is transformed into a `POST` request with the
+    /// query string passed as an HTML form.
+    ///
+    /// This sets `s3` to `false` and `url_encode_form` to `true`.
+    pub const fn url_encode_form() -> Self {
         Self {
             s3: false,
             url_encode_form: true,
         }
     }
 
+    /// Create a `SignatureOptions` suitable for use with S3-type authentication.
+    ///
+    /// This sets `s3` to `true` and `url_encode_form` to `false`, resulting in AWS SigV4S3-style
+    /// canonicalization.
     pub const S3: Self = Self {
         s3: true,
         url_encode_form: false,
@@ -40,6 +51,34 @@ impl SignatureOptions {
 /// Default allowed timestamp mismatch in minutes.
 const ALLOWED_MISMATCH_MINUTES: i64 = 15;
 
+/// Validate an AWS SigV4 request.
+///
+/// This takes in an HTTP [`Request`] along with other service-specific paramters. If the
+/// validation is successful (i.e. the request is properly signed with a known access key), this
+/// returns:
+/// * The request headers (as HTTP [`Parts`]).
+/// * The request body (as a [`Bytes`] object, which is empty if no body was provided).
+/// * The [response from the authenticator][SigV4AuthenticatorResponse], which contains the
+///   principal and other session data.
+///
+/// # Parameters
+/// * `request` - The HTTP [`Request`] to validate.
+/// * `region` - The AWS region in which the request is being made.
+/// * `service` - The AWS service to which the request is being made.
+/// * `get_signing_key` - A service that can provide the signing key for the request.
+/// * `server_timestamp` - The timestamp of the server when the request was received. Usually this
+///   is the current time, `Utc::now()`.
+/// * `required_headers` - The headers that are required to be signed in the request in addition to
+///   the default SigV4 headers. If none, use
+///   [`&SignedHeaderRequirements::default()`][SignedHeaderRequirements::default].
+/// * `options` - [`SignatureOptions`]` that affect the behavior of the signature validation. For
+///   most services, use `SignatureOptions::default()`.
+///
+/// # Errors
+/// This function returns a [`SignatureError`][crate::SignatureError] if the HTTP request is
+/// malformed or the request was not properly signed. The validation follows the
+/// [AWS Auth Error Ordering](https://github.com/dacut/scratchstack-aws-signature/blob/main/docs/AWS%20Auth%20Error%20Ordering.pdf)
+/// document.
 pub async fn sigv4_validate_request<B, S, F>(
     request: Request<B>,
     region: &str,
@@ -73,27 +112,43 @@ where
     Ok((parts, body, sigv4_response))
 }
 
+/// A trait for converting various body types into a [`Bytes`] object.
+///
+/// This requires reading the entire body into memory.
 #[async_trait]
 pub trait IntoRequestBytes {
+    /// Convert this object into a [`Bytes`] object.
     async fn into_request_bytes(self) -> Result<Bytes, BoxError>;
 }
 
+/// Convert the unit type `()` into an empty [`Bytes`] object.
 #[async_trait]
 impl IntoRequestBytes for () {
+    /// Convert the unit type `()` into an empty [`Bytes`] object.
+    ///
+    /// This is infalliable.
     async fn into_request_bytes(self) -> Result<Bytes, BoxError> {
         Ok(Bytes::new())
     }
 }
 
+/// Convert a `Vec<u8>` into a [`Bytes`] object.
 #[async_trait]
 impl IntoRequestBytes for Vec<u8> {
+    /// Convert a `Vec<u8>` into a [`Bytes`] object.
+    ///
+    /// This is infalliable.
     async fn into_request_bytes(self) -> Result<Bytes, BoxError> {
         Ok(Bytes::from(self))
     }
 }
 
+/// Identity transformation: return the [`Bytes`] object as-is.
 #[async_trait]
 impl IntoRequestBytes for Bytes {
+    /// Identity transformation: return the [`Bytes`] object as-is.
+    ///
+    /// This is infalliable.
     async fn into_request_bytes(self) -> Result<Bytes, BoxError> {
         Ok(self)
     }

src/signing_key.rs

@@ -45,7 +45,7 @@ pub struct KServiceKey {
 /// The `kSigning` key: an AWS `kService` key, HMAC-SHA256 hashed with the "aws4_request" string.
 #[derive(Clone, Copy, PartialEq, Eq)]
 pub struct KSigningKey {
-    /// The raw key.
+    /// The resulting raw signing key.
     key: [u8; SHA256_OUTPUT_LEN],
 }