当您创建密钥材料来源为外部的密钥时,KMS不会为您创建的用户主密钥(CMK)生成密钥材料,此时您可以将自己的密钥材料导入到CMK中。本文为您介绍如何导入外部密钥材料。

背景信息

用户主密钥(CMK)是KMS的基本资源,由密钥ID、基本元数据(如密钥状态等)以及用于加密、解密数据的密钥材料组成。默认情况下,当您创建CMK时,会由KMS生成密钥材料。您也可以选择创建密钥材料来源为外部的密钥,此时,KMS将不会为您创建的CMK生成密钥材料,您可以将自己的密钥材料导入到CMK中。

导入密钥材料时,您可以导入从未被导入过的密钥材料,也可以重新导入已经过期和已被删除的密钥材料,或者重置密钥材料的过期时间。

您可以调用DescribeKey接口判断密钥材料来源。
  • 当KeyMetadata中OriginAliyun_KMS时,说明密钥材料由KMS生成,该密钥称为普通密钥
  • OriginEXTERNAL时,说明密钥材料由外部导入,该密钥称为外部密钥
当您使用由外部导入的密钥材料时,需要注意以下几点:
  • 请确保您使用了符合要求的随机源生成密钥材料。
  • 请确保密钥材料的可靠性。
    • KMS可以确保导入密钥材料高可用,但是不能确保导入密钥材料与KMS生成的密钥材料具有相同的可靠性。
    • 导入的密钥材料被删除后,可以再次导入相同的密钥材料使得CMK再次可用,因此您需要自行保存密钥材料的副本。
  • 导入密钥材料后,您可以直接调用DeleteKeyMaterial接口删除密钥材料,也可以设置过期时间,在密钥材料过期后进行删除(CMK不会被删除)。
  • 每个CMK只能拥有一个导入密钥材料。当您将一个密钥材料导入CMK时,CMK将与密钥材料绑定,即便密钥材料已经过期或者被删除,也不能导入其他密钥材料。如果您需要轮换使用外部密钥材料的CMK,只能创建一个新的CMK然后导入新的密钥材料。
  • CMK具有独立性。例如:您使用CMK加密的数据,无法使用其他CMK进行解密,即便这些CMK都使用相同的密钥材料。
  • 只能导入128位(SM4)或256位(AES)的对称密钥作为密钥材料。128位(SM4)密钥仅支持部分地域。更多信息,请参见支持的地域

通过控制台导入密钥材料

  1. 创建外部密钥。
    1. 登录密钥管理服务控制台,在页面左上角的地域下拉列表,选择密钥所在的地域。
    2. 在左侧导航栏,单击用户主密钥
    3. 单击创建密钥,在创建密钥对话框完成各项的配置。
      配置项 说明
      KMS实例 选择默认,不支持修改。
      密钥类型 选择对称密钥类型Aliyun_AES_256或Aliyun_SM4。关于对称密钥类型的更多信息,请参见对称密钥的类型
      密钥用途 选择密钥的用途。取值:
      • Encrypt/Decrypt:数据加密和解密。
      • Sign/Verify:产生和验证数字签名。
      别名 用户主密钥的标识符。支持英文字母、数字、下划线(_)、短划线(-)和正斜线(/)。

      更多信息,请参见别名概述

      保护级别 密钥的保护级别。取值:
      • Software:通过软件模块对密钥进行保护。
      • Hsm:将密钥托管在密码机中,使密钥获得高安全等级的专用硬件的保护。
      描述 密钥的说明信息。
      轮转周期 设置对称密钥自动轮转的时间周期。
      说明 仅密钥类型为Aliyun_AES_256和Aliyun_SM4的对称密钥支持设置轮转周期。
      密钥材料来源 选择外部
    4. 仔细阅读参考文档后勾选我了解使用外部密钥材料的方法和意义,然后单击确定
  2. 获取导入密钥材料参数。
    导入密钥材料参数包括一个用于加密密钥材料的公钥,以及一个导入令牌。
    1. 在左侧导航栏,单击用户主密钥
    2. 单击目标密钥ID进入密钥管理页面,在密钥材料区域,单击获取导入参数
    3. 获取导入密钥材料的参数对话框,选择公钥类型加密算法,并单击下一步

      本文以公钥类型RSA_2048加密算法RSAES_OAEP_SHA_1为例进行介绍。

      说明
      • 公钥类型取值为RSA_2048时,您可以选择加密算法RSAES_PKCS1_V1_5(默认值)、RSAES_OAEP_SHA_1或RSAES_OAEP_SHA_256。
      • 公钥类型取值为EC_SM2时,您可以选择加密算法SM2PKE。
    4. 下载公钥和导入令牌,然后单击关闭
      下载公钥时需要选择公钥格式
      • 公钥格式选择der格式:下载的公钥文件后缀为.bin(例如:publickey_f240b730-7e3e-4bd7-877f-4fe22524****.bin)。
      • 公钥格式选择pem格式:下载的公钥文件后缀为.pem(例如:publickey_f240b730-7e3e-4bd7-877f-4fe22524****.pem)。
  3. 加密密钥材料。
    下载公钥和导入令牌后,您可以使用该公钥加密您的密钥材料。

    以使用OpenSSL加密密钥材料为例:使用的加密算法需要与获取导入对称密钥材料参数时指定的一致(RSAES_OAEP_SHA_1)。

    1. 创建一个密钥材料,使用OpenSSL产生一个32字节的随机数。
      openssl rand -out KeyMaterial.bin 32
    2. 根据指定的加密算法(RSAES_OAEP_SHA_1)加密密钥材料。
      执行下方示例代码时,您需要执行以下操作:
      • 将示例代码中的PublicKey.bin替换为获取导入密钥材料参数中下载的公钥文件的名称。
      • 示例代码以公钥格式为der格式为例,如果您下载公钥文件时选择了pem格式,需要将示例代码中的-keyform DER替换为-keyform PEM
      openssl rsautl -encrypt -in KeyMaterial.bin -oaep -inkey PublicKey.bin  -keyform DER  -pubin -out EncryptedKeyMaterial.bin
    3. 将加密后的密钥材料进行Base64编码,保存为文本文件。
      openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt
  4. 导入密钥材料。

    导入令牌与加密密钥材料的公钥具有绑定关系,一个令牌只能为其生成时指定的主密钥导入密钥材料。导入令牌的有效期为24小时,在有效期内可以重复使用,失效以后需要获取新的导入令牌和公钥。

    1. 在左侧导航栏,单击用户主密钥
    2. 单击目标密钥ID进入密钥管理页面,密钥材料区域,单击导入密钥材料
    3. 导入打包后的密钥材料对话框,上传打包后的密钥材料导入令牌
    4. 设置密钥材料过期时间,单击确定
      导入密钥材料成功后,密钥状态从待导入更新为启用中

通过ALIYUN CLI导入密钥材料

  1. 创建外部密钥。
    通过命令aliyun kms CreateKey调用CreateKey接口,指定参数OriginEXTERNAL
    aliyun kms CreateKey --Origin EXTERNAL --Description "External key"
  2. 获取导入密钥材料参数。
    通过命令aliyun kms GetParametersForImport调用GetParametersForImport接口获取导入密钥材料参数。
    aliyun kms GetParametersForImport --KeyId 1339cb7d-54d3-47e0-b595-c7d3dba8**** --WrappingAlgorithm RSAES_OAEP_SHA_1 --WrappingKeySpec RSA_2048
  3. 导入密钥材料。
    1. 使用公钥对密钥材料进行加密。

      公钥是一个RSA(2048比特)或者SM2公钥,使用的加密算法需要与获取导入密钥材料参数时指定的一致。由于API返回的公钥经过Base64编码,因此在使用时需要先进行Base64解码。目前KMS支持的加密算法有RSAES_OAEP_SHA_1、RSAES_OAEP_SHA_256、RSAES_PKCS1_V1_5和SM2PKE,其中SM2PKE仅部分地域支持。更多信息,请参见支持的地域

    2. 将加密后的密钥材料进行Base64编码。
    3. 通过命令aliyun kms ImportKeyMaterial调用ImportKeyMaterial接口,将编码后的密钥材料与导入令牌一起,作为ImportKeyMaterial接口的参数导入KMS。
      aliyun kms ImportKeyMaterial --KeyId 1339cb7d-54d3-47e0-b595-c7d3dba8**** --EncryptedKeyMaterial xxx --ImportToken xxxx --KeyMaterialExpireUnix xxxx

通过SDK导入密钥材料

代码示例:

  • JAVA SDK
    //使用最新KMS JAVA SDK。
    //KmsClient.java
    
    import com.aliyuncs.kms.model.v20160120.*;
    import com.aliyuncs.profile.DefaultProfile;
    
    //KMS API封装。
    public class KmsClient {
            DefaultAcsClient client;
    
            public KmsClient( String region_id, String ak, String secret) {
                    DefaultProfile profile = DefaultProfile.getProfile(region_id, ak, secret);
                    this.client = new DefaultAcsClient(profile);
            }
    
            public CreateKeyResponse createKey() throws Exception {
                    CreateKeyRequest request = new CreateKeyRequest();
                    request.setOrigin("EXTERNAL"); //创建外部密钥。
                    return this.client.getAcsResponse(request);
            }
            //... 省略,其余API类似。
    }
    //example.java
    import com.aliyuncs.kms.model.v20160120.*;
    import KmsClient
    import java.security.KeyFactory;
    import java.security.PublicKey;
    import java.security.spec.MGF1ParameterSpec;
    import javax.crypto.Cipher;
    import javax.crypto.spec.OAEPParameterSpec;
    import javax.crypto.spec.PSource.PSpecified;
    import java.security.spec.X509EncodedKeySpec;
    import java.util.Random;
    import javax.xml.bind.DatatypeConverter;
    
    public class CreateAndImportExample {
            public static void main(String[] args) {
                    String regionId = "cn-hangzhou";
            String accessKeyId = "*** Provide your AccessKeyId ***";
            String accessKeySecret = "*** Provide your AccessKeySecret ***";
            KmsClient kmsclient = new KmsClient(regionId,accessKeyId,accessKeySecret);
            //创建外部密钥。
            try {
                    CreateKeyResponse keyResponse = kmsclient.createKey();
                    String keyId = keyResponse.KeyMetadata.getKeyId();
                    //产生一个32字节随机数。
                    byte[] keyMaterial = new byte[32];
                    new Random().nextBytes(keyMaterial);
                    //获取导入密钥材料参数。
                    GetParametersForImportResponse paramResponse = kmsclient.getParametersForImport(keyId,"RSAES_OAEP_SHA_256");
                    String importToekn = paramResponse.getImportToken();
                    String encryptPublicKey = paramResponse.getPublicKey();
                    //Base64解码公钥。
                    byte[] publicKeyDer = DatatypeConverter.parseBase64Binary(encryptPublicKey);
                    //解析成RSA的公钥。
                    KeyFactory keyFact = KeyFactory.getInstance("RSA");
                    X509EncodedKeySpec spec = new X509EncodedKeySpec(publicKeyDer);
                    PublicKey publicKey = keyFact.generatePublic(spec);
                    //加密密钥材料。
                    Cipher oaepFromAlgo = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
                    String hashFunc = "SHA-256";
                    OAEPParameterSpec oaepParams = new OAEPParameterSpec(hashFunc, "MGF1", new MGF1ParameterSpec(hashFunc), PSpecified.DEFAULT);
                    oaepFromAlgo.init(Cipher.ENCRYPT_MODE, publicKey, oaepParams);
                    byte[] cipherDer = oaepFromAlgo.doFinal(keyMaterial);
                    //加密后的密钥材料,需要进行Base64编码。
                    String encryptedKeyMaterial = DatatypeConverter.printBase64Binary(cipherDer);
                    //导入密钥材料。
                    Long expireTimestamp = 1546272000L; //Unix时间戳,精确到秒,0表示永不过期。
                            kmsclient.importKeyMaterial(keyId,encryptedKeyMaterial, expireTimestamp);
            } catch(Exception e) {
                    //... 省略。
            }
            }
    }
  • Go SDK
    package main
    
    import (
        "crypto/rand"
        "crypto/rsa"
        "crypto/sha256"
        "crypto/x509"
        "encoding/base64"
        "fmt"
        "log"
        random "math/rand"
        "time"
    
        "github.com/aliyun/alibaba-cloud-sdk-go/services/kms"
    )
    
    //KMS CreateKey API封装。
    func kmsCreateKey(client *kms.Client) (string, error) {
        request := kms.CreateCreateKeyRequest()
        request.Scheme = "https"
        request.Origin = "EXTERNAL" //创建外部密钥。
        response, err := client.CreateKey(request)
        if err != nil {
            return "", fmt.Errorf("CreateKey error:%v", err)
        }
        return response.KeyMetadata.KeyId, nil
    }
    
    //KMS GetParametersForImport API封装。
    func kmsGetParametersForImport(client *kms.Client, keyId, wrappingKeySpec, wrappingAlgorithm string) (string, string, error) {
        request := kms.CreateGetParametersForImportRequest()
        request.Scheme = "https"
        request.KeyId = keyId
        request.WrappingKeySpec = wrappingKeySpec
        request.WrappingAlgorithm = wrappingAlgorithm
        response, err := client.GetParametersForImport(request)
        if err != nil {
            return "", "", fmt.Errorf("GetParametersForImport error:%v", err)
        }
        return response.PublicKey, response.ImportToken, nil
    }
    
    //KMS ImportKeyMaterial API封装。
    func kmsImportKeyMaterial(client *kms.Client, keyId, importToken, encryptedKeyMaterial string) error {
        request := kms.CreateImportKeyMaterialRequest()
        request.Scheme = "https"
        request.KeyId = keyId
        request.ImportToken = importToken
        request.EncryptedKeyMaterial = encryptedKeyMaterial
        _, err := client.ImportKeyMaterial(request)
        if err != nil {
            return fmt.Errorf("ImportKeyMaterial error:%v", err)
        }
        return nil
    }
    
    func randBytes(n int) []byte {
        var r = random.New(random.NewSource(time.Now().UnixNano()))
        bytes := make([]byte, n)
        for i := range bytes {
            bytes[i] = byte(r.Intn(256))
        }
        return bytes
    }
    
    func main() {
        accessKeyId := "*** Provide your AccessKeyId ***"
        accessKeySecret := "*** Provide your AccessKeySecret ***"
        regionId := "cn-hangzhou"
        client, err := kms.NewClientWithAccessKey(regionId, accessKeyId, accessKeySecret)
        if err != nil {
            log.Fatalf("NewClientWithAccessKey error:%+v\n", err)
        }
        //创建一个外部密钥。
        keyId, err := kmsCreateKey(client)
        if err != nil {
            log.Fatalf("kmsCreateKey error:%+v\n", err)
        }
        //以下示例代码产生一个32字节随机数。在实际应用中您需要通过用户的密钥管理系统生成密钥,并使用导入密钥材料参数中的公钥进行加密。
        keyMaterial := randBytes(32)
        //获取导入密钥材料参数。
        encryptPublicKey, importToken, err := kmsGetParametersForImport(client, keyId, "RSA_2048", "RSAES_OAEP_SHA_256")
        if err != nil {
            log.Fatalf("kmsGetParametersForImport error:%v\n", err)
        }
        //Base64解码公钥。
        publicKeyDer, err := base64.StdEncoding.DecodeString(encryptPublicKey)
        if err != nil {
            log.Fatalf("base64.StdEncoding.DecodeString error:%v\n", err)
        }
        //解析成RSA的公钥。
        publicKey, err := x509.ParsePKIXPublicKey(publicKeyDer)
        if err != nil {
            log.Fatalf("x509.ParsePKIXPublicKey error:%v\n", err)
        }
        //加密密钥材料。
        cipherDer, err := rsa.EncryptOAEP(sha256.New(), rand.Reader, publicKey.(*rsa.PublicKey), keyMaterial, nil)
        if err != nil {
            log.Fatalf("rsa.EncryptOAEP error:%v\n", err)
        }
        //加密后的密钥材料,需要进行Base64编码。
        encryptedKeyMaterial := base64.StdEncoding.EncodeToString(cipherDer)
        //导入密钥材料。
        err = kmsImportKeyMaterial(client, keyId, importToken, encryptedKeyMaterial)
        if err != nil {
            log.Fatalf("ImportKeyMaterial error:%v", err)
        }
    }