KMS handles cryptographic operations on your behalf, so your applications never manage key material or implement encryption logic directly. When you create a customer master key (CMK) without specifying the KeySpec parameter, KMS creates a symmetric key by default.
Symmetric encryption is the most widely used method for data encryption. KMS supports industry-standard symmetric key algorithms and protects your data with strong cryptography.
Supported algorithms
| Algorithm | Key length | Key type (KeySpec) | Encryption mode | Protection level |
|---|---|---|---|---|
| AES (Advanced Encryption Standard) | 256 bits | Aliyun_AES_256 | GCM (Galois/Counter Mode) | Software, Hardware Security Module (HSM) |
| SM4 | 128 bits | Aliyun_SM4 | GCM | HSM only |
KMS provides the SM4 algorithm through Managed HSM only. For details, see Managed HSM overview.
Encrypt and decrypt data
KMS uses a simplified API model that keeps key material out of your application code.
To encrypt data, call one of the following operations and specify a CMK ID or alias. KMS returns ciphertext — your application never handles the raw key material.
| Operation | Description |
|---|---|
Encrypt | Encrypts plaintext using a symmetric CMK |
ReEncrypt | Re-encrypts ciphertext under a different CMK without exposing the plaintext |
GenerateDataKey | Generates a random data key for local encryption and returns both the plaintext and encrypted copies |
GenerateDataKeyWithoutPlaintext | Generates a random data key for local encryption and returns only the encrypted copy |
To decrypt data, call Decrypt and pass the ciphertext. KMS automatically identifies the CMK used for encryption — you don't need to specify a CMK ID.
Encryption context
Symmetric keys in KMS use GCM mode, which supports additional authenticated data (AAD). KMS exposes AAD as EncryptionContext, a JSON string you can use in KMS API operations such as Encrypt, GenerateDataKey, and Decrypt.
EncryptionContext provides supplemental protection for the integrity of encrypted data. You can use it to customize authentication data.
For details on how to use EncryptionContext in API calls, see EncryptionContext.
Envelope encryption
For encrypting large volumes of data, use envelope encryption: KMS generates a data key, you use it to encrypt data locally, and then store the encrypted data key alongside the encrypted data.
Call GenerateDataKey to get both a plaintext data key (for immediate local use) and an encrypted copy of the data key (for storage). Call GenerateDataKeyWithoutPlaintext when you want to store the encrypted data key without handling the plaintext copy at all.
This two-level key hierarchy accelerates envelope encryption. For a step-by-step walkthrough, see Use envelope encryption to encrypt and decrypt local data.
Key rotation
Each symmetric CMK supports multiple key versions. KMS automatically rotates CMKs by generating new key versions, and you can customize the rotation schedule.
After a rotation, KMS uses the new key version for all subsequent Encrypt, GenerateDataKey, and GenerateDataKeyWithoutPlaintext calls. Ciphertext encrypted before the rotation remains decryptable — KMS automatically identifies the key version used during encryption and applies the correct key material during Decrypt. Re-encrypting existing data after a rotation is not required.
For configuration details, see Automatic key rotation.
Bring Your Own Key (BYOK)
BYOK lets you import external key material into a CMK instead of using KMS-generated material, which can help meet specific compliance or regulatory requirements.
To protect imported keys, import your key material into a CMK with an HSM protection level using Managed HSM. We recommend that you use Managed HSM to protect your keys. Keys stored in a managed HSM can be destroyed but their plaintext cannot be exported, which limits the attack surface.
For import instructions, see Import key material.
What's next
Managed HSM overview — learn how KMS integrates with hardware security modules
EncryptionContext — use additional authenticated data in API operations
Use envelope encryption to encrypt and decrypt local data — encrypt large datasets locally using data keys
Automatic key rotation — configure CMK rotation schedules
Import key material — use your own key material with BYOK