git.stella-ops.org/docs/security/offline-verification-crypto-provider.md

# Offline Verification Crypto Provider

**Provider ID:** `offline-verification`
**Version:** 1.0
**Status:** Production
**Last Updated:** 2025-12-23
**Sprint:** SPRINT_1000_0007_0002

## Overview

The **OfflineVerificationCryptoProvider** is a cryptographic provider designed for offline and air-gapped environments. It wraps .NET BCL cryptography (`System.Security.Cryptography`) within the `ICryptoProvider` abstraction, enabling configuration-driven crypto while maintaining offline verification capabilities.

This provider is particularly useful for:
- **Air-gapped deployments** where hardware security modules (HSMs) are unavailable
- **Offline bundle verification** in disconnected environments
- **Development and testing** environments
- **Fallback scenarios** when regional crypto providers are unavailable

## When to Use This Provider

### ✅ Recommended Use Cases

1. **Air-Gapped Bundle Verification**
   - Verifying DSSE-signed evidence bundles in disconnected environments
   - Validating attestations without external connectivity
   - Offline policy verification

2. **Development & Testing**
   - Local development without HSM dependencies
   - CI/CD pipelines for automated testing
   - Integration test environments

3. **Fallback Provider**
   - When regional providers (GOST, SM, eIDAS) are unavailable
   - Default offline verification path

### ❌ NOT Recommended For

1. **Production Signing Operations** - Use HSM-backed providers instead
2. **Compliance-Critical Scenarios** - Use certified providers (FIPS, eIDAS, etc.)
3. **High-Value Key Storage** - Use hardware-backed key storage

## Supported Algorithms

### Signing & Verification

| Algorithm | Curve/Key Size | Hash | Padding | Notes |
|-----------|----------------|------|---------|-------|
| ES256 | NIST P-256 | SHA-256 | N/A | ECDSA with SHA-256 |
| ES384 | NIST P-384 | SHA-384 | N/A | ECDSA with SHA-384 |
| ES512 | NIST P-521 | SHA-512 | N/A | ECDSA with SHA-512 |
| RS256 | RSA 2048+ | SHA-256 | PKCS1 | RSA with PKCS#1 v1.5 padding |
| RS384 | RSA 2048+ | SHA-384 | PKCS1 | RSA with PKCS#1 v1.5 padding |
| RS512 | RSA 2048+ | SHA-512 | PKCS1 | RSA with PKCS#1 v1.5 padding |
| PS256 | RSA 2048+ | SHA-256 | PSS | RSA-PSS with SHA-256 |
| PS384 | RSA 2048+ | SHA-384 | PSS | RSA-PSS with SHA-384 |
| PS512 | RSA 2048+ | SHA-512 | PSS | RSA-PSS with SHA-512 |

### Content Hashing

| Algorithm | Output Size | Aliases |
|-----------|-------------|---------|
| SHA-256 | 32 bytes | SHA256 |
| SHA-384 | 48 bytes | SHA384 |
| SHA-512 | 64 bytes | SHA512 |

### Password Hashing

**Not Supported.** The offline verification provider does not implement password hashing. Use dedicated password hashers:
- `Argon2idPasswordHasher` for modern password hashing
- `Pbkdf2PasswordHasher` for legacy compatibility

## API Reference

### Basic Usage

```csharp
using StellaOps.Cryptography;
using StellaOps.Cryptography.Plugin.OfflineVerification;

// Create provider instance
var provider = new OfflineVerificationCryptoProvider();

// Check algorithm support
bool supportsES256 = provider.Supports(CryptoCapability.Signing, "ES256");
// Returns: true

// Get a hasher
var hasher = provider.GetHasher("SHA-256");
var hash = hasher.ComputeHash(dataBytes);

// Get a signer (requires key reference)
var keyRef = new CryptoKeyReference("my-signing-key");
var signer = provider.GetSigner("ES256", keyRef);
var signature = await signer.SignAsync(dataBytes);
```

### Ephemeral Verification (New in v1.0)

For verification-only scenarios where you have raw public key bytes (e.g., DSSE verification):

```csharp
// Create ephemeral verifier from SubjectPublicKeyInfo bytes
byte[] publicKeyBytes = LoadPublicKeyFromDsse();
var verifier = provider.CreateEphemeralVerifier("ES256", publicKeyBytes);

// Verify signature (no private key required)
var isValid = await verifier.VerifyAsync(dataBytes, signatureBytes);
```

**When to use ephemeral verification:**
- DSSE envelope verification with inline public keys
- One-time verification operations
- No need to persist keys in provider's key store

### Dependency Injection Setup

```csharp
using Microsoft.Extensions.DependencyInjection;
using StellaOps.Cryptography;
using StellaOps.Cryptography.Plugin.OfflineVerification;

// Add to DI container
services.AddSingleton<ICryptoProvider, OfflineVerificationCryptoProvider>();

// Or use with crypto provider registry
services.AddSingleton<ICryptoProviderRegistry>(sp =>
{
    var registry = new CryptoProviderRegistry();
    registry.RegisterProvider(new OfflineVerificationCryptoProvider());
    return registry;
});
```

### Air-Gapped Bundle Verification Example

```csharp
using StellaOps.Cryptography;
using StellaOps.Cryptography.Plugin.OfflineVerification;
using StellaOps.AirGap.Importer.Validation;

// Initialize provider
var cryptoRegistry = new CryptoProviderRegistry([
    new OfflineVerificationCryptoProvider()
]);

// Create DSSE verifier with crypto provider
var dsseVerifier = new DsseVerifier(cryptoRegistry);

// Verify bundle signature
var trustRoots = new TrustRootConfig
{
    PublicKeys = new Dictionary<string, byte[]>
    {
        ["airgap-signer"] = LoadPublicKeyBytes()
    },
    TrustedKeyFingerprints = new HashSet<string>
    {
        ComputeFingerprint(LoadPublicKeyBytes())
    }
};

var result = dsseVerifier.Verify(dsseEnvelope, trustRoots);
if (result.IsSuccess)
{
    Console.WriteLine("Bundle signature verified successfully!");
}
```

## Configuration

### crypto-plugins-manifest.json

The offline verification provider is typically enabled by default:

```json
{
  "plugins": [
    {
      "name": "offline-verification",
      "assembly": "StellaOps.Cryptography.Plugin.OfflineVerification.dll",
      "type": "StellaOps.Cryptography.Plugin.OfflineVerification.OfflineVerificationCryptoProvider",
      "enabled": true,
      "priority": 45,
      "config": {}
    }
  ]
}
```

**Priority:** `45` - Higher than default (50), lower than regional providers (10-40)

### Environment Variables

No environment variables required. The provider is self-contained.

## Security Considerations

### ✅ Safe for Verification

The offline verification provider is **safe for verification operations** in offline environments:
- Public key verification
- Signature validation
- Hash computation
- Bundle integrity checks

### ⚠️ Signing Key Protection

**Private keys used with this provider MUST be protected:**
1. **Key Storage:**
   - Use encrypted key files with strong passphrases
   - Store in secure filesystem locations with restricted permissions
   - Consider using OS-level key storage (Windows DPAPI, macOS Keychain)

2. **Key Rotation:**
   - Rotate signing keys periodically
   - Maintain key version tracking for bundle verification

3. **Access Control:**
   - Limit file system permissions on private keys (chmod 600 on Unix)
   - Use separate keys for dev/test/prod environments

### Deterministic Operations

The provider ensures deterministic operations where required:
- **Hash computation:** SHA-256/384/512 are deterministic
- **Signature verification:** Deterministic for given signature and public key
- **ECDSA signing:** Uses deterministic nonce generation (RFC 6979) when available

## Limitations

1. **No HSM Support:** Keys are software-based, not hardware-backed
2. **No Compliance Certification:** Not FIPS 140-2, eIDAS, or other certified implementations
3. **Algorithm Limitations:** Only supports algorithms in .NET BCL
4. **No Password Hashing:** Use dedicated password hashers instead

## Migration Guide

### From Direct System.Security.Cryptography

**Before:**
```csharp
using System.Security.Cryptography;

var hash = SHA256.HashData(dataBytes);  // ❌ Direct BCL usage
```

**After:**
```csharp
using StellaOps.Cryptography;

var hasher = cryptoRegistry.ResolveHasher("SHA-256");
var hash = hasher.Hasher.ComputeHash(dataBytes);  // ✅ Provider abstraction
```

### From Legacy Crypto Plugins

Replace legacy plugin references with OfflineVerificationCryptoProvider:

1. Update `crypto-plugins-manifest.json`
2. Replace plugin DI registration
3. Update algorithm IDs to standard names (ES256, RS256, etc.)

## Testing

Comprehensive unit tests are available in:
`src/__Libraries/__Tests/StellaOps.Cryptography.Tests/OfflineVerificationCryptoProviderTests.cs`

Run tests:
```bash
dotnet test src/__Libraries/__Tests/StellaOps.Cryptography.Tests/
```

## Related Documentation

- [Crypto Provider Registry](../contracts/crypto-provider-registry.md)
- [Crypto Plugin Development Guide](../cli/crypto-plugins.md)
- [Air-Gapped Bundle Verification](../airgap/bundle-verification.md)
- [DSSE Signature Verification](../contracts/dsse-envelope.md)

## Support & Troubleshooting

### Provider Not Found

```
Error: Crypto provider 'offline-verification' not found
```

**Solution:** Ensure plugin is registered in `crypto-plugins-manifest.json` with `enabled: true`

### Algorithm Not Supported

```
Error: Algorithm 'ES256K' is not supported
```

**Solution:** Check [Supported Algorithms](#supported-algorithms) table. The offline provider only supports .NET BCL algorithms.

### Ephemeral Verifier Creation Fails

```
Error: Failed to create ephemeral verifier
```

**Causes:**
1. Invalid public key format (must be SubjectPublicKeyInfo DER-encoded)
2. Unsupported algorithm
3. Corrupted public key bytes

**Solution:** Verify public key format and algorithm compatibility.

## Changelog

### Version 1.0 (2025-12-23)
- Initial release
- Support for ES256/384/512, RS256/384/512, PS256/384/512
- SHA-256/384/512 content hashing
- Ephemeral verifier creation from raw public key bytes
- Comprehensive unit test coverage (39 tests)