CORE-3695 (#340)

Author: alexey-kadyrov-r3

cipher-suite/src/main/kotlin/net/corda/v5/cipher/suite/CryptoService.kt

@@ -48,7 +48,8 @@ interface CryptoService {
      * Generate and optionally store an asymmetric key pair.
      *
      * @param spec parameters to generate key pair.
-     * @param context the optional key/value operation context.
+     * @param context the optional key/value operation context. The context will have at least two variables defined -
+     * 'tenantId' and 'category'.
      *
      * Returns information about the generated key, could be either [GeneratedPublicKey] or [GeneratedWrappedKey]
      *
@@ -66,7 +67,8 @@ interface CryptoService {
      *
      * @param spec (either [SigningAliasSpec] or [SigningWrappedSpec]) to be used for signing.
      * @param data the data to be signed.
-     * @param context the optional key/value operation context.
+     * @param context the optional key/value operation context. The context will have at least one variable defined -
+     * 'tenantId'.
      *
      * @throws [CryptoServiceBadRequestException] if the private key does not exist as defined in the [key],
      * the key scheme is not supported,  or the [data] is empty array.

cipher-suite/src/main/kotlin/net/corda/v5/cipher/suite/CryptoServiceContext.kt

@@ -0,0 +1,10 @@
+@file:JvmName("CryptoServiceContext")
+
+package net.corda.v5.cipher.suite
+
+/**
+ * Standard [CryptoService] context constants keys.
+ */
+
+const val CRYPTO_TENANT_ID = "tenantId"
+const val CRYPTO_CATEGORY = "category"

cipher-suite/src/main/kotlin/net/corda/v5/cipher/suite/KeyGenerationSpec.kt

@@ -5,7 +5,6 @@ import net.corda.v5.cipher.suite.schemes.SignatureScheme
 /**
  * Defines parameters to generate a key pair.
  *
- * @property tenantId The tenant id which the key pair is generated for.
  * @property signatureScheme The spec defining properties of the key pair being generated.
  * @property alias Optional, the key alias for the pair as defined by the tenant, as that value is not guarantied to be
  * unique, in case if the HSM is shared between several tenants, the implementation must translate it something unique,
@@ -21,8 +20,8 @@ import net.corda.v5.cipher.suite.schemes.SignatureScheme
  * aliases for public and private keys, in such cases their names have to be derived from the single key pair alias.
  * It could be suffixes or whatever internal naming scheme is used.
  */
+@Suppress("LongParameterList")
 class KeyGenerationSpec(
-    val tenantId: String,
     val signatureScheme: SignatureScheme,
     val alias: String?,
     val masterKeyAlias: String?,

cipher-suite/src/main/kotlin/net/corda/v5/cipher/suite/SigningAliasSpec.kt

@@ -5,7 +5,6 @@ import net.corda.v5.cipher.suite.schemes.SignatureScheme
 /**
  * Holding class for the key pair which is persisted in HSM and referenced by its alias.
  *
- * @property tenantId The tenant id which the key pair belongs to.
  * @property hsmAlias The key pair alias assigned by the implementation when the key was generated.
  * @property signatureScheme The scheme for the signing operation.
  *
@@ -14,7 +13,6 @@ import net.corda.v5.cipher.suite.schemes.SignatureScheme
  * It could be suffixes or whatever internal naming scheme is used.
  */
 class SigningAliasSpec(
-    override val tenantId: String,
     val hsmAlias: String,
     override val signatureScheme: SignatureScheme
 ) : SigningSpec

cipher-suite/src/main/kotlin/net/corda/v5/cipher/suite/SigningSpec.kt

@@ -5,10 +5,8 @@ import net.corda.v5.cipher.suite.schemes.SignatureScheme
 /**
  * Marker interface denoting the signing parameters.
  *
- * @property tenantId The tenant id which the key pair belongs to.
  * @property signatureScheme The scheme for the signing operation.
  */
 interface SigningSpec {
-    val tenantId: String
     val signatureScheme: SignatureScheme
 }

cipher-suite/src/main/kotlin/net/corda/v5/cipher/suite/SigningWrappedSpec.kt

@@ -5,15 +5,13 @@ import net.corda.v5.cipher.suite.schemes.SignatureScheme
 /**
  * Holding class for the private key material.
  *
- * @property tenantId The tenant id which the key pair belongs to.
  * @property keyMaterial The encoded and encrypted private key.
  * @property masterKeyAlias The wrapping key's alias which was used for wrapping, the value
  * could be null for HSMs which use built-in wrapping keys.
  * @property encodingVersion The encoding version which was used to encode the private key.
  * @property signatureScheme The scheme for the signing operation.
  */
 class SigningWrappedSpec(
-    override val tenantId: String,
     val keyMaterial: ByteArray,
     val masterKeyAlias: String?,
     val encodingVersion: Int,

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/config/HSMLabel.avsc

@@ -0,0 +1,13 @@
+{
+  "type": "record",
+  "name": "CryptoStringResult",
+  "namespace": "net.corda.data.crypto.wire",
+  "doc": "Defines over-the-wire response for operation which return only single string value",
+  "fields": [
+    {
+      "name": "value",
+      "type": "string",
+      "doc": "The result's value"
+    }
+  ]
+}

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/config/TenantHSMConfig.avsc

@@ -0,0 +1,18 @@
+{
+  "type": "record",
+  "name": "HSMCategoryInfo",
+  "namespace": "net.corda.data.crypto.wire.hsm",
+  "doc": "Defines information about category and HSM configuration relation.",
+  "fields": [
+    {
+      "name": "category",
+      "type": "string",
+      "doc": "Such as LEDGER, TLS, etc."
+    },
+    {
+      "name": "keyPolicy",
+      "type": "PrivateKeyPolicy",
+      "doc": "Policy how a key is generated and persisted in an HSM."
+    }
+  ]
+}

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/persistence/HSMKeyInfo.avsc

@@ -0,0 +1,16 @@
+{
+  "type": "record",
+  "name": "HSMCategoryInfos",
+  "namespace": "net.corda.data.crypto.wire.hsm",
+  "doc": "Defines information about category and HSM configuration relation.",
+  "fields": [
+    {
+      "name": "links",
+      "type": {
+        "type": "array",
+        "items": "HSMCategoryInfo"
+      },
+      "doc": "Collection of HSMCategoryInfo"
+    }
+  ]
+}

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/wire/CryptoStringResult.avsc

@@ -1,8 +1,8 @@
 {
   "type": "record",
   "name": "HSMInfo",
-  "namespace": "net.corda.data.crypto.config",
-  "doc": "Defines persistent record for the HSM common configuration parameters.",
+  "namespace": "net.corda.data.crypto.wire.hsm",
+  "doc": "Defines information for HSM common configuration parameters.",
   "fields": [
     {
       "name": "id",
@@ -18,40 +18,30 @@
       "doc": "Time ([Instant]) in milliseconds when the record was updated or added."
     },
     {
-      "name": "version",
-      "type": "int",
-      "doc": "Ever increasing on each update version of the record, the initial value is 1."
-    },
-    {
-      "name": "hsmLabel",
-      "type": "string",
-      "doc": "Label associated with HSM worker to partition for HSMs which don't support more than one HSM per process/VM. The default value is 'default'."
+      "name": "workerLabel",
+      "type": [
+        "null",
+        "string"
+      ],
+      "doc": "Label associated with HSM worker to partition for HSMs which don't support more than one HSM per process/VM."
     },
     {
       "name": "description",
       "type": "string",
       "doc": "The human readable description of the HSM instance, like 'HSM on the first floor' or anything which helps tp understand what HSM is allocated."
     },
     {
-      "name": "serviceName",
-      "type": "string",
-      "doc": "Name of the CryptoServiceProvider which is sued to create interface to the HSM."
+      "name": "masterKeyPolicy",
+      "type": "MasterKeyPolicy",
+      "doc": "How to generate wrapping key on the HSM registration."
     },
     {
-      "name": "byoTenantId",
+      "name": "masterKeyAlias",
       "type": [
         "null",
         "string"
       ],
-      "doc": "The tenant id which owns the HSM instance. That HSM can be made available only for that tenant."
-    },
-    {
-      "name": "categories",
-      "type": {
-        "type": "array",
-        "items": "string"
-      },
-      "doc": "Categories, like TLS, LEDGER, FRESH_KEYS, etc., the HSM can be used for."
+      "doc": "If masterKeyPolicy=SHARED then this field must be specified with the wrapping key name."
     },
     {
       "name": "retries",
@@ -70,6 +60,16 @@
         "items": "string"
       },
       "doc": "List of supported signature scheme codes, must be a subset of schemes defined in the cipher suite."
+    },
+    {
+      "name": "serviceName",
+      "type": "string",
+      "doc": "Name of the CryptoServiceProvider which is used to create interface to the HSM."
+    },
+    {
+      "name": "capacity",
+      "type": "int",
+      "doc": "Maximum number of tenants that the instance can be assigned to (the actual allocations may exceed slightly that number). -1 means there is no limit"
     }
   ]
 }

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/wire/hsm/HSMCategoryInfo.avsc

@@ -0,0 +1,16 @@
+{
+  "type": "record",
+  "name": "HSMInfos",
+  "namespace": "net.corda.data.crypto.wire.hsm",
+  "doc": "Defines a collection of HSMInfo",
+  "fields": [
+    {
+      "name": "items",
+      "type": {
+        "type": "array",
+        "items": "HSMInfo"
+      },
+      "doc": "Collection of HSMInfo"
+    }
+  ]
+}