Merge pull request #322 from cipherstash/handle-zkms-error-on-startup

fix: improve ZeroKMS error handling and startup validation

Author: tobyhede

docs/errors.md

@@ -22,6 +22,7 @@
   - [KeysetName could not be set](#encrypt-keyset-name-could-not-be-set)
   - [Plaintext could not be encoded](#encrypt-plaintext-could-not-be-encoded)
   - [Unknown column](#encrypt-unknown-column)
+  - [Unknown Keyset Identifier](#encrypt-unknown-keyset)
   - [Unknown table](#encrypt-unknown-table)
   - [Unknown index term](#encrypt-unknown-index-term)
   - [Column configuration mismatch](#encrypt-column-config-mismatch)
@@ -46,14 +47,14 @@ Authentication failed when connecting to the database.
 ### Error message
 
 ```
-Database authentication failed: check username and password
+Database authentication failed. Check username and password
 ```
 
 ### How to fix
 
-Check the configured username and password are correct and can connect to the database.
+1. Check the configured username and password are correct and can connect to the database.
 
-Check the database is using a supported authentication method.
+2. Check the database is using a supported authentication method.
 
 CipherStash Proxy supports several PostgreSQL password authentication methods:
 
@@ -76,21 +77,38 @@ Authentication failed when connecting a client to the proxy.
 ### Error message
 
 ```
-Client authentication failed: check username and password
+Client authentication failed. Check username and password.
 ```
 
 ### How to fix
 
-Check the configured username and password are correct.
+1. Check the configured username and password are correct.
 
 
 
 <!-- ---------------------------------------------------------------------------------------------------- -->
 
 
+## ZeroKMS  <a id='authentication-failed-zerokms'></a>
+
+Authentication failed when connecting to ZeroKMS.
+
+
+### Error message
+
+```
+ZeroKMS authentication failed. Check the configured credentials.
+```
+
+### How to Fix
+
+1. Check that the configured `client` credentials are correct.
+2. Check that the active `keyset_name` or `keyset_id` is associated with a keyset in the configured workspace.
+
 
 <!-- ---------------------------------------------------------------------------------------------------- -->
 
+
 # Mapping errors
 
 
@@ -354,7 +372,7 @@ Keyset Name could not be set using `SET CIPHERSTASH.KEYSET_NAME`
 <!-- ---------------------------------------------------------------------------------------------------- -->
 
 
-## Unknown Keyset Identifier <a id='encrypt-unknown-keyset'></a>
+## Unknown keyset identifier <a id='encrypt-unknown-keyset'></a>
 
 The specified keyset could not be loaded.
 
@@ -370,11 +388,13 @@ Unknown keyset name or id '{keyset}'
 1. Check that the active `keyset_name` or `keyset_id` is associated with a keyset in the configured workspace.
 2. Check that the configured `client` has been granted access to the keyset via the dashboard.
 3. Keyset names are case sensitive. If setting the active keyset by name, check that the `keyset_name` is an exact match.
+4. Check that the configured `client` credentials are correct.
 
 
 <!-- ---------------------------------------------------------------------------------------------------- -->
 
 
+
 ## Could not decrypt data for keyset <a id='encrypt-could-not-decrypt-data-for-keyset'></a>
 
 The data belonging to the active `keyset_id` could not be decrypted.

packages/cipherstash-proxy-integration/src/multitenant/set_keyset_id.rs

@@ -283,7 +283,7 @@ mod tests {
         if let Err(err) = result {
             let msg = err.to_string();
 
-            assert_eq!(msg, "db error: FATAL: Unknown keyset name or id '2cace9db-3a2a-4b46-a184-ba412b3e0730'. For help visit https://github.com/cipherstash/proxy/blob/main/docs/errors.md#encrypt-unknown-keyset");
+            assert_eq!(msg, "db error: FATAL: Unknown keyset name or id '2cace9db-3a2a-4b46-a184-ba412b3e0730'. Check the configured credentials. For help visit https://github.com/cipherstash/proxy/blob/main/docs/errors.md#encrypt-unknown-keyset");
         } else {
             unreachable!();
         }

packages/cipherstash-proxy-integration/src/multitenant/set_keyset_name.rs

@@ -341,7 +341,7 @@ mod tests {
         if let Err(err) = result {
             let msg = err.to_string();
 
-            assert_eq!(msg, "db error: FATAL: Unknown keyset name or id 'BLAHVTHA'. For help visit https://github.com/cipherstash/proxy/blob/main/docs/errors.md#encrypt-unknown-keyset");
+            assert_eq!(msg, "db error: FATAL: Unknown keyset name or id 'BLAHVTHA'. Check the configured credentials. For help visit https://github.com/cipherstash/proxy/blob/main/docs/errors.md#encrypt-unknown-keyset");
         } else {
             unreachable!();
         }

packages/cipherstash-proxy/src/error.rs

@@ -52,7 +52,7 @@ pub enum Error {
     Tls(#[from] rustls::Error),
 
     #[error(transparent)]
-    ZeroKMS(#[from] cipherstash_client::zerokms::Error),
+    ZeroKMS(#[from] ZeroKMSError),
 
     #[error("Unknown error")]
     Unknown,
@@ -67,6 +67,15 @@ pub enum ContextError {
     UnknownPortal,
 }
 
+#[derive(Error, Debug)]
+pub enum ZeroKMSError {
+    #[error("ZeroKMS authentication failed. Check the configured credentials. For help visit {}#zerokms-authentication-failed", ERROR_DOC_BASE_URL)]
+    AuthenticationFailed,
+
+    #[error(transparent)]
+    System(#[from] cipherstash_client::zerokms::Error),
+}
+
 #[derive(Error, Debug)]
 pub enum MappingError {
     #[error("Invalid parameter for column '{}' of type '{}' in table '{}' (OID {}). For help visit {}#mapping-invalid-parameter",
@@ -283,7 +292,7 @@ pub enum EncryptError {
     UnknownColumn { table: String, column: String },
 
     #[error(
-        "Unknown keyset name or id '{keyset}'. For help visit {}#encrypt-unknown-keyset",
+        "Unknown keyset name or id '{keyset}'. Check the configured credentials. For help visit {}#encrypt-unknown-keyset",
         ERROR_DOC_BASE_URL
     )]
     UnknownKeysetIdentifier { keyset: String },
@@ -300,10 +309,10 @@ pub enum EncryptError {
 
 #[derive(Error, Debug)]
 pub enum ProtocolError {
-    #[error("Database authentication failed: check username and password. For help visit {}#authentication-failed-database", ERROR_DOC_BASE_URL)]
+    #[error("Database authentication failed. Check username and password. For help visit {}#authentication-failed-database", ERROR_DOC_BASE_URL)]
     AuthenticationFailed,
 
-    #[error("Client authentication failed: check username and password. For help visit {}#authentication-failed-client", ERROR_DOC_BASE_URL)]
+    #[error("Client authentication failed. Check username and password. For help visit {}#authentication-failed-client", ERROR_DOC_BASE_URL)]
     ClientAuthenticationFailed,
 
     #[error("Expected {expected} parameter format codes, received {received}")]