Refactor and simplify KeyManager API (#1650)

4 files changed, 60 insertions, 25 deletions

diff --git a/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/CryptoException.kt b/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/CryptoException.kt
index 34e64d5f..431cd90c 100644
--- a/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/CryptoException.kt
+++ b/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/CryptoException.kt
@@ -2,18 +2,28 @@ package dev.msfjarvis.aps.crypto
 
 public sealed class CryptoException(message: String? = null) : Exception(message)
 
-public sealed class KeyPairException(message: String? = null) : CryptoException(message) {
-  public object PrivateKeyUnavailableException :
-    KeyPairException("Key object does not have a private sub-key")
-}
-
+/** Sealed exception types for [KeyManager]. */
 public sealed class KeyManagerException(message: String? = null) : CryptoException(message) {
+
+  /** Store contains no keys. */
   public object NoKeysAvailableException : KeyManagerException("No keys were found")
+
+  /** Key directory does not exist or cannot be accessed. */
   public object KeyDirectoryUnavailableException :
     KeyManagerException("Key directory does not exist")
+
+  /** Failed to delete given key. */
   public object KeyDeletionFailedException : KeyManagerException("Couldn't delete the key file")
+
+  /** Failed to parse a [Key] as a known type. */
+  public object InvalidKeyException :
+    KeyManagerException("Given key cannot be parsed as a known key type")
+
+  /** No key matching [keyId] could be found. */
   public class KeyNotFoundException(keyId: String) :
     KeyManagerException("No key found with id: $keyId")
+
+  /** Attempting to add another key for [keyId] without requesting a replace. */
   public class KeyAlreadyExistsException(keyId: String) :
-    KeyManagerException("Pre-existing key was found for $keyId but 'replace' is set to false")
+    KeyManagerException("Pre-existing key was found for $keyId")
 }
diff --git a/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/Key.kt b/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/Key.kt
new file mode 100644
index 00000000..73dee199
--- /dev/null
+++ b/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/Key.kt
@@ -0,0 +1,14 @@
+/*
+ * Copyright © 2014-2021 The Android Password Store Authors. All Rights Reserved.
+ * SPDX-License-Identifier: GPL-3.0-only
+ */
+
+package dev.msfjarvis.aps.crypto
+
+/**
+ * A simple value class wrapping over a [ByteArray] that can be used as a key type for cryptographic
+ * purposes. The public/private distinction is elided specifically to defer that decision to
+ * implementations of [KeyManager]. Similarly, identification of the key's identities is also
+ * deferred to [KeyManager] to ensure maximum flexibility.
+ */
+@JvmInline public value class Key(public val contents: ByteArray)
diff --git a/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/KeyManager.kt b/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/KeyManager.kt
index 2f901354..dacdfc6a 100644
--- a/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/KeyManager.kt
+++ b/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/KeyManager.kt
@@ -7,12 +7,37 @@ package dev.msfjarvis.aps.crypto
 
 import com.github.michaelbull.result.Result
 
-public interface KeyManager<T : KeyPair> {
+/**
+ * [KeyManager] defines a contract for implementing a management system for [Key]s as they would be
+ * used by an implementation of [CryptoHandler] to obtain eligible public or private keys as
+ * required.
+ */
+public interface KeyManager {
+
+  /**
+   * Inserts a [key] into the store. If the key already exists, this method will return
+   * [KeyManagerException.KeyAlreadyExistsException] unless [replace] is `true`.
+   */
+  public suspend fun addKey(key: Key, replace: Boolean = false): Result<Key, Throwable>
+
+  /** Removes [key] from the store. */
+  public suspend fun removeKey(key: Key): Result<Key, Throwable>
+
+  /**
+   * Get a [Key] for the given [id]. The actual semantics of what [id] is are left to individual
+   * implementations to figure out for themselves. For example, in GPG this can be a full
+   * hexadecimal key ID, an email, a short hex key ID, and probably a few more things.
+   */
+  public suspend fun getKeyById(id: String): Result<Key, Throwable>
+
+  /** Returns all keys currently in the store as a [List]. */
+  public suspend fun getAllKeys(): Result<List<Key>, Throwable>
 
-  public suspend fun addKey(key: T, replace: Boolean = false): Result<T, Throwable>
-  public suspend fun removeKey(key: T): Result<T, Throwable>
-  public suspend fun getKeyById(id: String): Result<T, Throwable>
-  public suspend fun getAllKeys(): Result<List<T>, Throwable>
+  /**
+   * Get a stable identifier for the given [key]. The returned key ID should be suitable to be used
+   * as an identifier for the cryptographic identity tied to this key.
+   */
+  public suspend fun getKeyId(key: Key): String?
 
   /** Given a [fileName], return whether this instance can handle it. */
   public fun canHandle(fileName: String): Boolean
diff --git a/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/KeyPair.kt b/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/KeyPair.kt
deleted file mode 100644
index b8dec216..00000000
--- a/crypto-common/src/main/kotlin/dev/msfjarvis/aps/crypto/KeyPair.kt
+++ /dev/null
@@ -1,14 +0,0 @@
-/*
- * Copyright © 2014-2021 The Android Password Store Authors. All Rights Reserved.
- * SPDX-License-Identifier: GPL-3.0-only
- */
-
-package dev.msfjarvis.aps.crypto
-
-/** Defines expectations for a keypair used in public key cryptography. */
-public interface KeyPair {
-
-  public fun getPrivateKey(): ByteArray
-  public fun getPublicKey(): ByteArray
-  public fun getKeyId(): String
-}