Key Management Service:Import key material

Step 1: Create an external CMK

1. Log in to the KMS console. In the top navigation bar, select the region where you want to create the CMK.

2. In the left-side navigation pane, choose Resource > Keys.

3. Click Create Key and configure the following parameters in the Create Key dialog box:

   Parameter	Description
   KMS Instance	The KMS instance to use. The default value is Default and cannot be changed.
   Key Type	The CMK type. Set to Aliyun_AES_256.
   Key Usage	Encrypt/Decrypt to encrypt or decrypt data, or Sign/Verify to sign data or verify a digital signature.
   Key Alias	An identifier for the CMK. Can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).
   Protection Level	Software for software-module protection, or Hsm to manage the CMK in a hardware security module (HSM).
   Description	An optional description of the CMK.
   Rotation Period	The automatic rotation interval. Configurable only when Key Type is Aliyun_AES_256 Note This setting applies only to symmetric keys of type Aliyun_AES_256. .
   Key Material Source	Select External.

4. Select I understand the implications of using the external key materials and click OK.

Step 2: Get import parameters

The import parameters consist of a wrapping public key (to encrypt your key material) and an import token (to authenticate the upload).

1. On the key list page, click the CMK's key ID to open the key management page. In the Key Material section, click Obtain Parameters for Import.

2. In the Obtain Parameters to Import Key Material dialog box, set Public Key Type to RSA_2048 and Encryption Algorithm to RSAES_OAEP_SHA_1, then click Next.

   For RSA_2048 keys, the supported wrapping algorithms are RSAES_PKCS1_V1_5, RSAES_OAEP_SHA_1, and RSAES_OAEP_SHA_256. The default is RSAES_PKCS1_V1_5.

   If you select RSA_2048 as the public key type, you can select RSAES_PKCS1_V1_5 (default), RSAES_OAEP_SHA_1, or RSAES_OAEP_SHA_256 as the encryption algorithm.

3. Select a Public Key Format:

   • DER Format — the downloaded file has a .bin extension (for example, publickey_f240b730-7e3e-4bd7-877f-4fe22524****.bin).

   • PEM Format — the downloaded file has a .pem extension (for example, publickey_f240b730-7e3e-4bd7-877f-4fe22524****.pem).

4. Download the public key and the import token, then click Close.

Step 3: Encrypt your key material

Use the wrapping public key you downloaded to encrypt your key material locally. The example below uses OpenSSL with the RSAES_OAEP_SHA_1 algorithm — use the same algorithm you selected in Step 2.

Generate 32 bytes of random key material:

openssl rand -out KeyMaterial.bin 32

Encrypt the key material with the wrapping public key:

# Replace PublicKey.bin with the filename of the public key you downloaded.
# If you selected PEM Format, replace -keyform DER with -keyform PEM.
openssl rsautl -encrypt -in KeyMaterial.bin -oaep \
  -inkey PublicKey.bin -keyform DER -pubin \
  -out EncryptedKeyMaterial.bin

Encode the encrypted key material in Base64:

openssl enc -e -base64 -A \
  -in EncryptedKeyMaterial.bin \
  -out EncryptedKeyMaterial_base64.txt

Step 4: Import the encrypted key material

1. In the left-side navigation pane, choose Resource > Keys.

2. Click the CMK's key ID to open the key management page. In the Key Material section, click Import Key Material.

3. In the Import Wrapped Key Material dialog box, upload the required files:

   • Wrapped Key Material: the EncryptedKeyMaterial_base64.txt file from Step 3.

   • Import Token: the import token file downloaded in Step 2.

4. Set Key Material Expired On to specify when KMS should automatically delete the key material, then click OK.

After the import completes, the CMK status changes from Pending Import to Enabled.

Step 1: Create an external CMK

aliyun kms CreateKey --Origin EXTERNAL --Description "External key"

Step 2: Get import parameters

Replace <key-id> with the key ID returned in Step 1.

aliyun kms GetParametersForImport \
  --KeyId <key-id> \
  --WrappingAlgorithm RSAES_OAEP_SHA_1 \
  --WrappingKeySpec RSA_2048

The response includes a Base64-encoded wrapping public key and an import token. Decode the public key from Base64 before using it to encrypt your key material.

The public key is a 2048-bit RSA public key. Use the same encryption algorithm that you specified when you retrieved the import parameters. The API returns the public key in Base64-encoded format. You must decode the public key before you use it. KMS supports RSAES_OAEP_SHA_1, RSAES_OAEP_SHA_256, and RSAES_PKCS1_V1_5.

Step 3: Encrypt and encode your key material

Use the decoded public key to encrypt your 256-bit AES key material with a supported wrapping algorithm (RSAES_OAEP_SHA_1, RSAES_OAEP_SHA_256, or RSAES_PKCS1_V1_5), then encode the encrypted result in Base64. You can use the OpenSSL commands from the console workflow in Step 3 above.

Step 4: Import the encrypted key material

Replace the placeholders with your actual values:

aliyun kms ImportKeyMaterial \
  --KeyId <key-id> \
  --EncryptedKeyMaterial <encrypted-key-material> \
  --ImportToken <import-token> \
  --KeyMaterialExpireUnix <expire-unix-timestamp>

Java

// KmsClient.java
import com.aliyuncs.kms.model.v20160120.*;
import com.aliyuncs.profile.DefaultProfile;

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"); // Create an external CMK.
        return this.client.getAcsResponse(request);
    }
    // Other operations follow the same pattern.
}

// 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 = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
        KmsClient kmsclient = new KmsClient(regionId, accessKeyId, accessKeySecret);

        try {
            // Step 1: Create an external CMK.
            CreateKeyResponse keyResponse = kmsclient.createKey();
            String keyId = keyResponse.KeyMetadata.getKeyId();

            // Step 2: Generate 32 bytes of random key material.
            byte[] keyMaterial = new byte[32];
            new Random().nextBytes(keyMaterial);

            // Step 3: Get import parameters.
            GetParametersForImportResponse paramResponse =
                kmsclient.getParametersForImport(keyId, "RSAES_OAEP_SHA_256");
            String importToken = paramResponse.getImportToken();
            String encryptPublicKey = paramResponse.getPublicKey();

            // Step 4: Decode the Base64-encoded wrapping public key.
            byte[] publicKeyDer = DatatypeConverter.parseBase64Binary(encryptPublicKey);
            KeyFactory keyFact = KeyFactory.getInstance("RSA");
            X509EncodedKeySpec spec = new X509EncodedKeySpec(publicKeyDer);
            PublicKey publicKey = keyFact.generatePublic(spec);

            // Step 5: Encrypt the key material using RSAES_OAEP_SHA_256.
            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);

            // Step 6: Encode the encrypted key material in Base64.
            String encryptedKeyMaterial = DatatypeConverter.printBase64Binary(cipherDer);

            // Step 7: Import the key material.
            // expireTimestamp: UNIX timestamp in seconds. Use 0 for no expiration.
            Long expireTimestamp = 1546272000L;
            kmsclient.importKeyMaterial(keyId, encryptedKeyMaterial, expireTimestamp);

        } catch (Exception e) {
            // Handle exceptions.
        }
    }
}

Go

package main

import (
    "crypto/rand"
    "crypto/rsa"
    "crypto/sha256"
    "crypto/x509"
    "encoding/base64"
    "fmt"
    "log"
    "os"
    random "math/rand"
    "time"

    "github.com/aliyun/alibaba-cloud-sdk-go/services/kms"
)

// kmsCreateKey creates an external CMK and returns its key ID.
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
}

// kmsGetParametersForImport returns the Base64-encoded wrapping public key and import token.
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
}

// kmsImportKeyMaterial imports Base64-encoded encrypted key material into the specified CMK.
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 {
    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 := os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
    accessKeySecret := os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
    regionId := "cn-hangzhou"

    client, err := kms.NewClientWithAccessKey(regionId, accessKeyId, accessKeySecret)
    if err != nil {
        log.Fatalf("NewClientWithAccessKey error: %+v", err)
    }

    // Step 1: Create an external CMK.
    keyId, err := kmsCreateKey(client)
    if err != nil {
        log.Fatalf("kmsCreateKey error: %+v", err)
    }

    // Step 2: Generate 32 bytes of random key material.
    // In production, generate key material in your own key management system.
    keyMaterial := randBytes(32)

    // Step 3: Get import parameters.
    encryptPublicKey, importToken, err := kmsGetParametersForImport(
        client, keyId, "RSA_2048", "RSAES_OAEP_SHA_256")
    if err != nil {
        log.Fatalf("kmsGetParametersForImport error: %v", err)
    }

    // Step 4: Decode the Base64-encoded wrapping public key.
    publicKeyDer, err := base64.StdEncoding.DecodeString(encryptPublicKey)
    if err != nil {
        log.Fatalf("base64 decode error: %v", err)
    }
    publicKey, err := x509.ParsePKIXPublicKey(publicKeyDer)
    if err != nil {
        log.Fatalf("x509.ParsePKIXPublicKey error: %v", err)
    }

    // Step 5: Encrypt the key material.
    cipherDer, err := rsa.EncryptOAEP(
        sha256.New(), rand.Reader, publicKey.(*rsa.PublicKey), keyMaterial, nil)
    if err != nil {
        log.Fatalf("rsa.EncryptOAEP error: %v", err)
    }

    // Step 6: Encode the encrypted key material in Base64.
    encryptedKeyMaterial := base64.StdEncoding.EncodeToString(cipherDer)

    // Step 7: Import the key material.
    if err := kmsImportKeyMaterial(client, keyId, importToken, encryptedKeyMaterial); err != nil {
        log.Fatalf("kmsImportKeyMaterial error: %v", err)
    }
}