# Security Model

## Design Principles

1. **Fail-closed by default** — absent configuration causes rejection, not acceptance.
2. **Explicit trust transitions** — trust is not implicit; it must be established at each cryptographic stage.
3. **No silent bypasses** — signature verification results are always propagated; `let _ = verify(...)` is forbidden.
4. **Algorithm agility with compliance first** — AS4 WS-Security runtime verification is strict-only (no legacy inbound fallback paths); any non-default compatibility behavior must be explicit and scoped through interop policy outside WS-Security cryptographic verification.

---

## Certificate and Trust Configuration

All certificate and trust material is carried in `CertHandle`, which is set on `SessionContext` via `.with_cert_handle(handle)`.

```rust
pub struct CertHandle {
    pub signing_key_pem: String,          // PEM private key for signing (AS2 S/MIME or AS4 WS-Security)
    pub signing_cert_pem: String,         // PEM certificate corresponding to signing_key_pem
    pub encryption_cert_pem: String,      // PEM certificate for encrypting to this party
    pub trust_anchor_pems: Vec<String>,   // PEM CA certificates for PKIX chain validation
    pub fingerprint_sha256: String,       // Expected SHA-256 fingerprint of partner's signing cert (empty = pinning disabled)
    pub ocsp_config: OcspConfig,          // OCSP mode and responder override
}
```

### PKIX chain validation

When `RevocationPolicy::require_chain_validation = true` (the default when at least one trust anchor is provided), all signer certificates are validated against `trust_anchor_pems` using PKIX chain building. An empty `trust_anchor_pems` with `require_chain_validation = true` **fails closed** — no certificate will pass validation.

To explicitly allow any certificate (testing only):
```rust
RevocationPolicy {
    require_chain_validation: false,
    trust_anchor_pems: vec![],
    ..Default::default()
}
```

### Certificate fingerprint pinning

When `fingerprint_sha256` is non-empty, the signer certificate's SHA-256 fingerprint is compared against this value after PKIX validation. A mismatch fails the receive.

For AS4 push receive, `As4PushPolicy` now controls trust mode explicitly:
1. Pinned sender mode: requires `fingerprint_sha256` to be configured for signed inbound message verification.

```rust
CertHandle {
    fingerprint_sha256: "AA:BB:CC:...".to_string(),  // enforce pinning
    ..
}
```

---

## OCSP (Online Certificate Status Protocol)

OCSP is configured per session via `OcspConfig` in `CertHandle`:

```rust
pub struct OcspConfig {
    pub mode: OcspMode,
    pub responder_override: Option<String>,  // Optional URL override
}

pub enum OcspMode {
    Disabled,
    Required,
    BestEffort,  // OCSP failure does not fail the receive
}
```

OCSP responses are fetched via `reqwest` (`async-ocsp` feature, enabled by default). The async path (`fetch_ocsp_responses_with_cache_async*`) is the preferred entry point and runs entirely on the caller's Tokio runtime with no additional thread overhead. The sync compatibility wrapper (`fetch_ocsp_responses_with_cache_provider_scoped`) bridges into async by using `tokio::task::block_in_place` + `block_on` on the current runtime handle — no dedicated OS thread is spawned. Responses are cached (`ProcessLocalOcspResponseCache`, 5-minute TTL, max 512 entries with lazy eviction) to minimise live round-trips — in steady state, most certificate checks are served from cache.

### Response freshness

OCSP responses are validated for freshness:
- `thisUpdate` must be within 300 seconds of the current time (clock skew tolerance).
- `nextUpdate` must not be more than 86400 seconds (24 hours) in the past.

Stale or expired OCSP responses are rejected.

---

## Cryptographic Algorithms

### AS2 (S/MIME)

| Operation | Algorithm |
|---|---|
| Signing | S/MIME CMS — RSA + SHA-256 |
| Encryption | S/MIME CMS — AES-256 CBC (or AES-128-GCM for newer partners) |
| MIC computation | SHA-256 over `Content-Type: …\r\n\r\n<payload>` (RFC 4130 §7.3.1) |

### AS4 (WS-Security / XML Encryption)

| Operation | Algorithm | URI |
|---|---|---|
| Payload encryption (outbound) | AES-256-GCM (XMLenc11) | `http://www.w3.org/2009/xmlenc11#aes256-gcm` |
| Payload encryption (inbound) | AES-128-GCM or AES-256-GCM (XMLenc11) | `http://www.w3.org/2009/xmlenc11#aes128-gcm`, `http://www.w3.org/2009/xmlenc11#aes256-gcm` |
| Key transport | RSA-OAEP (XMLenc11) | `http://www.w3.org/2009/xmlenc11#rsa-oaep` |
| Key transport MGF | MGF1-SHA256 | `http://www.w3.org/2009/xmlenc11#mgf1sha256` |
| Key transport digest | SHA-256 | `http://www.w3.org/2001/04/xmlenc#sha256` |
| XML Signature | RSA-SHA256 | `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` |
| Canonicalization | Exclusive C14N | `http://www.w3.org/2001/10/xml-exc-c14n#` |

ASX uses **AES-256-GCM** (authenticated encryption) for outbound AS4 encryption and accepts only XMLenc11 AES-GCM inbound. Legacy AES-CBC and XMLenc 1.0 OAEP variants are rejected fail-closed to reduce downgrade and padding-oracle risk.

---

## WS-Security XML Signatures

### Canonicalization (C14N)

WS-Security signature computation uses XML Exclusive C14N (W3C `exc-c14n`). The implementation:
- Correctly handles namespace propagation for visibly-utilized namespaces.
- Forwards processing instruction nodes (`<?target data?>`).
- Implements `InclusiveNamespaces PrefixList` per W3C Exc-C14N §2.1 — ancestor namespace bindings for listed prefixes are rendered even when not directly utilized at the element.
- Strips comments in default mode; preserves them when `include_comments = true`.
- Sorts attributes in lexicographic order (namespace URI, local name) as required by C14N.

Validated against W3C C14N test vectors (namespace propagation, attribute ordering, text/attribute escaping, PI forwarding, comment stripping, comment preservation).

### Signature verification

Signature verification uses:
1. Digest verification over C14N-serialized referenced elements.
2. RSA signature verification using `secure_eq` (constant-time comparison) for digest values.
3. PKIX chain validation of the signing certificate.
4. OCSP status check (if configured).

Verification is fail-closed: any error at any step propagates immediately via `?`. The caller cannot ignore a failed verification.

### `wsu:Timestamp` validation

Inbound WS-Security timestamps are validated:
- `wsu:Created` must be within 5 minutes of the current time.
- `wsu:Expires` (if present) must not be in the past.

Outbound timestamps include `wsu:Created` (now) and `wsu:Expires` (now + 5 minutes).

---

## `InsecureBypassTrustVerifier`

```rust
use asx_rs::lifecycle::InsecureBypassTrustVerifier;
```

**For testing only.** This verifier passes any payload as fully trusted and decryptable without performing any cryptographic checks. Its name is intentionally explicit.

Never use `InsecureBypassTrustVerifier` in production. It bypasses:
- Signature verification
- PKIX chain validation
- OCSP status checking
- Fingerprint pinning

---

## Payload Size Limits

All inbound reads are bounded. The default limit is **256 MiB** (`DEFAULT_MAX_BODY_BYTES`). This applies to:
- `asx_rs::as2::receive_with_mdn_with_reliability`
- `asx_rs::as4::receive_push_with_dedup_sync`
- `transport::server` layer (axum handlers)

Override per-session:
```rust
As2PushPolicy::builder().max_body_bytes(64 * 1024 * 1024)  // 64 MiB
```

---

## Temp File Security

Streaming receive operations that require on-disk spooling (e.g., for signature verification rewinding) use `tempfile::NamedTempFile` for atomic, exclusive temp file creation. This prevents symlink attacks on world-writable `/tmp`.

---

## Operator Hardening Expectations (Core Dumps and Host Memory)

ASX zeroizes owned private-key PEM buffers on drop where possible, and recent send-path refactors minimize transient key-buffer duplication. However, ASX is only a library and cannot enforce host OS process-dump policy, swap policy, or debugger attach policy.

Production operators are expected to harden runtime environments accordingly:

1. Disable process core dumps for ASX-hosting services (for example `ulimit -c 0`, systemd `LimitCORE=0`, container runtime equivalents).
2. Restrict dumpability and ptrace/debug attachment to trusted operators only.
3. Ensure swap/pagefile policy is encrypted or disabled for regulated deployments handling private keys.
4. Keep crash-reporting pipelines from uploading raw process memory unless a formally approved secret-scrubbing policy is in place.

These controls are mandatory complements to in-process zeroization when handling cryptographic private key material in production.

---

## Known Limitations

| Limitation | Mitigation |
|---|---|
| Custom XML Exclusive C14N implementation | Validated against W3C test vectors and interop compatibility matrix; not yet replaced by a vetted library |
| In-memory dedup provides no replay protection across restarts | Use `TtlDedupStorage` with a distributed backend for production; document required 48h window per RFC 4130 §5.2.1 |
| No TLS mutual authentication (mTLS) at the library level | Configure mTLS at the TLS terminator / reverse proxy layer |
| OCSP `thisUpdate`/`nextUpdate` clock skew tolerance is fixed at ±300s / 86400s | Adjust via `OcspConfig` if partner OCSP responders have larger clock drift |
| OCSP sync wrapper uses `block_in_place`/`block_on` (not a new OS thread) — must be called from a multi-thread Tokio runtime | Use the async `fetch_ocsp_responses_with_cache_async` entry point directly from async call sites; at very high message rates with many distinct certificates, consider a shared persistent OCSP cache backend |

---

## Crypto Backend Roadmap

### Current State: Mixed OpenSSL + Pure-Rust

`asx-rs` currently uses two separate crypto ecosystems:

| Subsystem | Current backend | Role |
|---|---|---|
| AS2 S/MIME signing / encryption | `openssl` (C FFI) | CMS `SignedData` / `EnvelopedData` |
| AS4 WS-Security XML signing | `openssl` (C FFI) | RSA-SHA256 `ds:Signature`, RSA-OAEP key wrap |
| AS4 payload symmetric encryption | `aes-gcm` (pure Rust) | AES-128/256-GCM `xenc:EncryptedData` |
| X.509 certificate parsing | `openssl` (C FFI) | Trust-anchor validation, chain building, OCSP |

This mixed model has several implications:

- **Build system**: consumers must have a working OpenSSL installation (or
  accept the `openssl-sys` vendored build). Cross-compilation (e.g., to
  `x86_64-unknown-linux-musl` static binaries) requires extra care.
- **FIPS compliance**: OpenSSL can be compiled in FIPS mode; the `aes-gcm`
  crate is *not* FIPS 140-2 validated. Regulated deployments (US federal,
  healthcare) requiring FIPS-validated crypto across **all** algorithms must
  either replace `aes-gcm` with the OpenSSL AES-GCM primitives or wait for
  the pure-Rust migration path below.
- **Vulnerability management**: OpenSSL and `aes-gcm` have separate CVE
  timelines and patch cadences. Both must be tracked independently.

### Migration Path: Full Pure-Rust Crypto

The long-term goal is to eliminate the OpenSSL C-FFI dependency and converge
on a single pure-Rust crypto stack. The planned migration path is:

1. **Phase 1 (in progress)**: Symmetric crypto is already pure Rust (`aes-gcm`).
2. **Phase 2**: Replace OpenSSL X.509 parsing with `x509-cert` + `rustls-pki-types`.
3. **Phase 3**: Replace OpenSSL RSA operations (CMS key wrap, WS-Security signing)
   with `rsa` (pure Rust) or `aws-lc-rs` (FIPS-validated pure-Rust interface).
4. **Phase 4**: Remove the `openssl` crate dependency entirely. Provide an
   optional `openssl-fips` feature gate for regulated environments that require
   FIPS 140-2 validated modules.

> **Note**: Phases 2–4 are pre-1.0 roadmap items and will be treated as
> breaking-dependency changes. Subscribe to the GitHub releases feed or
> `CHANGELOG.md` for status.

### FIPS Deployment Today

If you need FIPS-validated crypto today, use the following configuration:

1. Compile OpenSSL in FIPS mode (OpenSSL 3.x with `OPENSSL_FIPS=1`).
2. Do **not** enable AS4 XML encryption (set `As4SendPolicy { encrypt: false, .. }` for
   outbound; for inbound, `As4PushPolicy::default()` already allows unencrypted payloads
   when none arrive encrypted), since the `aes-gcm` symmetric layer is not FIPS
   140-2 validated.
3. Contact your compliance officer before enabling AS4 payload encryption in
   a regulated deployment until Phase 3 is complete.


