If a request contains sensitive information or is sent over the public network, encrypt the input field in the request body. This prevents data from being intercepted or tampered with during transmission.
Encryption and decryption process
This process uses a hybrid encryption mechanism. Data is encrypted with the AES symmetric algorithm. The AES key is securely transmitted using RSA asymmetric encryption.
-
Prepare the request data.
-
Generate an AES symmetric key. AES is an efficient symmetric encryption algorithm used to encrypt the content of the
inputfield.Note:
inputfield is the core object in a request to a Large Language Model (LLM) application. It includes required parameters such as the prompt (prompt) and optional parameters such as the conversation history (messages). -
Use a key pair to encrypt the
input. -
Encrypt the AES key with an RSA public key. Use the hosted RSA public key from the Alibaba Cloud Model Studio platform to encrypt the AES key. This ensures the secure transmission of the AES key.
Note: RSA is an asymmetric encryption algorithm that includes a public key and a private key. The public key is used to encrypt data, and the private key is used to decrypt data.
-
Generate an AES symmetric key. AES is an efficient symmetric encryption algorithm used to encrypt the content of the
-
Send the request. When you call the Alibaba Cloud Model Studio platform, pass the encrypted
inputcontent and the key information. The key information is encapsulated in theX-DashScope-EncryptionKeyrequest header. -
Alibaba Cloud Model Studio processes the request.
- The data is encrypted throughout the Alibaba Cloud Model Studio inference pipeline.
- The Alibaba Cloud Model Studio platform decrypts the data during vector recall and model inference.
- The generated answer is encrypted with the same AES key, and the encrypted inference result is returned.
- Process the response. The client receives the response, decrypts the inference result with the AES key, and obtains the plaintext answer.
Prerequisites
Activate the Alibaba Cloud Model Studio service and obtain an API key. For more information, see Obtain an API Key.
Important: Configure the API key as an environment variable to reduce the risk of leakage. For more information, see Set the API key as an environment variable. You can also configure the API key in your code, but this increases the risk of leakage.
DashScope SDK call (automatic encryption, out-of-the-box)
The DashScope SDK handles encryption and decryption. To make encrypted calls, simply enable the encryption feature. You do not need to write your own encryption and decryption code.
Constraints and limits
- Custom keys are not supported. To use a custom key, see HTTP call (manual key management).
- Only Java and Python are supported. For other programming languages, see HTTP call (manual key management).
Procedure
- Install the latest version of the DashScope SDK.
-
Enable the encryption feature.
- Java SDK
- Python SDK
SetenableEncrypttotrueto enable the encryption feature. - Call the model. Send the request in the same way as a normal call. The SDK automatically handles encryption and decryption.
Complete SDK code examples
Important: The sample code is for reference only. Do not use it directly in a production environment.
Note: For more information about request parameters, see Qwen API documentation.
- Java SDK
- Python SDK
Request exampleResponse exampleThe DashScope SDK automatically decrypts the response. The returned content is plaintext and does not require manual decryption.
HTTP calls (manual key management)
Note: This encrypted call method is a security feature provided by Alibaba Cloud Model Studio. This encryption process applies only to DashScope Endpoints. OpenAI-compatible Endpoints, such as the Chat Completions API and Responses API, do not support this encryption mechanism.
Differences from normal calls
Encrypted calls require three extra steps compared to normal calls. For more information, see Integration process.
-
Add the
X-DashScope-EncryptionKeyrequest header. The value of theX-DashScope-EncryptionKeyrequest header is a JSON string. The following table describes the parameters.public_key_id: The public key ID.encrypt_key: The AES key encrypted with an RSA public key.iv: The initialization vector (IV).
-
Encrypt the content of the
inputrequest parameter. The following table shows the difference between the request data for a normal call and an encrypted call. - Decrypt the response data.
Integration process
The integration process consists of three stages: prepare the request data, build and send the encrypted request, and decrypt the response data.
1. Prepare the request data
-
Generate an AES key
- Algorithm: AES
-
Key specifications:
-
Length: 128 bits (16 bytes), 192 bits (24 bytes), or 256 bits (32 bytes)
Note: Longer keys provide higher security but also increase computational overhead. A 256 bit key offers the highest security and is suitable for protecting highly sensitive data, such as core financial data.
- Randomness: Generate the key using a cryptographically secure random source.
- Uniqueness: The key must be unique for each request and must not be reused.
-
Length: 128 bits (16 bytes), 192 bits (24 bytes), or 256 bits (32 bytes)
- Example code:
- Generate an initialization vector (IV) Generate a random initialization vector for Galois/Counter Mode (GCM) encryption. Use a secure random number generator to create a 12 byte random byte sequence. Then, Base64-encode this byte sequence to obtain the IV. Example code:
-
Encrypt the input data
- Algorithm: AES-GCM (authentication tag length: 128 bits)
- Parameters:
-
Processing flow:
-
Serialize the input value into a JSON string. This is the
{"messages":[......]}part shown in the figure.
-
Perform AES-GCM encryption on the serialized
input. -
Convert the encryption result to a string. This string will be used as the value for the
inputfield when you build and send the request.
-
Serialize the input value into a JSON string. This is the
- Example code:
-
Encrypt the AES key with an RSA public key
- Algorithm: RSA
-
Processing flow:
- Base64-encode the original AES key generated in step 1.
-
Encrypt the encoded AES key using the RSA public key. For more information about how to obtain the
public_keyandpublic_key_idfrom Alibaba Cloud Model Studio, see Obtain an RSA public key.You do not need to fetch the RSA public key for every request. You can cache the public key on the client side to reduce the number of API calls in high queries-per-second (QPS) scenarios. A cache duration of 1 minute is recommended.The public key does not change under normal circumstances. It is rotated only in case of a security incident. Therefore, manage the public key cache using the following policy:- Normal scenario: Use the cached public key. After the cache expires, automatically fetch the latest public key.
- Error scenario: If the error code
BadRequest.IllegalInputis returned with the error messageThe input parameter can not be decoded., the public key is invalid. In this case, you must immediately fetch the latest public key to minimize service disruption.
- Base64-encode the encryption result.
- Example code:
2. Build and send the request
Add the X-DashScope-EncryptionKey request header and replace the original input value with the encrypted input. Then, send the request in the same way as a normal call.
The following list describes the parameters for the X-DashScope-EncryptionKey request header. The values for these parameters are generated during the data preparation stage.
public_key_id: The public key ID.encrypt_key: The AES key encrypted with an RSA public key.iv: The initialization vector (IV).

3. Decrypt the response data
- Algorithm: AES-GCM
- Parameters:
-
Processing flow:
- Use AES-GCM to decrypt the content of the
outputfield. - Return the plaintext result.
- Use AES-GCM to decrypt the content of the
- Example code:
Complete HTTP example code
This section provides complete Java and Python code examples. These examples combine all the steps from the integration process into a runnable program. If you use another programming language, you can follow the integration process to implement the logic.
Tip: If you need an implementation in another programming language, you can use an LLM to convert the following code to your target language.
Important: The example code is for reference only. Do not use it directly in a production environment.
Note: For more information about request parameters, see the Qwen API documentation.Request example
FAQ
Q: Why do I receive the error "Invalid AES key Length: 294 bytes" during code execution?
A: AES keys must be 128 bits (16 bytes), 192 bits (24 bytes), or 256 bits (32 bytes) long. Check your key length setting.
Q: Do the OpenAI-compatible Endpoints for the Chat Completions API and Responses API support encrypted inference?
A: No, they do not. The encryption flow described in this topic applies only to the DashScope SDK and HTTP Endpoints.
Q: Do I need to fetch the RSA public key for each request?
A: No, you do not. You should cache the RSA public key on the client for a recommended duration of 1 minute. The public key does not change under normal circumstances. It is only rotated in an emergency, such as a security incident. If a request returns the error code BadRequest.IllegalInput (The input parameter can not be decoded.), the public key is invalid. Immediately fetch the latest public key.