ash-core
Developed by 3maem Co. | شركة عمائم
Core Rust implementation of the ASH (Application Security Hash) protocol for request integrity verification and anti-replay protection.
Overview
ASH Core provides the foundational cryptographic primitives and canonicalization functions used across all ASH SDK implementations. It ensures byte-identical output across all platforms through deterministic processing.
Features
- RFC 8785 Compliant: JSON Canonicalization Scheme (JCS) for deterministic serialization
- Cryptographic Proofs: HMAC-SHA256 based proof generation and verification
- Timing Attack Resistance: Constant-time comparison for all security-sensitive operations
- Anti-Replay Protection: Single-use context enforcement with TTL
- Field Scoping: Protect specific fields while allowing others to change
- Request Chaining: Link sequential requests cryptographically
- WASM Compatible: Works in browsers via ash-wasm bindings
Installation
Or add to your Cargo.toml:
[]
= "2.3.5"
Examples
For usage examples, see the examples/ directory and the API Documentation.
API Reference
Core Proof Functions
| Function | Description |
|---|---|
ash_derive_client_secret(nonce, ctx_id, binding) |
Derive HMAC key from nonce |
ash_build_proof(secret, timestamp, binding, body_hash) |
Build HMAC-SHA256 proof |
ash_verify_proof(nonce, ctx_id, binding, timestamp, body_hash, proof) |
Verify proof |
High-Level API (v2.4.0)
| Function | Description |
|---|---|
build_request_proof(input) |
Client-side: build proof in one call |
verify_incoming_request(input) |
Server-side: verify request in one call |
Scoped Proof Functions
| Function | Description |
|---|---|
ash_build_proof_scoped(...) |
Build proof protecting specific fields |
ash_verify_proof_scoped(...) |
Verify scoped proof |
ash_extract_scoped_fields(payload, scope) |
Extract fields for scoping |
ash_hash_scoped_body(payload, scope) |
Hash only scoped fields |
Unified Proof Functions (Scoping + Chaining)
| Function | Description |
|---|---|
ash_build_proof_unified(...) |
Build proof with scoping + chaining |
ash_verify_proof_unified(...) |
Verify unified proof |
ash_hash_proof(proof) |
Compute chain hash |
Canonicalization Functions
| Function | Description |
|---|---|
ash_canonicalize_json(input) |
Canonicalize JSON (RFC 8785) |
ash_canonicalize_query(query) |
Canonicalize URL query string |
ash_canonicalize_urlencoded(input) |
Canonicalize form data |
ash_normalize_binding(method, path, query) |
Normalize endpoint binding |
Enriched API (v2.4.0)
| Function | Description |
|---|---|
ash_canonicalize_query_enriched(query) |
Canonical query with metadata |
ash_hash_body_enriched(body) |
Body hash with metadata |
ash_normalize_binding_enriched(method, path, query) |
Binding with parsed components |
Utility Functions
| Function | Description |
|---|---|
ash_generate_nonce(bytes) |
Generate cryptographic nonce |
ash_generate_context_id() |
Generate unique context ID |
ash_hash_body(body) |
SHA-256 hash of body |
ash_hash_scope(scope) |
Hash scope field list |
ash_timing_safe_equal(a, b) |
Constant-time comparison |
ash_validate_timestamp(ts, now, max_age, skew) |
Validate timestamp |
ash_validate_nonce(nonce) |
Validate nonce format |
ash_normalize_binding_value(type, value) |
Generic binding normalizer |
Testkit (v2.4.0)
| Function | Description |
|---|---|
load_vectors(data) |
Load conformance vectors |
run_vectors(vectors, adapter) |
Run vectors against any adapter |
AshAdapter trait |
12-method trait for SDK testing |
Types
| Type | Description |
|---|---|
AshMode |
Security mode: Minimal, Balanced, Strict |
AshError |
Error type with code, message, reason, retryable |
AshErrorCode |
Error codes (e.g., CtxNotFound, ProofInvalid) |
UnifiedProofResult |
Result from unified proof functions |
BindingType |
Binding types: Route, Ip, Device, Session, User, Tenant, Custom |
Error Codes
| Code | HTTP | Retryable | Description |
|---|---|---|---|
CtxNotFound |
450 | No | Context not found |
CtxExpired |
451 | No | Context expired |
CtxAlreadyUsed |
452 | No | Replay detected |
ProofInvalid |
460 | No | Proof verification failed |
BindingMismatch |
461 | No | Endpoint binding mismatch |
ScopeMismatch |
473 | No | Scope hash mismatch |
ChainBroken |
474 | No | Chain broken |
ScopedFieldMissing |
475 | No | Required scoped field missing |
TimestampInvalid |
482 | Yes | Clock skew / format |
ProofMissing |
483 | No | Missing header |
CanonicalizationError |
484 | No | Malformed payload |
ValidationError |
485 | No | Input validation |
ModeViolation |
486 | No | Mode mismatch |
UnsupportedContentType |
415 | No | Wrong content type |
InternalError |
500 | Yes | Transient server issue |
Cryptographic Details
| Component | Algorithm |
|---|---|
| Proof Generation | HMAC-SHA256 |
| Body Hashing | SHA-256 |
| Nonce Generation | CSPRNG (getrandom) |
| Comparison | Constant-time (subtle crate) |
| Key Derivation | HMAC-based |
Thread Safety
All functions are thread-safe and can be called concurrently.
Security Notes
ASH verifies what is being submitted, not who is submitting it. It should be used alongside authentication systems (JWT, OAuth, etc.).
Documentation
- SPECIFICATION.md - Complete protocol specification for SDK implementers
- CHANGELOG.md - Version history and migration guides
- API Documentation - Full Rust API docs
Related Crates
ash-wasm- WebAssembly bindings
License
Apache License 2.0
See LICENSE for full terms.
Links
© 3maem Co. | شركة عمائم