Crate reqsign

Expand description

§reqsign

Signing HTTP requests for AWS, Azure, Google, Huawei, Aliyun, Tencent and Oracle services.

§Features

This crate provides a unified interface for signing HTTP requests across multiple cloud providers:

AWS: Signature V4 for AWS services
Azure: Azure Storage services
Google: Google Cloud services
Aliyun: Aliyun Object Storage Service (OSS)
Huawei Cloud: Object Storage Service (OBS)
Tencent Cloud: Cloud Object Storage (COS)
Oracle: Oracle Cloud services

§Request URI Contract

Requests passed to the built-in signers must already contain a valid, wire-ready URI with an authority. Construct the intended path and query structure before signing and percent-encode data components exactly once. Structural delimiters such as path / and query & remain literal; delimiter bytes that belong to data must be encoded, such as %2F for a slash inside one path segment.

Reqsign does not perform general-purpose URI encoding for callers. Existing percent escapes, query order, duplicate keys, empty values, and literal + characters are part of the caller-owned wire representation. Header authentication preserves that URI. Query authentication preserves it as a prefix and appends only protocol-encoded authentication fields.

Signer::sign is atomic with respect to the caller’s request head. On error, the method, URI, version, headers, and extensions remain unchanged. On success, only the URI and headers may change. The expires_in argument is a service-specific validity input, not a universal switch between header and query authentication.

§Quick Start

Add reqsign to your Cargo.toml:

[dependencies]
reqsign = "0.20"

By default, this includes the default-context feature which provides a ready-to-use context implementation using reqwest and tokio.

To use specific services only:

[dependencies]
reqsign = { version = "0.20", default-features = false, features = ["aws", "default-context"] }

§Examples

§Option 1: Using Default Signers (Recommended)

The easiest way to get started is using the default signers provided for each service:

use anyhow::Result;
use reqsign::aws;

#[tokio::main]
async fn main() -> Result<()> {
    // Create a default signer for AWS S3 in us-east-1
    // This will automatically:
    // - Set up HTTP client and file reader
    // - Load credentials from environment, config files, or instance metadata
    let signer = aws::default_signer("s3", "us-east-1");

    // Build and sign a request
    let mut req = http::Request::builder()
        .method(http::Method::GET)
        .uri("https://s3.amazonaws.com/my-bucket/my-object")
        .body(())
        .unwrap()
        .into_parts()
        .0;

    signer.sign(&mut req, None).await?;

    println!("Request signed successfully!");
    Ok(())
}

§Option 2: Custom Assembly

For more control, you can manually assemble the signer components:

use anyhow::Result;
use reqsign::{Context, Signer, default_context};
use reqsign::aws::{DefaultCredentialProvider, RequestSigner};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a context with default implementations
    let ctx = default_context();

    // Or build your own context with specific implementations
    let ctx = Context::new()
        .with_file_read(reqsign_file_read_tokio::TokioFileRead)
        .with_http_send(reqsign_http_send_reqwest::ReqwestHttpSend::default())
        .with_env(reqsign::OsEnv);

    // Configure credential provider and request signer
    let credential_provider = DefaultCredentialProvider::new();
    let request_signer = RequestSigner::new("s3", "us-east-1");

    // Assemble the signer
    let signer = Signer::new(ctx, credential_provider, request_signer);

    // Build and sign a request
    let mut req = http::Request::builder()
        .method(http::Method::GET)
        .uri("https://s3.amazonaws.com/my-bucket/my-object")
        .body(())
        .unwrap()
        .into_parts()
        .0;

    signer.sign(&mut req, None).await?;

    println!("Request signed successfully!");
    Ok(())
}

§Customizing Default Signers

You can customize the default signers using the with_* methods:

use reqsign::aws;
use reqsign::aws::StaticCredentialProvider;

// Start with default signer and customize components
let signer = aws::default_signer("s3", "us-east-1")
    .with_credential_provider(StaticCredentialProvider::new(
        "my-access-key",
        "my-secret-key",
        None,  // Optional session token
    ))
    .with_context(my_custom_context);

§Examples for Other Services

// Azure Storage
use reqsign::azure;
let signer = azure::default_signer();

// Google Cloud
use reqsign::google;
let signer = google::default_signer("storage.googleapis.com");

// Aliyun OSS
use reqsign::aliyun;
let signer = aliyun::default_signer("mybucket");

// Huawei Cloud OBS
use reqsign::huaweicloud;
let signer = huaweicloud::default_signer("mybucket");

// Tencent COS
use reqsign::tencent;
let signer = tencent::default_signer();

// Oracle Cloud
use reqsign::oracle;
let signer = oracle::default_signer();

§Feature Flags

default: Enables default-context
default-context: Provides a default context implementation using reqwest and tokio
aliyun: Enable Aliyun OSS support
aws: Enable AWS services support
azure: Enable Azure Storage support
google: Enable Google Cloud support
google-credential-access-boundary-client-side: Enable client-side Google Credential Access Boundary token generation; implies google (server-side CAB is included by google)
huaweicloud: Enable Huawei Cloud OBS support
oracle: Enable Oracle Cloud support
tencent: Enable Tencent COS support

§WASM Support

This crate supports WebAssembly (WASM) targets. However, the default-context feature is not available on WASM due to platform limitations. When targeting WASM, you should:

Disable default features
Use the existing context implementations from reqsign-file-read-tokio and reqsign-http-send-reqwest crates
Or implement your own WASM-compatible context

Example for WASM:

[dependencies]
reqsign = { version = "0.20", default-features = false, features = ["aws"] }
reqsign-http-send-reqwest = "4"

Modules§

aliyunaliyun: Aliyun OSS service support with convenience APIs
awsaws-v4 or aws-v4a: AWS signing support.
azureazure: Azure Storage service support with convenience APIs
error: Error types for reqsign operations
googlegoogle: Google Cloud service support with convenience APIs
hash: Hash related utils.
huaweicloudhuaweicloud: Huawei Cloud OBS service support with convenience APIs
jwtjwt and non-WebAssembly: JWT encoding helpers.
oracleoracle: Oracle Cloud service support with convenience APIs
tencenttencent: Tencent Cloud COS service support with convenience APIs
time: Time related utils.
utils: Utility functions and types.
volcenginevolcengine: Volcengine TOS service support with convenience APIs

Structs§

CommandOutput: CommandOutput represents the output of a command execution.
Context: Context provides the context for the request signing.
Error: The error type for reqsign operations
Granter: Loads a source credential and grants a bounded service credential.
NoopCommandExecute: NoopCommandExecute is a no-op implementation that always returns an error.
NoopEnv: NoopEnv is a no-op implementation that always returns None/empty.
NoopFileRead: NoopFileRead is a no-op implementation that always returns an error.
NoopHttpSend: NoopHttpSend is a no-op implementation that always returns an error.
OsEnv: Implements Env for the OS context, both Unix style and Windows.
ProvideCredentialChain: A chain of credential providers that will be tried in order.
Signer: Loads credentials and atomically signs request heads.
SigningRequest: A service-local canonicalization view and signed-header staging area.
StaticEnv: StaticEnv provides a static env environment.

Enums§

ErrorKind: The kind of error that occurred
SigningMethod: A service-selected authentication placement.

Traits§

CommandExecute: CommandExecute is used to execute external commands for credential retrieval.
CommandExecuteDyn: CommandExecuteDyn is the dyn version of CommandExecute.
Env: Permits parameterizing the home functions via the _from variants
FileRead: FileRead is used to read the file content entirely in Vec<u8>.
FileReadDyn: FileReadDyn is the dyn version of FileRead.
GrantCredential: Service-specific credential granting.
GrantCredentialDyn: Dyn version of GrantCredential.
HttpSend: HttpSend is used to send http request during the signing process.
HttpSendDyn: HttpSendDyn is the dyn version of HttpSend.
MaybeSendNon-WebAssembly: MaybeSend is a marker to determine whether a type is Send or not.
ProvideCredential: ProvideCredential is the trait used by signer to load the credential from the environment. ` Service may require different credential to sign the request, for example, AWS require access key and secret key, while Google Cloud Storage require token.
ProvideCredentialDyn: ProvideCredentialDyn is the dyn version of ProvideCredential.
SignRequest: Service-specific request signing.
SignRequestDyn: SignRequestDyn is the dyn version of SignRequest.
SigningCredential: A credential that can distinguish cache freshness from exact usability.

Functions§

default_contextdefault-context: Create a Context with default implementations.

Type Aliases§

BoxedFutureNon-WebAssembly: BoxedFuture is the type alias of futures::future::BoxFuture.
Result: Convenience type alias for Results

Crate reqsign

Crate reqsign Copy item path

§reqsign

§Features

§Request URI Contract

§Quick Start

§Examples

§Option 1: Using Default Signers (Recommended)

§Option 2: Custom Assembly

§Customizing Default Signers

§Examples for Other Services

§Feature Flags

§WASM Support

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate reqsign