KMS错误：密钥用途不正确解决方法

摘要：本文旨在帮助开发者解决在使用 Google Cloud KMS (Key Management Service) 时遇到的 “Incorrect key purpose” 错误。该错误通常发生在尝试从 KMS 获取用于加密或解密数据的密钥时，表明密钥的用途与预期不符。本文将解释该错误的原因，并提供相应的解决方案，帮助开发者正确配置和使用 KMS 密钥。

在使用 Google Cloud KMS (Key Management Service) 时，开发者可能会遇到 FAILED_PRECONDITION: Operation requested for Key projects/myproject67567/locations/global/keyRings/test/cryptoKeys/test/cryptoKeyVersions/1 has incorrect key purpose: ENCRYPT_DECRYPT 错误。这个错误表明你试图对一个用途不符合要求的密钥执行操作。通常，这意味着你试图导出对称密钥的公钥，而对称密钥的 purpose 是 ENCRYPT_DECRYPT。

错误原因分析

KMS 中的密钥分为对称密钥和非对称密钥。

• 对称密钥: 对称密钥用于加密和解密，密钥本身不会导出。KMS 负责密钥的管理和使用，应用程序只能通过 KMS 的 API 进行加密和解密操作。对称密钥的 purpose 通常设置为 ENCRYPT_DECRYPT。
• 非对称密钥: 非对称密钥包含公钥和私钥。公钥可以导出，用于加密数据或验证签名，而私钥则保存在 KMS 中，用于解密数据或生成签名。非对称密钥的 purpose 可以是 ASYMMETRIC_ENCRYPT、ASYMMETRIC_DECRYPT 或 ASYMMETRIC_SIGN。

你遇到的错误是因为你试图从一个 purpose 为 ENCRYPT_DECRYPT (对称密钥) 的密钥中获取公钥。对称密钥在 KMS 内部使用，不能导出公钥。

解决方案

要解决这个问题，你需要确保你使用的密钥类型和用途与你的操作相符。

1. 如果你的目标是加密和解密数据，并且不需要导出公钥，那么你应该继续使用对称密钥。 但是，你不能直接获取对称密钥本身。你应该使用 KMS 的 encrypt 和 decrypt API 来进行加密和解密操作。

   以下是一个使用 KMS 对称密钥进行加密的示例 (Java):

   import com.google.cloud.kms.v1.CryptoKeyName;
   import com.google.cloud.kms.v1.KeyManagementServiceClient;
   import com.google.protobuf.ByteString;
   
   import java.io.IOException;
   
   public class KmsEncrypt {
   
       public static ByteString encryptData(String projectId, String locationId, String keyRingId, String cryptoKeyId, String plaintext) throws IOException {
           try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
               CryptoKeyName keyName = CryptoKeyName.of(projectId, locationId, keyRingId, cryptoKeyId);
   
               // Convert the plaintext to a ByteString.
               ByteString plaintextBytes = ByteString.copyFromUtf8(plaintext);
   
               // Call the KMS encrypt API.
               ByteString ciphertext = client.encrypt(keyName, plaintextBytes).getCiphertext();
   
               System.out.printf("Ciphertext: %s%n", ciphertext.toStringUtf8());
               return ciphertext;
           }
       }
   
       public static void main(String[] args) throws IOException {
           // Replace with your project, location, key ring, and crypto key.
           String projectId = "your-project-id";
           String locationId = "global";
           String keyRingId = "your-key-ring-id";
           String cryptoKeyId = "your-crypto-key-id";
           String plaintext = "This is the data to encrypt.";
   
           ByteString ciphertext = encryptData(projectId, locationId, keyRingId, cryptoKeyId, plaintext);
       }
   }

   同样，你需要使用 decrypt API 进行解密。

2. 如果你的目标是使用公钥加密数据（例如，客户端加密），然后使用私钥解密数据（例如，在服务器端），那么你需要创建一个非对称密钥。 创建非对称密钥时，需要选择合适的 purpose (例如 ASYMMETRIC_ENCRYPT) 和算法 (例如 RSA_DECRYPT_OAEP_2048_SHA256)。

   创建非对称密钥后，你可以使用 KMS 的 getPublicKey API 获取公钥。

   以下是一个获取 KMS 非对称密钥公钥的示例 (Java):

   import com.google.api.gax.core.FixedCredentialsProvider;
   import com.google.auth.oauth2.GoogleCredentials;
   import com.google.cloud.kms.v1.CryptoKeyVersionName;
   import com.google.cloud.kms.v1.KeyManagementServiceClient;
   import com.google.cloud.kms.v1.KeyManagementServiceSettings;
   import com.google.cloud.kms.v1.PublicKey;
   
   import java.io.IOException;
   import java.security.NoSuchAlgorithmException;
   import java.util.Collections;
   
   public class KmsGetPublicKey {
   
       public static PublicKey fetchKey(String projectId, String locationId, String keyRingId, String cryptoKeyId, String cryptoKeyVersionId) throws IOException, NoSuchAlgorithmException {
           try {
               KeyManagementServiceSettings keyManagementServiceSettings =
                       KeyManagementServiceSettings.newBuilder()
                               .setCredentialsProvider(FixedCredentialsProvider.create(GoogleCredentials.getApplicationDefault()
                                       .createScoped(Collections.singleton("https://www.googleapis.com/auth/cloudkms"))))
                               .build();
   
               KeyManagementServiceClient client =
                       KeyManagementServiceClient.create(keyManagementServiceSettings);
   
               CryptoKeyVersionName keyVersionName =
                       CryptoKeyVersionName.of(projectId, locationId, keyRingId,
                               cryptoKeyId, cryptoKeyVersionId);
   
               // Get the public key.
               PublicKey publicKey = client.getPublicKey(keyVersionName);
               System.out.printf("Public Key: %s%n", publicKey.getPem());
               return publicKey;
   
           } catch (Exception e) {
               throw new IOException(e);
           }
       }
   
       public static void main(String[] args) throws IOException, NoSuchAlgorithmException {
           // Replace with your project, location, key ring, crypto key, and crypto key version.
           String projectId = "your-project-id";
           String locationId = "global";
           String keyRingId = "your-key-ring-id";
           String cryptoKeyId = "your-crypto-key-id";
           String cryptoKeyVersionId = "1";
   
           PublicKey publicKey = fetchKey(projectId, locationId, keyRingId, cryptoKeyId, cryptoKeyVersionId);
       }
   }

注意事项

• 确保你的 KMS 密钥的 purpose 与你的用例相符。
• 对称密钥不能导出，只能用于 KMS 的加密和解密 API。
• 非对称密钥可以导出公钥，用于客户端加密或其他需要公钥的场景。
• 使用 KMS API 时，需要正确的权限。确保你的服务账户或用户具有访问 KMS 密钥的权限。

总结

Incorrect key purpose 错误通常是因为试图从一个用途不正确的密钥中执行操作。通过理解 KMS 密钥的类型和用途，并根据你的用例选择合适的密钥类型，你可以避免这个错误并正确使用 KMS。 记住，对称密钥用于 KMS 内部的加密和解密，而公钥/私钥对则用于需要公钥的场景。 仔细检查你的密钥配置和代码，确保它们与你的需求一致。