建立 Key Protect 實例及主要金鑰

若要建立 Key Protect 實例及主要金鑰，請執行下列動作:

1. 建立 Key Protect 服務實例。 請參閱 佈建服務。

2. 在此實例中建立客戶根金鑰。 客戶根金鑰作為直欄加密的主要金鑰。 請參閱 建立根金鑰。

   如果您想要使用現有的根金鑰，則可以匯入那些根金鑰。 請參閱 匯入根金鑰。

3. 使用 IBM IAM 服務來配置使用者對主要金鑰的存取權。 請參閱 授與對主要金鑰的存取權。

寫入加密的資料

若要寫入加密資料，請執行下列動作：

1. 將下列參數傳遞至 IBM Analytics Engine 無伺服器:

   • "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 實例的 ID，例如:

     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的金鑰管理中，主要金鑰 ID 是您可以在 IBM Cloud 服務視窗上找到 Key Protect CRK (客戶根金鑰) 的 ID。 例如：

   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" 參數，則會擲出異常狀況。

讀取加密的資料

必要的 meta 資料 (包括 KeyProtect 實例的 ID 和 URL) 儲存在已加密的 Parquet 檔案中。

若要讀取加密的 meta 資料，請執行下列動作：

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)