摘要：本文旨在帮助开发者解决在使用 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 内部使用，不能导出公钥。
解决方案
要解决这个问题，你需要确保你使用的密钥类型和用途与你的操作相符。
-
如果你的目标是加密和解密数据，并且不需要导出公钥，那么你应该继续使用对称密钥。 但是，你不能直接获取对称密钥本身。你应该使用 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 进行解密。
-
如果你的目标是使用公钥加密数据（例如，客户端加密），然后使用私钥解密数据（例如，在服务器端），那么你需要创建一个非对称密钥。 创建非对称密钥时，需要选择合适的 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 内部的加密和解密，而公钥/私钥对则用于需要公钥的场景。 仔细检查你的密钥配置和代码，确保它们与你的需求一致。
