# Crypto Service Refactor — Implementation Plan

**Date:** February 14, 2026  
**Status:** Approved  
**Reference:** [crypto-service-design-review.md](crypto-service-design-review.md)

---

## Overview

This plan implements the proposed architecture from the design review:
- Algorithm marker types with compile-time dispatch
- `OneShot<A>` trait for backend abstraction
- Generic `CryptoServer<B>` that works with any backend
- Streaming sessions via `Streaming<A>` trait

---

## Design Decision: Why Not Reuse `RustCryptoController`?

The existing `platform/impls/rustcrypto/src/controller.rs` (640 lines) implements
the `openprot-hal-blocking` traits. We considered reusing it but chose **not to**
for long-term maintainability:

### Current Architecture (God Trait)

```rust
// hal/blocking/src/digest.rs
pub trait DigestInit<A> { 
    type Context: DigestOp; 
    fn init(self, algo: A) -> Result<Self::Context, Self::Error>;
}

// platform/impls/rustcrypto
impl DigestInit<Sha2_256> for RustCryptoController { ... }
impl DigestInit<Sha2_384> for RustCryptoController { ... }
impl DigestInit<Sha2_512> for RustCryptoController { ... }
impl DigestOp for DigestContext256 { ... }
impl DigestOp for DigestContext384 { ... }
impl DigestOp for DigestContext512 { ... }
// 6 impls just for digest, 6 more for MAC = 12+ total
```

**Problem:** Adding SHA3-384 requires:
1. Modify `DigestInit` trait (or add new marker type)
2. Add `DigestContext3_384` in RustCryptoController
3. Add impl for HACE backend
4. Add impl for any test mock

### Proposed Architecture (Composable Traits)

```rust
// crypto-traits/src/lib.rs
pub trait OneShot<A: Algorithm> {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError>;
}

// backend-rustcrypto/src/lib.rs
impl OneShot<Sha256> for RustCryptoBackend { ... }
impl OneShot<Sha384> for RustCryptoBackend { ... }
impl OneShot<Sha3_384> for RustCryptoBackend { ... }  // ← Adding algorithm = adding impl

// backend-hace/src/lib.rs (HACE only supports SHA-2)
impl OneShot<Sha256> for HaceBackend { ... }
impl OneShot<Sha384> for HaceBackend { ... }
// No Sha3_384 impl needed if HACE doesn't support it
```

**Benefit:** Adding SHA3-384 requires:
1. Add `pub struct Sha3_384; impl Algorithm for Sha3_384 { ... }` to traits
2. Add `impl OneShot<Sha3_384> for RustCryptoBackend { ... }` to backend
3. Done — no other files touched

### Impact on Algorithm Roadmap

The SPDM spec requires 10-15 additional algorithms. Each algorithm addition:

| Approach | Files Changed | Risk |
|----------|--------------|------|
| Current God trait | 3-4 per algorithm | High (touches shared traits) |
| Composable traits | 1-2 per algorithm | Low (additive only) |

**Decision:** Take the upfront refactor cost now for clean extensibility later.
The existing `RustCryptoController` code will be referenced for implementation
details but not directly reused.

---

## Architectural Insight: Trait Layering (HAL vs Service)

During implementation review, we identified an important layering distinction:

```
┌─────────────────────────────────────────────────────────────────┐
│                        Crypto Client                            │
│  (services/crypto/client)                                       │
└───────────────────────────┬─────────────────────────────────────┘
                            │ IPC (channel_call)
┌───────────────────────────▼─────────────────────────────────────┐
│                        Crypto Server                            │
│  (services/crypto/server)                                       │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │              Service Layer Traits                         │  │
│  │  OneShot<A>    — one-shot operations via &self            │  │
│  │  Streaming<A>  — session-based via session handle         │  │
│  │  (services/crypto/api/src/backend.rs)                     │  │
│  └───────────────────────────────────────────────────────────┘  │
│                            │                                    │
│                            │ impl                               │
│                            ▼                                    │
│  ┌──────────────────┐  ┌──────────────────┐                     │
│  │ RustCryptoBackend│  │   HaceBackend    │ ... (future)        │
│  │ (software)       │  │ (hardware accel) │                     │
│  └────────┬─────────┘  └────────┬─────────┘                     │
│           │                     │                               │
└───────────┼─────────────────────┼───────────────────────────────┘
            │                     │
            │ (may use)           │ (uses)
            ▼                     ▼
┌───────────────────────────────────────────────────────────────────┐
│                        HAL Layer Traits                           │
│  owned::DigestInit  — typestate pattern (moves self)              │
│  owned::DigestOp    — resource recovery via fn cancel(self)       │
│  (hal/blocking/src/digest.rs)                                     │
└───────────────────────────────────────────────────────────────────┘
            │
            │ impl
            ▼
┌───────────────────────────────────────────────────────────────────┐
│  RustCryptoController │ HaceController │ ... (platform impls)     │
│  (platform/impls/)    │                │                          │
└───────────────────────────────────────────────────────────────────┘
```

### Key Distinction

| Layer | Location | Purpose | Pattern |
|-------|----------|---------|----------|
| **Service** | `services/crypto/api/src/backend.rs` | Abstract IPC protocol | `&self` + session handle |
| **HAL** | `hal/blocking/src/digest.rs` | Abstract hardware controllers | Typestate (moves self) |

### Why Two Layers?

1. **Service Layer:** Designed for IPC semantics where state lives across multiple
   requests. The server owns a `StreamingSession` and clients reference it via session ID.

2. **HAL Layer:** Designed for baremetal use where resource recovery is critical.
   The typestate pattern ensures hardware controllers are properly released on
   success, failure, or cancellation.

### Relationship

- The HAL layer is used **by** platform implementations (both baremetal and server backends)
- The Service layer is used **by** the crypto server to abstract over different backends
- A `HaceBackend` would wrap a `HaceController` (HAL) to implement `OneShot<A>` (Service)

---

## Architectural Insight: Decoupling Resource Recovery

The HAL traits in `hal/blocking/src/digest.rs` bundle two concerns:

1. **Operation semantics:** init/update/finalize flow
2. **Resource recovery:** typestate pattern ensuring controller is returned

```rust
// Current HAL: both concerns bundled
pub mod owned {
    pub trait DigestOp {
        type Output;
        type Controller;
        type Error;
        
        fn update(self, data: &[u8]) -> Result<Self, Self::Error>;
        fn finalize(self) -> Result<(Self::Output, Self::Controller), Self::Error>;
        fn cancel(self) -> Self::Controller;  // ← Resource recovery
    }
}
```

### Why This Matters for Service Layer

For the crypto server:
- Sessions are **already managed** via session handles (IDs in a table)
- Resource recovery is handled at the **session table level**, not per-operation
- The typestate overhead provides no benefit for software backends

### Proposed Decoupling (Future Work)

Decouple into two orthogonal patterns:

```rust
// 1. Core operation trait (minimal, &mut self)
pub trait DigestOp {
    type Output;
    type Error;
    
    fn update(&mut self, data: &[u8]) -> Result<(), Self::Error>;
    fn finalize(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>;
}

// 2. Optional wrapper for resource recovery (typestate)
pub struct Owned<T, C> {
    op: T,
    controller: C,
}

impl<T: DigestOp, C> Owned<T, C> {
    pub fn update(self, data: &[u8]) -> Result<Self, (C, T::Error)> { ... }
    pub fn finalize(self) -> Result<(T::Output, C), (C, T::Error)> { ... }
    pub fn cancel(self) -> C { ... }  // ← Resource recovery here
}
```

### Benefits

| Concern | Baremetal | Server |
|---------|-----------|--------|
| Operation semantics | Uses core `DigestOp` | Uses core `DigestOp` |
| Resource recovery | Wraps in `Owned<T, C>` | Not needed (session table) |

This decoupling is **not required** for the current refactor—the Service layer
traits are already designed without typestate. However, this insight informs
future HAL evolution.

---

## Threading Model Note

Pigweed userspace processes are **single-threaded event loops**. The crypto server:
- Handles requests **sequentially** within a single thread
- Cannot spawn multiple threads to handle concurrent requests
- For true parallelism, would need multiple separate server processes

This simplifies session management—no need for thread-safe session tables or locks.
The single-threaded model also means `&mut self` on `Streaming<A>` methods is safe
without additional synchronization.

---

## Phase 1: Create `crypto-traits` Crate

**Goal:** Define algorithm marker types and backend traits in a minimal, dependency-free crate.

### 1.1 Create directory structure

```
services/crypto/traits/
├── Cargo.toml
├── BUILD.bazel
└── src/
    └── lib.rs
```

### 1.2 Create `Cargo.toml`

```toml
[package]
name = "crypto-traits"
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"

[dependencies]
# Intentionally minimal — no_std, no dependencies
```

### 1.3 Create `src/lib.rs`

Contents:

```rust
#![no_std]

//! Crypto traits for backend abstraction.
//!
//! This crate defines:
//! - Algorithm marker types (Sha256, HmacSha256, etc.)
//! - OneShot<A> trait for one-shot crypto operations
//! - Streaming<A> trait for session-based streaming
//! - CryptoInput enum for semantically typed inputs

// --- Algorithm trait ---
pub trait Algorithm {
    const OUTPUT_SIZE: usize;
    const OP_CODE: u8;
}

// --- Digest algorithms ---
pub struct Sha256;
impl Algorithm for Sha256 { const OUTPUT_SIZE: usize = 32; const OP_CODE: u8 = 0x01; }

pub struct Sha384;
impl Algorithm for Sha384 { const OUTPUT_SIZE: usize = 48; const OP_CODE: u8 = 0x02; }

pub struct Sha512;
impl Algorithm for Sha512 { const OUTPUT_SIZE: usize = 64; const OP_CODE: u8 = 0x03; }

// --- MAC algorithms ---
pub struct HmacSha256;
impl Algorithm for HmacSha256 { const OUTPUT_SIZE: usize = 32; const OP_CODE: u8 = 0x10; }

pub struct HmacSha384;
impl Algorithm for HmacSha384 { const OUTPUT_SIZE: usize = 48; const OP_CODE: u8 = 0x11; }

pub struct HmacSha512;
impl Algorithm for HmacSha512 { const OUTPUT_SIZE: usize = 64; const OP_CODE: u8 = 0x12; }

// --- AEAD algorithms ---
pub struct Aes256GcmEncrypt;
impl Algorithm for Aes256GcmEncrypt { const OUTPUT_SIZE: usize = 0; const OP_CODE: u8 = 0x20; }

pub struct Aes256GcmDecrypt;
impl Algorithm for Aes256GcmDecrypt { const OUTPUT_SIZE: usize = 0; const OP_CODE: u8 = 0x21; }

// --- Signature algorithms (gated) ---
#[cfg(feature = "ecdsa")]
pub struct EcdsaP256Sign;
#[cfg(feature = "ecdsa")]
impl Algorithm for EcdsaP256Sign { const OUTPUT_SIZE: usize = 64; const OP_CODE: u8 = 0x40; }

#[cfg(feature = "ecdsa")]
pub struct EcdsaP256Verify;
#[cfg(feature = "ecdsa")]
impl Algorithm for EcdsaP256Verify { const OUTPUT_SIZE: usize = 1; const OP_CODE: u8 = 0x41; }

#[cfg(feature = "ecdsa")]
pub struct EcdsaP384Sign;
#[cfg(feature = "ecdsa")]
impl Algorithm for EcdsaP384Sign { const OUTPUT_SIZE: usize = 96; const OP_CODE: u8 = 0x42; }

#[cfg(feature = "ecdsa")]
pub struct EcdsaP384Verify;
#[cfg(feature = "ecdsa")]
impl Algorithm for EcdsaP384Verify { const OUTPUT_SIZE: usize = 1; const OP_CODE: u8 = 0x43; }

// --- Structured input types ---
pub enum CryptoInput<'a> {
    Digest { data: &'a [u8] },
    Mac { key: &'a [u8], data: &'a [u8] },
    Aead { key: &'a [u8], nonce: &'a [u8], data: &'a [u8] },
    Sign { private_key: &'a [u8], message: &'a [u8] },
    Verify { public_key: &'a [u8], message: &'a [u8], signature: &'a [u8] },
}

// --- Error type ---
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CryptoError {
    InvalidOperation,
    InvalidKeyLength,
    InvalidNonceLength,
    InvalidDataLength,
    InvalidSignature,
    BufferTooSmall,
    AuthenticationFailed,
    HardwareFailure,
}

// --- OneShot trait ---
pub trait OneShot<A: Algorithm> {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError>;
}

// --- Streaming trait ---
pub trait Streaming<A: Algorithm> {
    type Session;
    
    fn begin(&mut self) -> Result<Self::Session, CryptoError>;
    fn update(&mut self, session: &mut Self::Session, data: &[u8]) -> Result<(), CryptoError>;
    fn finalize(&mut self, session: Self::Session, output: &mut [u8]) -> Result<usize, CryptoError>;
    fn cancel(&mut self, session: Self::Session);
}
```

### 1.4 Create `BUILD.bazel`

```python
load("@rules_rust//rust:defs.bzl", "rust_library")

rust_library(
    name = "crypto-traits",
    srcs = ["src/lib.rs"],
    crate_features = select({
        "//target:ecdsa": ["ecdsa"],
        "//conditions:default": [],
    }),
    visibility = ["//visibility:public"],
)
```

### 1.5 Verification

```bash
bazel build //services/crypto/traits:crypto-traits
```

---

## Phase 2: Create `backend-rustcrypto` Crate

**Goal:** Implement `OneShot<A>` for all algorithms using RustCrypto.

### 2.1 Create directory structure

```
services/crypto/backend-rustcrypto/
├── Cargo.toml
├── BUILD.bazel
└── src/
    └── lib.rs
```

### 2.2 Create `Cargo.toml`

```toml
[package]
name = "crypto-backend-rustcrypto"
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"

[features]
default = []
ecdsa = ["crypto-traits/ecdsa", "p256", "p384"]

[dependencies]
crypto-traits = { path = "../traits" }

# RustCrypto
sha2 = { version = "0.10", default-features = false }
hmac = { version = "0.12", default-features = false }
aes-gcm = { version = "0.10", default-features = false, features = ["aes"] }

# ECDSA (optional)
p256 = { version = "0.13", default-features = false, features = ["ecdsa"], optional = true }
p384 = { version = "0.13", default-features = false, features = ["ecdsa"], optional = true }
```

### 2.3 Create `src/lib.rs`

```rust
#![no_std]

use crypto_traits::{
    Algorithm, CryptoError, CryptoInput, OneShot,
    Sha256, Sha384, Sha512,
    HmacSha256, HmacSha384, HmacSha512,
    Aes256GcmEncrypt, Aes256GcmDecrypt,
};

#[cfg(feature = "ecdsa")]
use crypto_traits::{EcdsaP256Sign, EcdsaP256Verify, EcdsaP384Sign, EcdsaP384Verify};

use sha2::Digest as Sha2Digest;
use hmac::{Hmac, Mac};
use aes_gcm::{Aes256Gcm, KeyInit, Nonce as GcmNonce, aead::AeadInPlace};

/// RustCrypto-based backend. Stateless — can be freely copied.
#[derive(Clone, Copy, Default)]
pub struct RustCryptoBackend;

impl RustCryptoBackend {
    pub const fn new() -> Self {
        Self
    }
}

// --- Generic digest helper ---
fn do_digest<D: Sha2Digest>(data: &[u8], output: &mut [u8]) -> Result<usize, CryptoError> {
    let mut hasher = D::new();
    hasher.update(data);
    let result = hasher.finalize();
    let size = result.len();
    if output.len() < size {
        return Err(CryptoError::BufferTooSmall);
    }
    output[..size].copy_from_slice(&result);
    Ok(size)
}

impl OneShot<Sha256> for RustCryptoBackend {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
        let CryptoInput::Digest { data } = input else { return Err(CryptoError::InvalidOperation) };
        do_digest::<sha2::Sha256>(data, output)
    }
}

impl OneShot<Sha384> for RustCryptoBackend {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
        let CryptoInput::Digest { data } = input else { return Err(CryptoError::InvalidOperation) };
        do_digest::<sha2::Sha384>(data, output)
    }
}

impl OneShot<Sha512> for RustCryptoBackend {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
        let CryptoInput::Digest { data } = input else { return Err(CryptoError::InvalidOperation) };
        do_digest::<sha2::Sha512>(data, output)
    }
}

// --- Generic HMAC helper ---
fn do_hmac<D>(key: &[u8], data: &[u8], output: &mut [u8]) -> Result<usize, CryptoError>
where
    D: sha2::Digest + hmac::digest::core_api::BlockSizeUser + Clone,
    Hmac<D>: Mac,
{
    let mut mac = <Hmac<D> as Mac>::new_from_slice(key)
        .map_err(|_| CryptoError::InvalidKeyLength)?;
    mac.update(data);
    let result = mac.finalize().into_bytes();
    let size = result.len();
    if output.len() < size {
        return Err(CryptoError::BufferTooSmall);
    }
    output[..size].copy_from_slice(&result);
    Ok(size)
}

impl OneShot<HmacSha256> for RustCryptoBackend {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
        let CryptoInput::Mac { key, data } = input else { return Err(CryptoError::InvalidOperation) };
        do_hmac::<sha2::Sha256>(key, data, output)
    }
}

impl OneShot<HmacSha384> for RustCryptoBackend {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
        let CryptoInput::Mac { key, data } = input else { return Err(CryptoError::InvalidOperation) };
        do_hmac::<sha2::Sha384>(key, data, output)
    }
}

impl OneShot<HmacSha512> for RustCryptoBackend {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
        let CryptoInput::Mac { key, data } = input else { return Err(CryptoError::InvalidOperation) };
        do_hmac::<sha2::Sha512>(key, data, output)
    }
}

// --- AES-GCM ---
const AES_KEY_SIZE: usize = 32;
const GCM_NONCE_SIZE: usize = 12;
const GCM_TAG_SIZE: usize = 16;

impl OneShot<Aes256GcmEncrypt> for RustCryptoBackend {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
        let CryptoInput::Aead { key, nonce, data } = input else { 
            return Err(CryptoError::InvalidOperation) 
        };
        if key.len() != AES_KEY_SIZE {
            return Err(CryptoError::InvalidKeyLength);
        }
        if nonce.len() != GCM_NONCE_SIZE {
            return Err(CryptoError::InvalidNonceLength);
        }
        let output_len = data.len() + GCM_TAG_SIZE;
        if output.len() < output_len {
            return Err(CryptoError::BufferTooSmall);
        }
        
        let key_array: [u8; 32] = key.try_into().map_err(|_| CryptoError::InvalidKeyLength)?;
        let cipher = Aes256Gcm::new(&key_array.into());
        let gcm_nonce = GcmNonce::from_slice(nonce);
        
        output[..data.len()].copy_from_slice(data);
        let tag = cipher.encrypt_in_place_detached(gcm_nonce, &[], &mut output[..data.len()])
            .map_err(|_| CryptoError::HardwareFailure)?;
        output[data.len()..output_len].copy_from_slice(&tag);
        
        Ok(output_len)
    }
}

impl OneShot<Aes256GcmDecrypt> for RustCryptoBackend {
    fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
        let CryptoInput::Aead { key, nonce, data } = input else { 
            return Err(CryptoError::InvalidOperation) 
        };
        if key.len() != AES_KEY_SIZE {
            return Err(CryptoError::InvalidKeyLength);
        }
        if nonce.len() != GCM_NONCE_SIZE {
            return Err(CryptoError::InvalidNonceLength);
        }
        if data.len() < GCM_TAG_SIZE {
            return Err(CryptoError::InvalidDataLength);
        }
        
        let ciphertext_len = data.len() - GCM_TAG_SIZE;
        if output.len() < ciphertext_len {
            return Err(CryptoError::BufferTooSmall);
        }
        
        let key_array: [u8; 32] = key.try_into().map_err(|_| CryptoError::InvalidKeyLength)?;
        let cipher = Aes256Gcm::new(&key_array.into());
        let gcm_nonce = GcmNonce::from_slice(nonce);
        
        let ciphertext = &data[..ciphertext_len];
        let tag = &data[ciphertext_len..];
        
        output[..ciphertext_len].copy_from_slice(ciphertext);
        cipher.decrypt_in_place_detached(
            gcm_nonce,
            &[],
            &mut output[..ciphertext_len],
            tag.into(),
        ).map_err(|_| CryptoError::AuthenticationFailed)?;
        
        Ok(ciphertext_len)
    }
}

// --- ECDSA (feature-gated) ---
#[cfg(feature = "ecdsa")]
mod ecdsa_impl {
    use super::*;
    use p256::ecdsa::{SigningKey as P256SigningKey, VerifyingKey as P256VerifyingKey, Signature as P256Signature, signature::{Signer, Verifier}};
    use p384::ecdsa::{SigningKey as P384SigningKey, VerifyingKey as P384VerifyingKey, Signature as P384Signature};
    
    impl OneShot<EcdsaP256Sign> for RustCryptoBackend {
        fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
            let CryptoInput::Sign { private_key, message } = input else {
                return Err(CryptoError::InvalidOperation);
            };
            if private_key.len() != 32 {
                return Err(CryptoError::InvalidKeyLength);
            }
            if output.len() < 64 {
                return Err(CryptoError::BufferTooSmall);
            }
            
            let key = P256SigningKey::from_slice(private_key)
                .map_err(|_| CryptoError::InvalidKeyLength)?;
            let sig: P256Signature = key.sign(message);
            output[..64].copy_from_slice(&sig.to_bytes());
            Ok(64)
        }
    }
    
    impl OneShot<EcdsaP256Verify> for RustCryptoBackend {
        fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
            let CryptoInput::Verify { public_key, message, signature } = input else {
                return Err(CryptoError::InvalidOperation);
            };
            if signature.len() != 64 {
                return Err(CryptoError::InvalidSignature);
            }
            if output.is_empty() {
                return Err(CryptoError::BufferTooSmall);
            }
            
            let key = P256VerifyingKey::from_sec1_bytes(public_key)
                .map_err(|_| CryptoError::InvalidKeyLength)?;
            let sig = P256Signature::from_slice(signature)
                .map_err(|_| CryptoError::InvalidSignature)?;
            
            match key.verify(message, &sig) {
                Ok(()) => {
                    output[0] = 1; // verified
                    Ok(1)
                }
                Err(_) => {
                    output[0] = 0; // failed
                    Ok(1)
                }
            }
        }
    }
    
    impl OneShot<EcdsaP384Sign> for RustCryptoBackend {
        fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
            let CryptoInput::Sign { private_key, message } = input else {
                return Err(CryptoError::InvalidOperation);
            };
            if private_key.len() != 48 {
                return Err(CryptoError::InvalidKeyLength);
            }
            if output.len() < 96 {
                return Err(CryptoError::BufferTooSmall);
            }
            
            let key = P384SigningKey::from_slice(private_key)
                .map_err(|_| CryptoError::InvalidKeyLength)?;
            let sig: P384Signature = Signer::sign(&key, message);
            output[..96].copy_from_slice(&sig.to_bytes());
            Ok(96)
        }
    }
    
    impl OneShot<EcdsaP384Verify> for RustCryptoBackend {
        fn compute(&self, input: &CryptoInput, output: &mut [u8]) -> Result<usize, CryptoError> {
            let CryptoInput::Verify { public_key, message, signature } = input else {
                return Err(CryptoError::InvalidOperation);
            };
            if signature.len() != 96 {
                return Err(CryptoError::InvalidSignature);
            }
            if output.is_empty() {
                return Err(CryptoError::BufferTooSmall);
            }
            
            let key = P384VerifyingKey::from_sec1_bytes(public_key)
                .map_err(|_| CryptoError::InvalidKeyLength)?;
            let sig = P384Signature::from_slice(signature)
                .map_err(|_| CryptoError::InvalidSignature)?;
            
            match Verifier::verify(&key, message, &sig) {
                Ok(()) => {
                    output[0] = 1;
                    Ok(1)
                }
                Err(_) => {
                    output[0] = 0;
                    Ok(1)
                }
            }
        }
    }
}
```

### 2.4 Verification

```bash
bazel build //services/crypto/backend-rustcrypto:crypto-backend-rustcrypto
```

---

## Phase 3: Rewrite Server with `CryptoServer<B>`

**Goal:** Replace the 496-line server with a ~150-line generic implementation.

### 3.1 Modify `services/crypto/server/Cargo.toml`

Replace direct RustCrypto dependencies with trait crate:

```toml
[dependencies]
crypto-api = { path = "../api" }
crypto-traits = { path = "../traits" }
crypto-backend-rustcrypto = { path = "../backend-rustcrypto" }
zerocopy = { version = "0.8", features = ["derive"] }
# Remove: sha2, hmac, aes-gcm, p256, p384
```

### 3.2 Rewrite `services/crypto/server/src/main.rs`

New structure:

```rust
#![no_main]
#![no_std]

use crypto_api::{CryptoError as WireError, CryptoOp, CryptoRequestHeader, CryptoResponseHeader};
use crypto_traits::{
    Algorithm, CryptoError, CryptoInput, OneShot, Streaming,
    Sha256, Sha384, Sha512,
    HmacSha256, HmacSha384, HmacSha512,
    Aes256GcmEncrypt, Aes256GcmDecrypt,
};
#[cfg(feature = "ecdsa")]
use crypto_traits::{EcdsaP256Sign, EcdsaP256Verify, EcdsaP384Sign, EcdsaP384Verify};

use crypto_backend_rustcrypto::RustCryptoBackend;
use pw_status::Result;
use userspace::entry;
use userspace::syscall::{self, Signals};
use userspace::time::Instant;
use app_crypto_server::handle;

const MAX_REQUEST_SIZE: usize = 1024;
const MAX_RESPONSE_SIZE: usize = 1024;

// Type alias for backend — change this one line to swap backends
type Backend = RustCryptoBackend;

/// Generic crypto server.
struct CryptoServer<B> {
    backend: B,
    // Streaming session state (single session at a time)
    session: StreamingSession,
}

enum StreamingSession {
    None,
    Sha256(Sha256State),
    Sha384(Sha384State),
    Sha512(Sha512State),
}

// Session state types (backend-specific, but hidden behind Streaming<A> trait)
struct Sha256State { /* backend session handle */ }
struct Sha384State { /* backend session handle */ }
struct Sha512State { /* backend session handle */ }

impl<B> CryptoServer<B>
where
    B: OneShot<Sha256> + OneShot<Sha384> + OneShot<Sha512>
     + OneShot<HmacSha256> + OneShot<HmacSha384> + OneShot<HmacSha512>
     + OneShot<Aes256GcmEncrypt> + OneShot<Aes256GcmDecrypt>
     #[cfg(feature = "ecdsa")]
     + OneShot<EcdsaP256Sign> + OneShot<EcdsaP256Verify>
     + OneShot<EcdsaP384Sign> + OneShot<EcdsaP384Verify>
{
    fn new(backend: B) -> Self {
        Self {
            backend,
            session: StreamingSession::None,
        }
    }

    fn dispatch(&self, request: &[u8], response: &mut [u8]) -> usize {
        // Parse header
        if request.len() < CryptoRequestHeader::SIZE {
            return encode_error(response, WireError::InvalidDataLength);
        }
        
        let header_bytes = &request[..CryptoRequestHeader::SIZE];
        let Some(header) = zerocopy::Ref::<_, CryptoRequestHeader>::from_bytes(header_bytes).ok() else {
            return encode_error(response, WireError::InvalidDataLength);
        };
        let header: &CryptoRequestHeader = &*header;
        
        let op = match header.operation() {
            Ok(op) => op,
            Err(e) => return encode_error(response, e),
        };
        
        // Extract fields
        let payload = &request[CryptoRequestHeader::SIZE..];
        let key_len = header.key_length();
        let nonce_len = header.nonce_length();
        let data_len = header.data_length();
        
        if payload.len() < key_len + nonce_len + data_len {
            return encode_error(response, WireError::InvalidDataLength);
        }
        
        let key = &payload[..key_len];
        let nonce = &payload[key_len..key_len + nonce_len];
        let data = &payload[key_len + nonce_len..key_len + nonce_len + data_len];
        
        // Build semantic input
        let input = Self::build_input(op, key, nonce, data);
        
        // Dispatch by op code
        match op {
            CryptoOp::Sha256Hash => self.run::<Sha256>(&input, response),
            CryptoOp::Sha384Hash => self.run::<Sha384>(&input, response),
            CryptoOp::Sha512Hash => self.run::<Sha512>(&input, response),
            CryptoOp::HmacSha256 => self.run::<HmacSha256>(&input, response),
            CryptoOp::HmacSha384 => self.run::<HmacSha384>(&input, response),
            CryptoOp::HmacSha512 => self.run::<HmacSha512>(&input, response),
            CryptoOp::Aes256GcmEncrypt => self.run::<Aes256GcmEncrypt>(&input, response),
            CryptoOp::Aes256GcmDecrypt => self.run::<Aes256GcmDecrypt>(&input, response),
            #[cfg(feature = "ecdsa")]
            CryptoOp::EcdsaP256Sign => self.run::<EcdsaP256Sign>(&input, response),
            #[cfg(feature = "ecdsa")]
            CryptoOp::EcdsaP256Verify => self.run::<EcdsaP256Verify>(&input, response),
            #[cfg(feature = "ecdsa")]
            CryptoOp::EcdsaP384Sign => self.run::<EcdsaP384Sign>(&input, response),
            #[cfg(feature = "ecdsa")]
            CryptoOp::EcdsaP384Verify => self.run::<EcdsaP384Verify>(&input, response),
            // Streaming ops (Phase 4)
            CryptoOp::Sha256Begin | CryptoOp::Sha256Update | CryptoOp::Sha256Finish |
            CryptoOp::Sha384Begin | CryptoOp::Sha384Update | CryptoOp::Sha384Finish |
            CryptoOp::Sha512Begin | CryptoOp::Sha512Update | CryptoOp::Sha512Finish => {
                encode_error(response, WireError::InvalidOperation) // TODO Phase 4
            }
            #[cfg(not(feature = "ecdsa"))]
            CryptoOp::EcdsaP256Sign | CryptoOp::EcdsaP256Verify |
            CryptoOp::EcdsaP384Sign | CryptoOp::EcdsaP384Verify => {
                encode_error(response, WireError::InvalidOperation)
            }
        }
    }

    fn build_input<'a>(op: CryptoOp, key: &'a [u8], nonce: &'a [u8], data: &'a [u8]) -> CryptoInput<'a> {
        match op {
            CryptoOp::Sha256Hash | CryptoOp::Sha384Hash | CryptoOp::Sha512Hash => 
                CryptoInput::Digest { data },
            CryptoOp::HmacSha256 | CryptoOp::HmacSha384 | CryptoOp::HmacSha512 => 
                CryptoInput::Mac { key, data },
            CryptoOp::Aes256GcmEncrypt | CryptoOp::Aes256GcmDecrypt => 
                CryptoInput::Aead { key, nonce, data },
            CryptoOp::EcdsaP256Sign | CryptoOp::EcdsaP384Sign => 
                CryptoInput::Sign { private_key: key, message: data },
            CryptoOp::EcdsaP256Verify | CryptoOp::EcdsaP384Verify => 
                CryptoInput::Verify { public_key: key, message: data, signature: nonce },
            _ => CryptoInput::Digest { data: &[] }, // streaming handled separately
        }
    }

    fn run<A: Algorithm>(&self, input: &CryptoInput, response: &mut [u8]) -> usize
    where
        B: OneShot<A>,
    {
        let result_start = CryptoResponseHeader::SIZE;
        match self.backend.compute(input, &mut response[result_start..]) {
            Ok(len) => encode_success(response, len),
            Err(e) => encode_error(response, map_error(e)),
        }
    }
}

fn encode_error(response: &mut [u8], err: WireError) -> usize {
    let header = CryptoResponseHeader::error(err);
    let header_bytes = zerocopy::IntoBytes::as_bytes(&header);
    response[..CryptoResponseHeader::SIZE].copy_from_slice(header_bytes);
    CryptoResponseHeader::SIZE
}

fn encode_success(response: &mut [u8], result_len: usize) -> usize {
    let header = CryptoResponseHeader::success(result_len as u16);
    let header_bytes = zerocopy::IntoBytes::as_bytes(&header);
    response[..CryptoResponseHeader::SIZE].copy_from_slice(header_bytes);
    CryptoResponseHeader::SIZE + result_len
}

fn map_error(e: CryptoError) -> WireError {
    match e {
        CryptoError::InvalidOperation => WireError::InvalidOperation,
        CryptoError::InvalidKeyLength => WireError::InvalidKeyLength,
        CryptoError::InvalidNonceLength => WireError::InvalidNonceLength,
        CryptoError::InvalidDataLength => WireError::InvalidDataLength,
        CryptoError::InvalidSignature => WireError::InvalidSignature,
        CryptoError::BufferTooSmall => WireError::BufferTooSmall,
        CryptoError::AuthenticationFailed => WireError::AuthenticationFailed,
        CryptoError::HardwareFailure => WireError::HardwareFailure,
    }
}

#[entry]
fn main() -> ! {
    match crypto_server_loop() {
        Ok(()) => unreachable!(),
        Err(e) => {
            pw_log::error!("Crypto server error: {:?}", e);
            loop { cortex_m::asm::wfi(); }
        }
    }
}

fn crypto_server_loop() -> Result<()> {
    pw_log::info!("Crypto server starting");
    
    let server = CryptoServer::new(RustCryptoBackend::new());
    let mut request_buf = [0u8; MAX_REQUEST_SIZE];
    let mut response_buf = [0u8; MAX_RESPONSE_SIZE];

    loop {
        syscall::object_wait(handle::CRYPTO, Signals::READABLE, Instant::MAX)?;
        let len = syscall::channel_read(handle::CRYPTO, 0, &mut request_buf)?;
        let response_len = server.dispatch(&request_buf[..len], &mut response_buf);
        syscall::channel_respond(handle::CRYPTO, &response_buf[..response_len])?;
    }
}
```

### 3.3 Verification

```bash
bazel test --config=virt_ast1060_evb //target/ast1060/crypto:crypto_test --test_output=all
```

All existing tests must pass unchanged.

---

## Phase 4: Add Streaming Support via `Streaming<A>` Trait

**Goal:** Implement streaming hash using the trait-based design.

### 4.1 Add to `crypto-traits/src/lib.rs`

Already defined in Phase 1. Add session state types.

### 4.2 Add to `backend-rustcrypto/src/lib.rs`

```rust
use sha2::{Sha256 as Sha2_256, Sha384 as Sha2_384, Sha512 as Sha2_512};

pub struct Sha256Session(Sha2_256);
pub struct Sha384Session(Sha2_384);
pub struct Sha512Session(Sha2_512);

impl Streaming<Sha256> for RustCryptoBackend {
    type Session = Sha256Session;
    
    fn begin(&mut self) -> Result<Self::Session, CryptoError> {
        Ok(Sha256Session(Sha2_256::new()))
    }
    
    fn update(&mut self, session: &mut Self::Session, data: &[u8]) -> Result<(), CryptoError> {
        session.0.update(data);
        Ok(())
    }
    
    fn finalize(&mut self, session: Self::Session, output: &mut [u8]) -> Result<usize, CryptoError> {
        if output.len() < 32 {
            return Err(CryptoError::BufferTooSmall);
        }
        let result = session.0.finalize();
        output[..32].copy_from_slice(&result);
        Ok(32)
    }
    
    fn cancel(&mut self, _session: Self::Session) {
        // Session dropped, nothing to clean up for software impl
    }
}

// Similar for Sha384, Sha512
```

### 4.3 Update server dispatch

Add streaming op handling in `CryptoServer::dispatch()`.

### 4.4 Verification

```bash
bazel test --config=virt_ast1060_evb //target/ast1060/crypto:crypto_test --test_output=all
```

Streaming test (`test_sha256_streaming`) must pass.

---

## Phase 5: HACE Backend (Future)

**Goal:** Add hardware-accelerated backend for AST1060.

### 5.1 Create `backend-hace` crate

```
services/crypto/backend-hace/
├── Cargo.toml
├── BUILD.bazel
└── src/
    └── lib.rs
```

### 5.2 Implement `OneShot<A>` and `Streaming<A>`

Wrap the `HaceController` from `aspeed-rust` to implement the traits.

### 5.3 Feature-gate in server

```rust
#[cfg(feature = "hace")]
type Backend = HaceBackend;

#[cfg(not(feature = "hace"))]
type Backend = RustCryptoBackend;
```

---

## Task Summary

| Phase | Task | New Files | Modified | LOC | Effort |
|-------|------|-----------|----------|-----|--------|
| 1 | Create `crypto-traits` crate | 3 | 0 | ~150 | 0.5 day |
| 2 | Create `backend-rustcrypto` crate | 3 | 0 | ~300 | 1 day |
| 3 | Rewrite server with `CryptoServer<B>` | 0 | 2 | ~150 (was 496) | 1 day |
| 4 | Add streaming via `Streaming<A>` | 0 | 3 | ~100 | 0.5 day |
| 5 | HACE backend (future) | 3 | 1 | ~300 | 3 days |
| **Total** | | **9** | **6** | **~1000** | **~6 days** |

---

## What Happens to Existing Code

| Component | Action |
|-----------|--------|
| `hal/blocking/src/digest.rs` | **Keep** — still used by non-crypto-server code |
| `hal/blocking/src/mac.rs` | **Keep** — still used by non-crypto-server code |
| `platform/impls/rustcrypto/src/controller.rs` | **Reference only** — mine for implementation patterns |
| `services/crypto/server/src/main.rs` | **Rewrite** — becomes generic `CryptoServer<B>` |
| `services/crypto/api/` | **Keep** — wire protocol unchanged |
| `services/crypto/client/` | **Keep** — client API unchanged |
| `services/crypto/tests/` | **Keep** — tests pass without modification |

---

## Code Organization After Refactor

```
services/crypto/
├── traits/                          # NEW: Algorithm markers + OneShot/Streaming traits
│   └── src/lib.rs                   #      ~150 lines, no dependencies
├── backend-rustcrypto/              # NEW: OneShot<A> impls using RustCrypto
│   └── src/lib.rs                   #      ~300 lines
├── backend-hace/                    # FUTURE: OneShot<A> impls using HACE
│   └── src/lib.rs                   #      ~300 lines
├── api/                             # UNCHANGED: Wire protocol
│   └── src/protocol.rs
├── server/                          # REWRITTEN: Generic CryptoServer<B>
│   └── src/main.rs                  #      ~150 lines (was 496)
├── client/                          # UNCHANGED: Client library
│   └── src/lib.rs
└── tests/                           # UNCHANGED: Integration tests
    └── src/main.rs
```

---

## Verification Checkpoints

After each phase:

1. **Build:** `bazel build //services/crypto/...`
2. **Lint:** `bazel build //services/crypto/... --aspects=@aspect_rules_lint//lint:lint.bzl%clippy_lints`
3. **Test:** `bazel test --config=virt_ast1060_evb //target/ast1060/crypto:crypto_test --test_output=all`
4. **Commit:** One commit per phase with descriptive message

---

## Rollback Plan

Each phase is independently deployable:
- Phase 1-2 are additive (no existing code changes)
- Phase 3 is the critical rewrite — keep old server as `main.rs.bak` until tests pass
- Phase 4-5 are additive features

---

## Decision Record

**Date:** February 13, 2026

**Decision:** Implement new composable `OneShot<A>` / `Streaming<A>` traits rather
than reusing existing `openprot-hal-blocking` + `RustCryptoController`.

**Rationale:**
1. Current architecture uses "God trait" pattern requiring all backends to implement all algorithms
2. Adding new algorithms touches shared trait definitions, violating Open-Closed Principle
3. SPDM spec requires 10-15 additional algorithms; current approach would be 3-4 files per algorithm
4. Composable traits allow adding algorithms in 1-2 files with no modifications to existing code
5. HAL traits bundle resource recovery (typestate) with operation semantics—unnecessary for server
6. Service layer traits use session handles, better fit for IPC-based state management

**Tradeoff:** ~6 days upfront work vs. ongoing maintenance cost for 2+ years of algorithm additions.

**Accepted by:** User (February 13, 2026)

**Updated:** February 14, 2026 — Added architectural insights on trait layering and resource recovery decoupling

---

*Ready to execute.*