创建 Key Protect 实例和主密钥

要创建密钥保护实例和主密钥，请执行以下操作:

1. 创建 Key Protect 服务实例。 请参阅 供应服务。

2. 在此实例中创建客户根密钥。 客户根密钥充当列加密的主密钥。 请参阅 创建根密钥。

   如果要使用现有根密钥，那么可以导入这些根密钥。 请参阅 导入根密钥。

3. 使用 IBM IAM 服务配置用户对主密钥的访问权。 请参阅 授予对主密钥的访问权。

写入加密数据

要写入加密数据：

1. 将以下参数传递到 IBM Analytics Engine Serverless:

   • "parquet.crypto.factory.class": 实现 EncryptionPropertiesFactory 的类。 设置为 "com.ibm.parquet.key.management.IBMKeyToolsFactory"。

     sc.hadoopConfiguration.set("parquet.crypto.factory.class","com.ibm.parquet.key.management.IBMKeyToolsFactory")
     

   • "parquet.encryption.kms.instance.id": KeyProtect 实例的标识，例如:

     sc.hadoopConfiguration.set("parquet.encryption.kms.instance.id" , "27861a9a-6779-4026-bca4-01e59acf0767")
     

   • "parquet.encryption.kms.instance.url": KeyProtect 实例的 URL ，例如:

     sc.hadoopConfiguration.set("parquet.encryption.kms.instance.url" , "https://<region>.kms.cloud.ibm.com")
     

   • "parquet.encryption.key.access.token": 具有对 KeyProtect 实例中所需密钥的访问权的有效 IAM 令牌，例如:

     sc.hadoopConfiguration.set("parquet.encryption.key.access.token" , "<token string>")
     

     如果将令牌保留在本地文件中，那么可以将其装入。

     val token = scala.io.Source.fromFile("<token file>").mkString
     sc.hadoopConfiguration.set("parquet.encryption.key.access.token" , token)
     

2. 指定需要加密的列以及要使用的主密钥。 您还必须指定页脚密钥。 在 Key Protect的密钥管理中，主密钥标识是可在 IBM Cloud 服务窗口上找到的 Key Protect CRK (客户根密钥) 的标识。 例如：

   val k1 = "d1ae3fc2-6b7d-4a03-abb6-644e02933734"
   val k2 = "c4a21521-2a78-4968-a7c2-57c481f58d5c"
   val k3 = "a4ae4bc2-9d78-8748-f8a2-17f584d48c5b"
   
   dataFrame.write
   .option("parquet.encryption.footer.key" , k1)
   .option("parquet.encryption.column.keys" , k2+":SSN,Address;"+k3+":CreditCard")
   .parquet("<path to encrypted files>")
   

   注: 如果未设置 "parquet.encryption.column.keys" 参数或 "parquet.encryption.footer.key" 参数，那么将抛出异常。

读取加密数据

所需的元数据 (包括 KeyProtect 实例的标识和 URL) 存储在加密的 Parquet 文件中。

要读取加密元数据：

1. 设置实现 EncryptionPropertiesFactory 的类:

   sc.hadoopConfiguration.set("parquet.crypto.factory.class","com.ibm.parquet.key.management.IBMKeyToolsFactory")
   

2. 为相关密钥提供 IAM 访问令牌:

   sc.hadoopConfiguration.set("parquet.encryption.key.access.token" , "<token string>")
   

3. 调用常规的 parquet 读取命令，例如：

   val dataFrame = spark.read.parquet("<path to encrypted files>")
   

密钥轮换

如果需要密钥轮换，那么管理员必须使用 手动轮换密钥中描述的过程在 Key Protect 中轮换主密钥。 然后，管理员可以通过调用以下命令来触发 Parquet 密钥轮换:

public static void KeyToolkit.rotateMasterKeys(String folderPath, Configuration hadoopConfig)

要启用 Parquet 密钥轮换，必须设置以下 Hadoop 配置属性：

• 参数 "parquet.encryption.key.access.token"， "parquet.encryption.kms.instance.url"和 "parquet.encryption.kms.instance.id"

• 参数 "parquet.encryption.key.material.store.internally" 必须设置为 "false"

• 参数 "parquet.encryption.kms.client.class" 必须设置为 "com.ibm.parquet.key.management.KeyProtectClient"

• 参数 "parquet.crypto.factory.class" 必须设置为 "com.ibm.parquet.key.management.IBMKeyToolsFactory"

  例如：

  sc.hadoopConfiguration.set("parquet.encryption.key.access.token" , "<token string>")
  sc.hadoopConfiguration.set("parquet.encryption.kms.instance.url" , "https://<region>.kms.cloud.ibm.com")
  sc.hadoopConfiguration.set("parquet.encryption.kms.instance.id", "27861a9a-6779-4026-bca4-01e59acf0767")
  sc.hadoopConfiguration.set("parquet.encryption.key.material.store.internally", "false")
  sc.hadoopConfiguration.set("parquet.encryption.kms.client.class" "com.ibm.parquet.key.management.KeyProtectClient")
  sc.hadoopConfiguration.set("parquet.crypto.factory.class","com.ibm.parquet.key.management.IBMKeyToolsFactory")
  
  KeyToolkit.rotateMasterKeys("<path to encrypted files>", sc.hadoopConfiguration)