Key Management Service:Import key material for an asymmetric key

Features

In regulated industries, compliance audits often require you to prove exclusive custody of cryptographic key material. When you create an asymmetric key with an external key material source, Key Management Service (KMS) does not generate key material — you supply and import your own. This is known as Bring Your Own Key (BYOK).

Usage notes

• After the first import of key material, the key is bound to that key material and no longer supports importing other key material.

• You can import the same key material multiple times to a KMS key as needed, but you cannot import different key material to one KMS key.

• If the key material of a key expires or is deleted, you can import the same key material again to make the key available again. Key material cannot be exported after import. Store the key material properly.

Scope

A KMS instance is purchased and enabled. For more information, see Purchase and enable a KMS instance.

Import key material in the KMS console

Step 2: Download a wrapping public key and an import token

The parameters for importing key material include a wrapping public key and an import token. The wrapping public key is used to encrypt the key material and protect it during the import process. The import token is used to authorize the import.

1. Find the target key, click Actions in the Details column. On the key details page, in the Key Material section, click Obtain Parameters for Import.

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

   Key management type	Key specifications	Wrapping public key type	Encryption algorithm
   Software-protected key	RSA_2048 RSA_3072 EC_P256 EC_P256K	RSA_2048	RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD
   Hardware-protected key	RSA_2048 RSA_3072 RSA_4096 EC_P256 EC_P256K	RSA_2048	RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD

   • RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD: For the detailed encryption process, see Example: Use OpenSSL to generate key material for the RSA_2048 algorithm.

3. Download the wrapping public key and the import token, and store them securely.

   • Public Key Format:

     • DER Format: The downloaded file is named WrappingPublicKey**.bin by default.

     • PEM Format: The downloaded file is named WrappingPublicKey**.pem by default.

   • Import Token: The downloaded file is named ImportToken***.txt by default.

     Important

     • An import token is valid for 24 hours and can be reused within this period. After it expires, you must obtain a new import token and public key.

     • The wrapping public key and the import token must be used as a pair. You cannot use a wrapping public key from one download with an import token from another.

Step 3: Encrypt the key material using the wrapping public key

Step 4: Import key material

On the key details page, click Import Key Material. In the Import Wrapped Key Material dialog box, complete the configurations and click OK.

After the key material is successfully imported, the key status changes from Pending Import to Enabling.

Import key material using Alibaba Cloud SDK

You can use Alibaba Cloud SDK to create RSA and ECC keys in KMS and import key material. The following Java code example demonstrates the process.

 <dependency>
 <groupId>com.aliyun</groupId>
 <artifactId>kms20160120</artifactId>
 <version>1.4.0</version>
 </dependency>
 <dependency>
 <groupId>com.aliyun</groupId>
 <artifactId>tea</artifactId>
 <version>1.3.2</version>
 </dependency>

package com.aliyun;

import java.security.InvalidAlgorithmParameterException;
import java.security.KeyFactory;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.Provider;
import java.security.PublicKey;
import java.security.SecureRandom;
import java.security.interfaces.ECPrivateKey;
import java.security.spec.ECGenParameterSpec;
import java.security.spec.MGF1ParameterSpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Random;

import javax.crypto.Cipher;
import javax.crypto.spec.OAEPParameterSpec;
import javax.crypto.spec.PSource.PSpecified;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;

import com.aliyun.kms20160120.models.*;
import com.aliyun.kms20160120.Client;
import org.bouncycastle.asn1.gm.GMNamedCurves;
import org.bouncycastle.asn1.x9.X9ECParameters;
import org.bouncycastle.crypto.engines.SM2Engine;
import org.bouncycastle.crypto.params.ECDomainParameters;
import org.bouncycastle.crypto.params.ECPublicKeyParameters;
import org.bouncycastle.crypto.params.ParametersWithRandom;
import org.bouncycastle.jcajce.provider.asymmetric.ec.BCECPublicKey;
import org.bouncycastle.jce.provider.BouncyCastleProvider;

public class BringYourOwnAsymmetricKeySample {
    private final static String dedicatedKmsInstanceId = "<yourKmsInstanceId>";
    // The public endpoint of KMS.
    private final static String endpoint = "kms.<regionId>.aliyuncs.com";
    private final Client kmsClient;
    private final String SM2PKE_SM4_ECB = "SM2PKE_SM4_ECB";
    private final String RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD = "RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD";
    private static Provider BC = new BouncyCastleProvider();
    private static X9ECParameters x9ECParameters = GMNamedCurves.getByName("sm2p256v1");
    private static ECDomainParameters ecDomainParameters = new ECDomainParameters(x9ECParameters.getCurve(), x9ECParameters.getG(), x9ECParameters.getN());

    static {
        java.security.Security.addProvider(new org.bouncycastle.jce.provider.BouncyCastleProvider());
    }

    public static void main(String[] args) throws Exception {
        // Initialize the KMS SDK.
        Client client = BringYourOwnAsymmetricKeySample.createClient();
        BringYourOwnAsymmetricKeySample sample = new BringYourOwnAsymmetricKeySample(client);

        // Create and import an external key of the EC_SM2 type.
        sample.doByok("EC_SM2", "EC_SM2", sample.SM2PKE_SM4_ECB, "SM4");
        // Create and import an external key of the EC_P256 type.
        sample.doByok("EC_P256", "RSA_2048", sample.RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD, "AES_256");
        // Create and import an external key of the RSA type.
        sample.doByok("RSA_2048", "RSA_2048", sample.RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD, "AES_256");
    }

    /**
     * <b>description</b> :
     * <p>Initialize the client using credentials.</p>
     *
     * @return Client
     * @throws Exception
     */
    public static Client createClient() throws Exception {
        // We recommend that you use the more secure credential-based initialization without hardcoding AccessKey pairs. For more information, see: https://www.alibabacloud.com/help/document_detail/378657.html.
        com.aliyun.credentials.Client credential = new com.aliyun.credentials.Client();
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                .setCredential(credential);
        // For the endpoint, see https://api.aliyun.com/product/Kms.
        config.endpoint = endpoint;
        return new Client(config);
    }

    public BringYourOwnAsymmetricKeySample(Client kmsClient) {
        this.kmsClient = kmsClient;
    }

    public void doByok(String targetKeySpec, String wrappingKeySpec, String wrappingAlgorithm, String ephemeralKeySpec) {
        try {
            // Create an external ECC key.
            CreateKeyResponseBody.CreateKeyResponseBodyKeyMetadata keyMetadata = this.createExternalKeyInDkms(dedicatedKmsInstanceId, targetKeySpec, "SIGN/VERIFY");
            String keyId = keyMetadata.getKeyId();
            // Obtain the parameters for importing key material.
            GetParametersForImportResponse parametersForImportResponse = this.getParametersForImport(keyId, wrappingKeySpec,
                    wrappingAlgorithm);
            String importToken = parametersForImportResponse.body.getImportToken();
            String publicKeyBase64 = parametersForImportResponse.body.getPublicKey();
            // Generate the ephemeral symmetric key.
            byte[] ephemeralSymmetricKeyPlaintext = this.generateEphemeralSymmetricKey(ephemeralKeySpec);
            // Generate the target asymmetric key.
            byte[] targetAsymmetricKeyPlaintext = this.generateTargetAsymmetricKey(targetKeySpec);
            // Use the import wrapping key public key to encrypt the ephemeral symmetric key.
            byte[] ephemeralSymmetricKeyCipher = this.encryptEphemeralSymmetricKey(publicKeyBase64,
                    wrappingAlgorithm, ephemeralSymmetricKeyPlaintext);
            // Use the ephemeral symmetric key to encrypt the target asymmetric key.
            byte[] targetAsymmetricKeyCipher = this.encryptTargetAsymmetricKey(ephemeralSymmetricKeyPlaintext, targetAsymmetricKeyPlaintext,
                    wrappingAlgorithm);
            // Generate the key material.
            byte[] encryptedKeyMaterial = new byte[ephemeralSymmetricKeyCipher.length + targetAsymmetricKeyCipher.length];
            System.arraycopy(ephemeralSymmetricKeyCipher, 0, encryptedKeyMaterial, 0, ephemeralSymmetricKeyCipher.length);
            System.arraycopy(targetAsymmetricKeyCipher, 0, encryptedKeyMaterial, ephemeralSymmetricKeyCipher.length, targetAsymmetricKeyCipher.length);
            String encryptedKeyMaterialBase64 = DatatypeConverter.printBase64Binary(encryptedKeyMaterial);
            // Import the key material to KMS.
            this.importKeyMaterial(keyId, encryptedKeyMaterialBase64, importToken, 0L);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private GetParametersForImportResponse getParametersForImport(String keyId, String keySpec, String algorithm) throws Exception {
        GetParametersForImportRequest request = new GetParametersForImportRequest();
        request.setKeyId(keyId);
        request.setWrappingKeySpec(keySpec);
        request.setWrappingAlgorithm(algorithm);
        return this.kmsClient.getParametersForImport(request);
    }

    private CreateKeyResponseBody.CreateKeyResponseBodyKeyMetadata createExternalKeyInDkms(String dedicatedKmsInstance, String keySpec, String keyUsage) throws Exception {
        CreateKeyRequest request = new CreateKeyRequest();
        // Create an external key.
        request.setOrigin("EXTERNAL");
        request.setDKMSInstanceId(dedicatedKmsInstance);
        request.setKeySpec(keySpec);
        request.setKeyUsage(keyUsage);
        return kmsClient.createKey(request).body.keyMetadata;
    }

    private byte[] generateEphemeralSymmetricKey(String ephemeralSymmetricKeySpec) throws Exception {
        // If the ephemeral symmetric key is AES_256, the length is 32 bytes.
        int ephemeralSymmetricKeyLength = 32;
        if ("SM4".equals(ephemeralSymmetricKeySpec)) {
            ephemeralSymmetricKeyLength = 16;
        }
        byte[] key = new byte[ephemeralSymmetricKeyLength];
        new Random().nextBytes(key);
        return key;
    }

    private byte[] generateTargetAsymmetricKey(String keySpec) throws Exception {
        PrivateKey privateKey = null;
        // Generate an SM2 key and obtain the D value of the private key.
        if ("EC_SM2".equals(keySpec)) {
            ECPrivateKey ecPrivateKey = (ECPrivateKey) generateSm2KeyPair().getPrivate();
            byte[] dT = ecPrivateKey.getS().toByteArray();
            byte[] d = new byte[32];
            if (dT.length == 33) {
                System.arraycopy(dT, 1, d, 0, 32);
            }
            return dT.length == 32 ? dT : d;
        }

        // Generate an RSA or ECC private key.
        if (keySpec.contains("RSA")) {
            String[] keySpecAttrs = keySpec.split("_");
            int bits = Integer.parseInt(keySpecAttrs[keySpecAttrs.length - 1]);
            privateKey = generateRsaKeyPair(bits).getPrivate();
        } else if (keySpec.contains("EC")) {
            if (keySpec.contains("P256K")) {
                // Generate an EC_P256K private key.
                privateKey = generateEccKeyPair("secp256k1").getPrivate();
            } else {
                // Generate an EC_P256 private key.
                privateKey = generateEccKeyPair("secp256r1").getPrivate();
            }
        }
        if (privateKey != null) {
            // Return the private key in PKCS#8 format.
            return privateKey.getEncoded();
        }
        return null;
    }

    private KeyPair generateEccKeyPair(String keySpec)
            throws NoSuchAlgorithmException, InvalidAlgorithmParameterException {
        ECGenParameterSpec ecSpec = new ECGenParameterSpec(keySpec);
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("EC");
        keyPairGenerator.initialize(ecSpec, new SecureRandom());
        return keyPairGenerator.generateKeyPair();
    }

    private KeyPair generateRsaKeyPair(int length) throws Exception {
        KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
        keyGen.initialize(length);
        return keyGen.genKeyPair();
    }

    private KeyPair generateSm2KeyPair() throws Exception {
        KeyPairGenerator keyGen = KeyPairGenerator.getInstance("EC", "BC");
        keyGen.initialize(new ECGenParameterSpec("sm2p256v1"), new SecureRandom());
        return keyGen.genKeyPair();
    }


    private byte[] encryptEphemeralSymmetricKey(String publicKeyBase64, String wrappingAlgorithm, byte[] ephemeralSymmetricKeyPlaintext) throws Exception {
        PublicKey publickey = null;
        byte[] enchbk = null;
        if ("RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD".equals(wrappingAlgorithm)) {
            publickey = parseDerPublicKey("RSA", publicKeyBase64);
            Cipher oaepFromAlgo = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
            OAEPParameterSpec oaepParams = new OAEPParameterSpec("SHA-256", "MGF1", new MGF1ParameterSpec("SHA-256"), PSpecified.DEFAULT);
            oaepFromAlgo.init(Cipher.ENCRYPT_MODE, publickey, oaepParams);
            enchbk = oaepFromAlgo.doFinal(ephemeralSymmetricKeyPlaintext);
        } else if ("SM2PKE_SM4_ECB".equals(wrappingAlgorithm)) {
            publickey = parseDerPublicKey("EC", publicKeyBase64, BC);
            BCECPublicKey localECPublicKey = (BCECPublicKey) publickey;
            ECPublicKeyParameters ecPublicKeyParameters = new ECPublicKeyParameters(localECPublicKey.getQ(), ecDomainParameters);
            SM2Engine sm2Engine = new SM2Engine(SM2Engine.Mode.C1C3C2);
            sm2Engine.init(true, new ParametersWithRandom(ecPublicKeyParameters));
            enchbk = sm2Engine.processBlock(ephemeralSymmetricKeyPlaintext, 0, ephemeralSymmetricKeyPlaintext.length);

        } else {
            throw new Exception("Invalid wrappingAlgorithm");
        }
        return enchbk;
    }

    private PublicKey parseDerPublicKey(String keyType, String pemKey) throws Exception {
        byte[] derKey = DatatypeConverter.parseBase64Binary(pemKey);
        X509EncodedKeySpec keySpec = new X509EncodedKeySpec(derKey);
        return KeyFactory.getInstance(keyType).generatePublic(keySpec);
    }

    private PublicKey parseDerPublicKey(String keyType, String pemKey, Provider provider) throws Exception {
        byte[] derKey = DatatypeConverter.parseBase64Binary(pemKey);
        X509EncodedKeySpec keySpec = new X509EncodedKeySpec(derKey);
        return KeyFactory.getInstance(keyType, provider).generatePublic(keySpec);
    }

    private byte[] encryptTargetAsymmetricKey(byte[] secretKey, byte[] targetAsymmetricKeyPlaintext, String wrappingAlgorithm)
            throws Exception {
        if ("RSAES_OAEP_SHA_256_AES_256_ECB_PKCS7_PAD".equals(wrappingAlgorithm)) {
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey, "AES");
            Cipher cipher = Cipher.getInstance("AES/ECB/PKCS7Padding", "BC");
            cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec);
            return cipher.doFinal(targetAsymmetricKeyPlaintext);
        } else if ("SM2PKE_SM4_ECB".equals(wrappingAlgorithm)) {
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey, "SM4");
            Cipher cipher = Cipher.getInstance("SM4/ECB/NoPadding");
            cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec);
            return cipher.doFinal(targetAsymmetricKeyPlaintext);
        }

        throw new Exception("Invalid WrappingAlgorithm");
    }

    private void importKeyMaterial(
            String keyId,
            String material,
            String token,
            Long expire
    ) throws Exception {
        ImportKeyMaterialRequest req = newImportKeyMaterialRequest(
                keyId, material, token, expire);
        this.kmsClient.importKeyMaterial(req);
    }

    private ImportKeyMaterialRequest newImportKeyMaterialRequest(
            String keyId,
            String material,
            String token,
            Long expire
    ) {
        ImportKeyMaterialRequest request = new ImportKeyMaterialRequest();
        request.setEncryptedKeyMaterial(material);
        request.setImportToken(token);
        request.setKeyId(keyId);
        request.setKeyMaterialExpireUnix(expire);
        return request;
    }
}
            

FAQ

• Is key material deletion supported?

  Yes, it is supported.

  Important

  After the imported key material expires or is deleted, the key becomes unavailable. You must import the same key material again to restore the key.

  • Delete key material directly

    • Console: On the key details page, in the Key Material section, click Delete Key Material.

    • API: Call the DeleteKeyMaterial operation to delete the key material. This operation does not delete your key.

  • Automatic deletion by KMS after expiration

    Set an expiration time when importing key material. After that time, KMS deletes the expired key material.

• How do I reimport the same key material?

  After the key material expires or is deleted, you can import the same key material again so the key can continue to be used.

  1. Delete the expired key material.

     On the key details page, click the Key Material tab, and click Delete Key Material.

  2. Download the wrapping public key and import token again. For more information, see Step 2: Download a wrapping public key and an import token.

     Note

     The key wrapping process does not affect the content of the key material. You can use a different wrapping public key and wrapping algorithm to import the same key material.

  3. Encrypt the key material using the wrapping public key. For more information, see Step 3: Encrypt the key material using the wrapping public key.

     Note

     The key material must be the same as the previously expired one.

  4. Use the import token to import the encrypted key material. For more information, see Step 4: Import key material.

• How do I determine whether the key material is imported externally or generated by KMS?

  • Method 1: Check in the KMS console.

    On the Keys page, click the Customer Master Keys tab, select a Instance ID, find the target key, click Actions in the Details column, and check the Key Material Origin on the details page.

  • Method 2: Check by calling the DescribeKey operation.

    If the value of Origin is EXTERNAL, the key material is imported externally. If the value of Origin is Aliyun_KMS, the key material is generated by KMS.

• How do I rotate a key that uses external key material?

  • For a software-protected symmetric key with imported external key material, only immediate manual rotation is supported. Automatic periodic rotation is not supported. For more information, see Bring Your Own Keys (BYOKs) with imported key material..

  • For a software-protected asymmetric key with imported external key material, rotation is not supported.

  • For a hardware-protected key (symmetric or asymmetric) with imported external key material, rotation is not supported.

References

• Understanding KMS keys

• Key specifications for symmetric and asymmetric encryption

• Import key material into a symmetric key