[KeyManager] Add protobuf definitions for standardizing error handling (#721)

This commit introduces the foundational infrastructure for standardizing error handling across the Go-Rust FFI boundary in the `KeyManager` component. By moving to Protobuf-defined error codes, we ensure that both Go and Rust have a shared, type-safe understanding of failure states, replacing more brittle or inconsistent error-passing mechanisms.

Key Changes
   - Standardized Error Definitions: Introduced `status.proto`, which defines a comprehensive Error enum covering common failure scenarios such as `INTERNAL_ERROR`, `INVALID_ARGUMENT`, `CRYPTO_ERROR`, and more.
   - Go Integration:
       - Added a `FFIStatus` struct that implements the Go error interface.
       - Provided a `ToStatus()` helper on the generated Protobuf Error type to simplify converting FFI return codes into idiomatic Go errors.
   - Rust Infrastructure:
       - Integrated the new Status `proto` into the Rust build pipeline.
       - Implemented `std::status::Status` and `fmt::Display` for the generated Rust Error type.
       - Added `ffi_call` and `ffi_call_i32` utility functions. these helpers wrap FFI operations in catch_unwind blocks to prevent panics from crossing the FFI boundary, translating them into standardized `ERROR_INTERNAL` codes instead.
   - Tooling: Updated the `gen_keymanager.sh` script to ensure consistent Go code generation for the new error definitions.

Author: NilanjanDaw

keymanager/km_common/build.rs

@@ -8,7 +8,10 @@ fn main() -> Result<()> {
 
     let mut config = prost_build::Config::new();
 
-    config.compile_protos(&["proto/algorithms.proto"], &["proto/"])?;
+    config.compile_protos(
+        &["proto/algorithms.proto", "proto/status.proto"],
+        &["proto/"],
+    )?;
 
     Ok(())
 }

keymanager/km_common/proto/algorithms.pb.go

@@ -0,0 +1,36 @@
+// Package keymanager provides common cryptographic utilities and FFI wrappers.
+package keymanager
+
+import (
+	"fmt"
+)
+
+// FFIStatus represents a status returned from the Rust FFI.
+type FFIStatus struct {
+	Code Status
+}
+
+func (e *FFIStatus) Error() string {
+	return fmt.Sprintf("FFI status: %s", e.Code.String())
+}
+
+// Is allows users to check errors.Is(err, Status_CODE.ToStatus()) or errors.Is(err, &FFIStatus{Code: Status_CODE}).
+func (e *FFIStatus) Is(target error) bool {
+	if t, ok := target.(*FFIStatus); ok {
+		return e.Code == t.Code
+	}
+	return false
+}
+
+// Status returns the string representation of the Status.
+func (e Status) Status() string {
+	return e.String()
+}
+
+// ToStatus converts a Status to a Go error, or returns nil if it is Success.
+func (e Status) ToStatus() error {
+	if e == Status_STATUS_SUCCESS {
+		return nil
+	}
+	return &FFIStatus{Code: e}
+}

keymanager/km_common/proto/status.go

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package keymanager;
+
+option go_package = "github.com/google/go-tpm-tools/keymanager/km_common/proto;keymanager";
+
+enum Status {
+  STATUS_UNSPECIFIED = 0;
+  STATUS_SUCCESS = 1;
+  STATUS_INTERNAL_ERROR = 2;
+  STATUS_INVALID_ARGUMENT = 3;
+  STATUS_NOT_FOUND = 4;
+  STATUS_ALREADY_EXISTS = 5;
+  STATUS_PERMISSION_DENIED = 6;
+  STATUS_UNAUTHENTICATED = 7;
+  STATUS_UNSUPPORTED_ALGORITHM = 8;
+  STATUS_INVALID_KEY = 9;
+  STATUS_CRYPTO_ERROR = 10;
+  STATUS_DECRYPTION_FAILURE = 11;
+  STATUS_ENCRYPTION_FAILURE = 12;
+  STATUS_DECAPSULATION_FAILURE = 13;
+}

keymanager/km_common/proto/status.pb.go

@@ -0,0 +1,45 @@
+package keymanager
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestFFIStatus(t *testing.T) {
+	err := Status_STATUS_INTERNAL_ERROR.ToStatus()
+	if err == nil {
+		t.Fatalf("ToStatus() = nil, want error")
+	}
+	if !errors.Is(err, Status_STATUS_INTERNAL_ERROR.ToStatus()) {
+		t.Errorf("errors.Is(err, Status_STATUS_INTERNAL_ERROR.ToStatus()) = false, want true")
+	}
+	if errors.Is(err, Status_STATUS_INVALID_ARGUMENT.ToStatus()) {
+		t.Errorf("errors.Is(err, Status_STATUS_INVALID_ARGUMENT.ToStatus()) = true, want false")
+	}
+
+	// Test with FFIStatus pointer
+	if !errors.Is(err, &FFIStatus{Code: Status_STATUS_INTERNAL_ERROR}) {
+		t.Errorf("errors.Is(err, &FFIStatus{Code: Status_STATUS_INTERNAL_ERROR}) = false, want true")
+	}
+	if errors.Is(err, &FFIStatus{Code: Status_STATUS_INVALID_ARGUMENT}) {
+		t.Errorf("errors.Is(err, &FFIStatus{Code: Status_STATUS_INVALID_ARGUMENT}) = true, want false")
+	}
+
+	// Test other error type
+	if errors.Is(err, errors.New("other error")) {
+		t.Errorf("errors.Is(err, errors.New(\"other error\")) = true, want false")
+	}
+}
+
+func TestFFIStatusSuccess(t *testing.T) {
+	if err := Status_STATUS_SUCCESS.ToStatus(); err != nil {
+		t.Errorf("Status_STATUS_SUCCESS.ToStatus() = %v, want nil", err)
+	}
+}
+
+func TestStatusMethod(t *testing.T) {
+	val := Status_STATUS_INTERNAL_ERROR
+	if val.Status() != "STATUS_INTERNAL_ERROR" {
+		t.Errorf("Status_STATUS_INTERNAL_ERROR.Status() = %q, want \"STATUS_INTERNAL_ERROR\"", val.Status())
+	}
+}

keymanager/km_common/proto/status.proto

@@ -1,7 +1,7 @@
 use crate::algorithms::{AeadAlgorithm, HpkeAlgorithm, KdfAlgorithm, KemAlgorithm};
+use crate::crypto::secret_box::SecretBox;
 #[cfg(any(test, feature = "test-utils"))]
 use crate::crypto::PrivateKey;
-use crate::crypto::secret_box::SecretBox;
 use crate::crypto::{Error, PrivateKeyOps, PublicKeyOps};
 use bssl_crypto::{hkdf, hpke, x25519};
 

keymanager/km_common/proto/status_test.go

@@ -1,6 +1,38 @@
-pub mod algorithms {
+pub mod keymanager {
     include!(concat!(env!("OUT_DIR"), "/keymanager.rs"));
 }
+pub use keymanager as algorithms;
+pub use keymanager as proto;
+
+pub use proto::Status;
+
+impl std::error::Error for Status {}
+impl std::fmt::Display for Status {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{:?}", self)
+    }
+}
+
+/// Helper function to safely execute an FFI closure, catch panics, and return a standardized Status.
+pub fn ffi_call<F>(f: F) -> Status
+where
+    F: FnOnce() -> Result<(), Status>,
+{
+    std::panic::catch_unwind(std::panic::AssertUnwindSafe(f))
+        .unwrap_or(Err(Status::InternalError))
+        .err()
+        .unwrap_or(Status::Success)
+}
+
+/// Helper function for FFI calls returning i32 (positive for count/success, negative for Status).
+pub fn ffi_call_i32<F>(f: F) -> i32
+where
+    F: FnOnce() -> Result<i32, Status>,
+{
+    std::panic::catch_unwind(std::panic::AssertUnwindSafe(f))
+        .unwrap_or(Err(Status::InternalError))
+        .unwrap_or_else(|e| -(e as i32))
+}
 
 pub mod crypto;
 pub mod key_types;

keymanager/km_common/src/crypto/x25519.rs

@@ -7,3 +7,5 @@ protoc -I. --go_out=. --go_opt=paths=source_relative keymanager/km_common/proto/
 protoc -I. --go_out=. --go_opt=paths=source_relative keymanager/km_common/proto/key_claims.proto
 # Generate payload.pb.go
 protoc -I. --go_out=. --go_opt=paths=source_relative keymanager/km_common/proto/payload.proto
+# Generate status.pb.go
+protoc -I. --go_out=. --go_opt=paths=source_relative keymanager/km_common/proto/status.proto