Crate ash_core

Expand description

§ASH Core

ASH (Anti-tamper Security Hash) is a request integrity and anti-replay protection library

§Safety

This crate uses #![forbid(unsafe_code)] to guarantee 100% safe Rust. that ensures HTTP requests have not been tampered with in transit.

§What ASH Does

ASH provides cryptographic proof that:

The payload has not been modified
The request is for the correct endpoint (method + path + query)
The request is not a replay of a previous request
Optionally, only specific fields are protected (scoping)

§What ASH Does NOT Do

ASH verifies what is being submitted, not who is submitting it. Use alongside authentication systems (JWT, OAuth, API keys, etc.).

§Quick Start

use ash_core::{
    ash_canonicalize_json, ash_derive_client_secret,
    ash_build_proof, ash_verify_proof, ash_hash_body,
};

// 1. Server provides nonce and context_id to client
let nonce = "0123456789abcdef0123456789abcdef"; // 32+ hex chars
let context_id = "ctx_abc123";
let binding = "POST|/api/transfer|";

// 2. Client canonicalizes payload
let payload = r#"{"amount":100,"recipient":"alice"}"#;
let canonical = ash_canonicalize_json(payload).unwrap();

// 3. Client derives secret and builds proof
let client_secret = ash_derive_client_secret(nonce, context_id, binding).unwrap();
let body_hash = ash_hash_body(&canonical);
let timestamp = "1704067200";
let proof = ash_build_proof(&client_secret, timestamp, binding, &body_hash).unwrap();

// 4. Server verifies proof (re-derives secret from nonce internally)
let valid = ash_verify_proof(nonce, context_id, binding, timestamp, &body_hash, &proof).unwrap();
assert!(valid);

§Features

Feature	Description
Tamper Detection	HMAC-SHA256 proof ensures payload integrity
Replay Prevention	One-time contexts prevent request replay
Deterministic	Byte-identical output across all platforms
Field Scoping	Protect specific fields while allowing others to change
Request Chaining	Link sequential requests cryptographically
WASM Compatible	Works in browsers and server environments

§Module Overview

Module	Purpose
`proof`	Core proof generation and verification
`canonicalize`	Deterministic JSON/URL-encoded serialization
`compare`	Constant-time comparison functions
`config`	Scope policy configuration
`errors`	Error types and codes

§Security Considerations

Nonce entropy: Use 32+ hex characters (128+ bits) for nonces
Timestamp validation: Reject requests older than 5 minutes
HTTPS required: ASH does not encrypt data, only signs it
Context isolation: Never reuse context_id across requests

§Protocol Version

This library implements ASH Protocol v2.1 with extensions:

v2.2: Field-level scoping
v2.3: Request chaining
v2.3.2: Binding normalization (METHOD|PATH|QUERY format)
v2.3.4: Bug fixes (BUG-020 through BUG-034)
v2.3.5: Security hardening (SEC-AUDIT-005 through SEC-AUDIT-007)

Re-exports§

pub use headers::HeaderMapView;
pub use headers::HeaderBundle;
pub use headers::ash_extract_headers;
pub use binding::ash_normalize_binding_value;
pub use binding::BindingType;
pub use binding::NormalizedBindingValue;
pub use binding::MAX_BINDING_VALUE_LENGTH;
pub use build::build_request_proof;
pub use build::BuildRequestInput;
pub use build::BuildRequestResult;
pub use build::BuildMeta;
pub use enriched::ash_canonicalize_query_enriched;
pub use enriched::CanonicalQueryResult;
pub use enriched::ash_hash_body_enriched;
pub use enriched::BodyHashResult;
pub use enriched::ash_normalize_binding_enriched;
pub use enriched::ash_parse_binding;
pub use enriched::NormalizedBinding;
pub use testkit::load_vectors;
pub use testkit::load_vectors_from_file;
pub use testkit::run_vectors;
pub use testkit::AshAdapter;
pub use testkit::AdapterResult;
pub use testkit::TestReport;
pub use testkit::VectorResult;
pub use testkit::Vector;
pub use testkit::VectorFile;
pub use verify::verify_incoming_request;
pub use verify::VerifyRequestInput;
pub use verify::VerifyResult;
pub use verify::VerifyMeta;

Modules§

binding: Generic binding normalizer.
build: High-level request proof building (Phase 3-B).
config: ASH Configuration Module.
enriched: Enriched API variants (Phase 2).
headers: Canonical header extraction for ASH protocol.
testkit: Testkit — Conformance adapter runner.
verify: High-level request verification (Phase 3-A).

Structs§

AshError: Main error type for ASH operations.
BuildProofInput: Input for building a proof.
UnifiedProofResult: Result from unified proof generation.
VerifyInput: Input for verifying a proof.

Enums§

AshErrorCode: Error codes for ASH protocol.
AshMode: Security mode for ASH verification.
InternalReason: Internal diagnostic reason for errors.

Constants§

ASH_SDK_VERSION: ASH SDK version (library version).
ASH_VERSION_PREFIX: ASH protocol version prefix.
DEFAULT_CLOCK_SKEW_SECONDS: Default clock skew tolerance (60 seconds).
DEFAULT_MAX_TIMESTAMP_AGE_SECONDS: Default maximum age for timestamps (5 minutes).

Functions§

ash_build_proof: Build cryptographic proof (client-side).
ash_build_proof_scoped: Build v2.2 cryptographic proof with scoped fields.
ash_build_proof_unified: Build unified v2.3 cryptographic proof (client-side).
ash_canonicalize_json: Canonicalize a JSON string to deterministic form.
ash_canonicalize_json_value: Canonicalize a JSON Value to a deterministic string.
ash_canonicalize_json_value_with_size_check: Canonicalize a JSON Value with size validation.
ash_canonicalize_query: Canonicalize a URL query string according to ASH v2.3.1 specification.
ash_canonicalize_urlencoded: Canonicalize URL-encoded form data.
ash_derive_client_secret: Derive client secret from server nonce.
ash_extract_scoped_fields: Extract scoped fields from a JSON value.
ash_extract_scoped_fields_strict: Extract scoped fields from a JSON value with strict mode.
ash_generate_context_id: Generate a unique context ID with “ash_” prefix.
ash_generate_context_id_256: Generate a unique context ID with 256 bits of entropy.
ash_generate_nonce: Generate a cryptographically secure random nonce.
ash_generate_nonce_or_panic: Generate a cryptographically secure random nonce (convenience wrapper).
ash_hash_body: Compute SHA-256 hash of canonical body.
ash_hash_proof: Hash a proof for chaining purposes.
ash_hash_scope: Compute SHA-256 hash of scope fields. Uses unit separator (‘\x1F’) to prevent collision with field names containing commas.
ash_hash_scoped_body: Hash scoped payload for client-side use.
ash_hash_scoped_body_strict: Hash scoped payload with strict mode.
ash_normalize_binding: Normalize a binding string to canonical form (v2.3.2+ format).
ash_normalize_binding_from_url: Normalize a binding from a full URL path (including query string).
ash_timing_safe_compare: Compare two strings in constant time.
ash_timing_safe_equal: Perform a constant-time comparison of two byte slices.
ash_validate_nonce: Validate a nonce string (format and length only, not uniqueness).
ash_validate_timestamp: Validate a timestamp string.
ash_validate_timestamp_format: Validate timestamp format only (not freshness).
ash_verify_proof: Verify proof (server-side).
ash_verify_proof_scoped: Verify v2.2 proof with scoped fields.
ash_verify_proof_unified: Verify unified v2.3 proof (server-side).
ash_verify_proof_with_freshness: Verify proof with timestamp freshness check (server-side).

Crate ash_core

Crate ash_core Copy item path

§ASH Core

§Safety

§What ASH Does

§What ASH Does NOT Do

§Quick Start

§Features

§Module Overview

§Security Considerations

§Protocol Version

Re-exports§

Modules§

Structs§

Enums§

Constants§

Functions§

Crate ash_core