All Products
Search

This Product

    Key Management Service:Encrypt

    Document Center

    Key Management Service:Encrypt

    Last Updated:Jun 09, 2023

    Encrypts plaintext.

    Usage notes

    The following table describes encryption algorithms and padding modes for different types of keys.

    Key specifications

    Encryption algorithm

    Padding mode

    Description

    • Aliyun_AES_128

    • Aliyun_AES_192

    • Aliyun_AES_256

    AES_GCM (default value)

    N/A

    The Galois/Counter Mode (GCM) mode is used.

    AES_CBC

    • PKCS7_PADDING (default value)

    • NO_PADDING

    The cipher block chaining (CBC) mode is used. The padding mode can be configured.

    Note

    Only KMS instances of the hardware key management type support this encryption algorithm.

    AES_ECB

    The electronic codebook (ECB) mode is used. The padding mode can be configured.

    Note

    Only KMS instances of the hardware key management type support this encryption algorithm.

    • RSA_2048

    • RSA_3072

    • RSA_4096

    RSAES_OAEP_SHA_256 (default value)

    N/A

    RSAES-OAEP using SHA-256 and MGF1 with SHA-256

    • EC_P256

    • EC_P256K

    ECIES_DH_SHA_1_XOR_HMAC (default value)

    N/A

    Follow the following SEC 1: Elliptic Curve Cryptography, Version 2.0 standards:

    • Key agreement protocol: Elliptic-curve Diffie–Hellman (ECDH)

    • Key derivation algorithm: key derivation function 2 (KDF2) with SHA-1

    • MAC algorithm: HMAC-SHA-1

    • Symmetric encryption algorithm: XOR

    Request message definition

    message EncryptRequest {
     string KeyId = 1;
     bytes Plaintext = 2;
     string Algorithm = 3;
     bytes Aad = 4;
     bytes Iv = 5;    
     string PaddingMode = 6;
}

    Request parameters

    Parameter

    Type

    Required

    Example

    Description

    KeyId

    string

    Yes

    key-hzz62f1cb66fa42qo****

    The globally unique ID of the key. You can set the value to an alias that is bound to the key.

    Plaintext

    bytes

    Yes

    Binary data

    The plaintext that you want to encrypt.

    Algorithm

    string

    No

    AES_GCM

    The encryption algorithm. For more information about the valid values and default values, see the Encryption algorithm column in the table in the Usage notes section of this topic.

    Iv

    bytes

    No

    Binary data

    The initial vector that is used to encrypt data.

    This parameter takes effect only when Algorithm is set to AES_GCM or AES_CBC. If this parameter is not specified, KMS generates a random number.

    Aad

    binary

    No

    Binary data

    The authentication data when the GCM mode is used to encrypt a data key.

    If the key is a symmetric key and the value of Algorithm is set to AES_GCM or SM4_GCM, you can specify this parameter.

    Important

    If you specify this parameter, you must specify the parameter when you call the Decrypt operation.

    PaddingMode

    string

    No

    PKCS7_PADDING

    The padding mode.

    This parameter is required only when Algorithm is set to AES_CBC or AES_ECB. For more information, see the Padding mode column in the table in the Usage notes section of this topic.

    Valid values:

    • PKCS7_PADDING: PKCS#7 padding is used. This is the default value. The length of the data plaintext or ciphertext may not be an integer multiple of the cipher block size in bytes.

      If the input plaintext or ciphertext is L bytes in length, the system adds a padding string of K -(L mod K) bytes. Each padding string is K -(L mod K) bytes in length.

    • NO_PADDING: Padding strings are not added to plaintext. The length of the plaintext must be an integer multiple of the cipher block size.

    Response message definition

    message EncryptResponse {
     string KeyId = 1;
     bytes CiphertextBlob = 2;
     bytes Iv = 3;
     string RequestId = 4;
     string Algorithm = 5;
     string PaddingMode = 6;
}

    Response parameters

    Parameter

    Type

    Example

    Description

    Iv

    bytes

    Binary data

    The initial vector that is used to encrypt data.

    This parameter returns a valid value only when Algorithm is set to AES_GCM or AES_CBCIn other cases, an empty value is returned.

    CiphertextBlob

    bytes

    Binary data

    The ciphertext of the data that is encrypted by using a key.

    Note

    When the Elliptic Curve Integrated Encryption Scheme (ECIES) algorithm is used, the returned data ciphertext format follows the SEC 1: Elliptic Curve Cryptography, Version 2.0 standards.

    KeyId

    string

    key-hzz62f1cb66fa42qo****

    The globally unique ID of the key. If you set KeyId to an alias of the key, the ID of the key to which the alias is bound is returned.

    Algorithm

    string

    AES_GCM

    The encryption algorithm. If Algorithm is specified in the request parameters, the value of this parameter is the same as that in the request parameters. If Algorithm is not specified in the request parameters, KMS uses the default value.

    For more information about default algorithms, see the Encryption algorithm column in the table in the Usage notes section of this topic.

    PaddingMode

    string

    PKCS7_PADDING

    The padding mode. This parameter returns a valid value only when Algorithm is set to AES_CBC or AES_ECB. In other cases, an empty value is returned.

    RequestId

    string

    475f1620-b9d3-4d35-b5c6-3fbdd941423d

    The ID of the request, which is used to locate and troubleshoot issues.

    Error codes

    For more information about error codes, see Common error codes.