V3 architecture Encryption Mode

Get the Encrypt Key (ekey)

Log in to the Alibaba Cloud Captcha console. In the upper-right area of the Overview page, copy the Encrypt Key (ekey).

Construct and encrypt the plaintext

1. Build the plaintext string.

Concatenate the three fields with & as the delimiter:

sceneId&timestamp&expireTime

Example plaintext:

sdewfwe&1712345678&3600

2. Encrypt with AES-256-CBC.

Apply AES encryption to the plaintext string using the following parameters:

The output is an encrypted byte array (CaptchaSceneIdEncrypted).

3. Concatenate and Base64-encode.

1. Concatenate the 16-byte IV and CaptchaSceneIdEncrypted in order, with no separator: IV + CaptchaSceneIdEncrypted.

2. Base64-encode the concatenated byte array using standard encoding without line feeds.

The resulting string is EncryptedSceneId.

Java code example

The following example generates an EncryptedSceneId using AES-256-CBC encryption.

import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.time.Instant;
import java.util.Base64;

public class SceneIdEncryptor {

    // The IV is a fixed length of 16 bytes (AES block size).
    private static final int IV_LENGTH_BYTES = 16;

    /**
     * Encrypts the sceneId to generate an EncryptedSceneId.
     *
     * @param sceneId        The CAPTCHA scenario identifier (formerly CaptchaAppid).
     * @param ekeyStr        The ekey from the console (used as the encryption key).
     * @param expireTimeSec  The validity period in seconds. Must be between 1 and 86400.
     * @return A Base64-encoded string: EncryptedSceneId (IV + encrypted data).
     * @throws Exception     Thrown for unsupported algorithms or other encryption errors.
     */
    public static String encryptSceneId(String sceneId, String ekeyStr, int expireTimeSec) throws Exception {
        if (expireTimeSec <= 0 || expireTimeSec > 86400) {
            throw new IllegalArgumentException("expireTimeSec must be between 1 and 86400 seconds.");
        }

        // Get the current timestamp in seconds.
        long timestamp = Instant.now().getEpochSecond();

        // Step 1: Decode the ekey into a 32-byte key.
        byte[] keyBytes = Base64.getDecoder().decode(ekeyStr);

        // Step 2: Build the plaintext and encrypt with AES-256-CBC.
        // Plaintext format: sceneId&timestamp&expireTime
        String plaintext = sceneId + "&" + timestamp + "&" + expireTimeSec;
        byte[] plaintextBytes = plaintext.getBytes(StandardCharsets.UTF_8);

        // Java uses PKCS5Padding, which is equivalent to PKCS7Padding for AES.
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");

        // Generate a cryptographically secure random 16-byte IV.
        SecureRandom random = new SecureRandom();
        byte[] iv = new byte[IV_LENGTH_BYTES];
        random.nextBytes(iv);
        IvParameterSpec ivSpec = new IvParameterSpec(iv);

        SecretKeySpec secretKeySpec = new SecretKeySpec(keyBytes, "AES");
        cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivSpec);

        byte[] encryptedBytes = cipher.doFinal(plaintextBytes);

        // Step 3: Concatenate IV + ciphertext, then Base64-encode.
        byte[] result = new byte[IV_LENGTH_BYTES + encryptedBytes.length];
        System.arraycopy(iv, 0, result, 0, IV_LENGTH_BYTES);
        System.arraycopy(encryptedBytes, 0, result, IV_LENGTH_BYTES, encryptedBytes.length);

        return Base64.getEncoder().encodeToString(result);
    }

    public static void main(String[] args) {
        try {
            String sceneId = "s123456789";       // Replace with your actual sceneId.
            String ekey = "<your-ekey>";         // Replace with the ekey from the console.
            int expireTimeSec = 3600;            // Set the desired validity period.

            String encryptedSceneId = encryptSceneId(sceneId, ekey, expireTimeSec);
            System.out.println("EncryptedSceneId: " + encryptedSceneId);
            // Output differs on each run because the IV is randomly generated.
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Replace the following placeholder before running the example:

EncryptedSceneId parameter

JavaScript code example

// Fetch the EncryptedSceneId from your backend.
const getEncryptedSceneId = async () => {
  const response = await fetch('/api/encrypt-scene-id', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
  });
  // Backend returns JSON: { "EncryptedSceneId": "..." }
  const { EncryptedSceneId } = await response.json();
  return EncryptedSceneId;
};

// Initialize the CAPTCHA with the encrypted scene ID.
const initCaptcha = async () => {
  const encryptedId = await getEncryptedSceneId();
  window.initAliyunCaptcha({
    SceneId: '<your-scene-id>',        // The scene ID from the Captcha console.
    EncryptedSceneId: encryptedId,
    // ... other initialization parameters
  });
};

initCaptcha();

Replace the following placeholder before using this example: