[EPIC](plugins) CMK Keystore Plugin for L1 Key Operations using OpenBao Transit Keys

[nnicora]

Implement a new Keystore Operation Plugin that enables OpenKCM to use the OpenBao Transit Secret Engine for L1 (Customer Managed Key) operations. This allows the L1 key to serve as the root of trust for the internal key hierarchy (L2, L3) without the key material ever entering the OpenKCM application memory.

The plugin will act as a secure proxy, delegating all cryptographic tasks to OpenBao's "Encryption as a Service" API, thereby enabling native BYOK (Bring Your Own Key) and HYOK (Hold Your Own Key) capabilities.

💼 Business Context & Value

• Root of Trust Security: L1 keys are the foundation of isolation. Keeping them inside OpenBao/HSM ensures they are never exposed to the application layer.
• BYOK/HYOK Support: Customers can maintain exclusive control over the L1 key in their own OpenBao instance or managed HSM.
• Compliance: Satisfies FIPS 140-2/3 and data sovereignty requirements by ensuring root keys never leave their secure boundary.

---

🏗 Architecture Overview

The plugin implements the standard OpenKCM Keystore Operation interface. Instead of performing local cryptography, it maps gRPC calls to OpenBao Transit API endpoints.

---

🛠 Functional Requirements

1. Keystore Plugin Implementation

• Implement the plugin interface defined in the SDK:
  https://github.tools.sap/kms/plugin-sdk/blob/main/proto/plugin/keystore/operations/v1/operations.pb.go
• Supported Operations:
  • Encrypt: Proxy to /transit/encrypt/{key_name}.
  • Decrypt: Proxy to /transit/decrypt/{key_name}.
• Authentication: Must support configurable authentication methods (e.g., Kubernetes Auth, AppRole, or Token).

2. L1 Key Operations

• Key Isolation: Ensure L1 keys never leave the OpenBao environment in plaintext.
• Envelope Encryption: Use the L1 Transit key to wrap/unwrap Internal Versioned Keys (IVK/L2).
• Transactional Safety: Cryptographic operations must be atomic. Partial successes are not permitted; network failures must trigger clean error states.

---

🛡 Non-Functional Requirements

• Security: - Zero exposure of L1 plaintext keys in application memory, logs, or core dumps.
  • All communication with OpenBao must use TLS 1.3.
• Performance: - Implement persistent connection pooling to the OpenBao API.
  • Ensure L1 operations (which occur during unsealing or rotation) do not become a system bottleneck.
• Resilience: - Handle network partitions or OpenBao "sealed" states gracefully.
  • Implement exponential backoff for transient API failures.
• Auditability: - Log all plugin operations with OperationType, KeyIdentifier, KeyVersion, and Timestamp.
  • Prohibition: Strictly forbid logging of request/response payloads (Ciphertext/Plaintext).

---

✅ Acceptance Criteria

• Plugin successfully implements the keystore/operations/v1 gRPC contract.
• Integration test confirms L1 keys are never exposed in plaintext outside of OpenBao.
• Successful encryption/decryption of L2 keys using an L1 key hosted in a remote OpenBao instance.
• Audit logs correctly capture metadata for all Transit API interactions.
• Plugin handles OpenBao "Key Not Found" or "Permission Denied" errors with appropriate OpenKCM error codes.