Encryption/Decryption Application

This chapter describes the GK7206 encryption/decryption application example — sample_cipher. The application demonstrates the various capabilities of the chip's hardware encryption module, including AES symmetric encryption/decryption, RSA signing and encryption/decryption, HASH digests, random number generation, and efuse key management.

The application source code is located in the SDK directory sample/cipher/. It provides a complete demonstration of cryptographic functions and serves as a reference template for developing security-related applications.

1 Application Overview

1.1 Features

  • AES symmetric encryption/decryption: supports five working modes (ECB/CBC/CTR/CFB/OFB) and 128/256-bit keys
  • RSA asymmetric encryption: supports RSA signature generation and verification, public-key encryption and private-key decryption
  • HASH digest: supports SHA1/SHA256 and other hash algorithms
  • Random number generation: hardware random number generator (RNG)
  • efuse key management: supports reading the CA key from efuse for encryption/decryption
  • Multi-block batch processing: demonstrates batch encryption/decryption of multi-block data
  • Virtual address mode: supports encryption/decryption operations using virtual addresses

1.2 Technical Specifications

ParameterValue
Supported algorithmsAES, RSA, SHA1, SHA256, RNG
AES working modesECB, CBC, CTR, CFB, OFB
AES key lengths128-bit, 256-bit
AES data width128-bit
RSA key lengths1024/2048-bit
HASH algorithmsSHA1, SHA256
Memory footprintMinimal (no hardware dependency)
NPU usageNot used

1.3 Test Case List

indexNameTest commandExpected behavior (success)Possible failure cause
1CIPHER./sample_cipher 1AES CBC/CTR/ECB results match the plaintext → TEST_END_PASSEncryption/decryption or comparison failure
2CIPHER-MULTI./sample_cipher 2Multi-block batch AES matches for every block → PASSSame as above
3CIPHER-EFUSE./sample_cipher 3efuse CA key encryption/decryption matches → PASSCA key not burned into efuse (normal)
4HASH./sample_cipher 4Outputs fixed-length digests → PASS—
5RNG./sample_cipher 5Prints random bytes → PASS—
6RSA-SIGN./sample_cipher 6RSA signature + verification passes → PASSVerification failure
7RSA-ENC./sample_cipher 7Public-key encryption/private-key decryption matches → PASSComparison failure
8CIPHER-VIA./sample_cipher 8Virtual-address AES matches → PASSComparison failure

1.4 Directory Structure

sample/cipher/
├── Makefile              # Build script
└── sample_cipher.c       # Main program (contains all test cases)

2 Build and Deployment

2.1 Prerequisites

Before building this application, make sure the following preparations have been completed:

  1. SDK environment is set up: follow SDK Compilation to set up the cross-compilation toolchain and SDK configuration
  2. The SDK has been fully built once: the application depends on the SDK's common libraries and header files

Tips

This application has no hardware dependency — no sensor or other peripherals are required, and it can be tested at any time.

2.2 Build the Application

# Enter the sample directory
cd <SDK_PATH>/sample

# Build the cipher sample
make -C cipher clean && make -C cipher

Or build from the top level:

make -C sample all

After a successful build, the executable sample_cipher is generated in the sample/cipher/ directory.

2.3 Deploy to the Board

# Transfer to the development board via SCP
scp sample/cipher/sample_cipher root@<board IP>:/tmp/

# Or download via TFTP
tftp -g -r sample_cipher <board IP>

Info

Since this application is very small, it can run directly from /tmp without an SD card.

2.4 Run the Application

# Add execute permission
chmod +x /tmp/sample_cipher

# Run the test cases (recommended order)
./sample_cipher 4    # HASH test
./sample_cipher 5    # RNG test
./sample_cipher 1    # Basic AES test
./sample_cipher 7    # RSA encryption test
./sample_cipher 6    # RSA signature test
./sample_cipher 2    # Multi-block batch test
./sample_cipher 8    # Virtual address test
./sample_cipher 3    # efuse test (may fail)

2.5 Expected Output

Index 1: CIPHER (multi-mode AES encryption/decryption test)

~~~~~~~~~~~~~~~~~~~~~ run sample_cipher ~~~~~~~~~~~~~~~~~~~
chnid 0x2818049
ECB-AES-256-ORI:
0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11
0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11
ECB-AES-256-ENC:
0x86 0x3a 0xe9 0x1f 0xd4 0xcf 0x51 0x13 0x2d 0xc3 0xe4 0xed 0xf0 0x9d 0xbc 0x6e
0x86 0x3a 0xe9 0x1f 0xd4 0xcf 0x51 0x13 0x2d 0xc3 0xe4 0xed 0xf0 0x9d 0xbc 0x6e
ECB-AES-256-DEC:
0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11
0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11 0x11
****************** ecb_aes256 test PASS ******************
chnid 0x2818049
CBC-AES-256-ORI:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
CBC-AES-256-ENC:
0xe0 0xfa 0xab 0x42 0xd5 0xa5 0x5c 0x18 0xb0 0x13 0x1f 0x47 0x6c 0xa5 0xd0 0x0a
CBC-AES-256-DEC:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
****************** cbc_aes256 test PASS ******************
chnid 0x2818049
CBC-AES-192-ORI:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
CBC-AES-192-ENC:
0x69 0x25 0x8f 0xc2 0x8d 0x58 0x8b 0x84 0x67 0x87 0x76 0x02 0x2f 0x9c 0x1c 0x91
CBC-AES-192-DEC:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
****************** cbc_aes192 test PASS ******************
chnid 0x2818049
CBC-AES-128-ORI:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
CBC-AES-128-ENC:
0x76 0x49 0xab 0xac 0x81 0x19 0xb2 0x46 0xce 0xe9 0x8e 0x9b 0x12 0xe9 0x19 0x7d
CBC-AES-128-DEC:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
****************** cbc_aes128 test PASS ******************
CFB-AES-128-ORI:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
0xae 0x2d 0x8a 0x57 0x1e 0x03 0xac 0x9c 0x9e 0xb7 0x6f 0xac 0x45 0xaf 0x8e 0x51
CFB-AES-128-ENC:
0x3b 0x3f 0xd9 0x2e 0xb7 0x2d 0xad 0x20 0x33 0x34 0x49 0xf8 0xe8 0x3c 0xfb 0x4a
0xc8 0xa6 0x45 0x37 0xa0 0xb3 0xa9 0x3f 0xcd 0xe3 0xcd 0xad 0x9f 0x1c 0xe5 0x8b
CFB-AES-128-DEC
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
0xae 0x2d 0x8a 0x57 0x1e 0x03 0xac 0x9c 0x9e 0xb7 0x6f 0xac 0x45 0xaf 0x8e 0x51
****************** cfb_aes128 test PASS ******************
CTR-AES-128-ORI:
0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f
0x10 0x11 0x12 0x13 0x14 0x15 0x16 0x17 0x18 0x19 0x1a 0x1b 0x1c 0x1d 0x1e 0x1f
CTR-AES-128-ENC:
0x51 0x04 0xa1 0x06 0x16 0x8a 0x72 0xd9 0x79 0x0d 0x41 0xee 0x8e 0xda 0xd3 0x88
0xeb 0x2e 0x1e 0xfc 0x46 0xda 0x57 0xc8 0xfc 0xe6 0x30 0xdf 0x91 0x41 0xbe 0x28
CTR-AES-128-DEC
0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f
0x10 0x11 0x12 0x13 0x14 0x15 0x16 0x17 0x18 0x19 0x1a 0x1b 0x1c 0x1d 0x1e 0x1f
****************** ctr_aes128 test PASS ******************

################# FUNCTION 1 RUN SUCCESS #################

Success indicator: ################# FUNCTION 1 RUN SUCCESS #################, with each sub-test showing ****************** test PASS ******************.

Fixed and variable parts

  • Fixed parts: all AES encryption/decryption results (for the fixed test data and keys)
  • Variable parts: chnid (channel ID, may differ on each run)

Index 2: CIPHER-MULTI (multi-block batch test)

~~~~~~~~~~~~~~~~~~~~~ run sample_multicipher ~~~~~~~~~~~~~~~~~~~
GOLD
0x76 0x49 0xab 0xac 0x81 0x19 0xb2 0x46 0xce 0xe9 0x8e 0x9b 0x12 0xe9 0x19 0x7d
0x4c 0xbb 0xc8 0x58 0x75 0x6b 0x35 0x81 0x25 0x52 0x9e 0x96 0x98 0xa3 0x8f 0x44
****************** multicipher_aes_cbc_enc test PASS ******************
****************** multicipher_aes_cbc_dec test PASS ******************

################# FUNCTION 2 RUN SUCCESS #################

Success indicator: ################# FUNCTION 2 RUN SUCCESS #################, with the encryption/decryption results matching the GOLD reference values.

Fixed and variable parts

  • Fixed parts: all encryption/decryption results (for the fixed test data and keys)
  • Variable parts: none (the output of this test is entirely fixed)

Index 3: CIPHER-EFUSE (efuse CA key test)

~~~~~~~~~~~~~~~~~~~~~ run sample_cipher_efuse ~~~~~~~~~~~~~~~~~~~
clear text:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
encrypted text:
0xf0 0xb7 0x6a 0x0c 0x16 0x06 0xd4 0xde 0x79 0xcb 0x5c 0x66 0xd3 0x51 0x0c 0xab
before decrypt:
0xf0 0xb7 0x6a 0x0c 0x16 0x06 0xd4 0xde 0x79 0xcb 0x5c 0x66 0xd3 0x51 0x0c 0xab
decrypted text:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
****************** sample_cipher_efuse_vir test PASS ******************
clear text:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
encrypted text:
0xf0 0xb7 0x6a 0x0c 0x16 0x06 0xd4 0xde 0x79 0xcb 0x5c 0x66 0xd3 0x51 0x0c 0xab
before decrypt:
0xf0 0xb7 0x6a 0x0c 0x16 0x06 0xd4 0xde 0x79 0xcb 0x5c 0x66 0xd3 0x51 0x0c 0xab
decrypted text:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
****************** sample_cipher_efuse_phy test PASS ******************

################# FUNCTION 3 RUN SUCCESS #################

Success indicator: ################# FUNCTION 3 RUN SUCCESS #################, with the decrypted plaintext matching the original plaintext. Failure case: if the CA key has not been burned into efuse, the test fails with an error — this is normal.

Fixed and variable parts

  • Fixed parts: the plaintext, ciphertext, and encryption results (for the fixed test data and keys)
  • Variable parts: none (the output of this test is entirely fixed)

Index 4: HASH (hash digest test)

~~~~~~~~~~~~~~~~~~~~~ run sample_hash ~~~~~~~~~~~~~~~~~~~
****************** sha1 test PASS ******************
****************** sha256 test PASS ******************
hmac-Sha1 result:
0xac 0xd4 0x9a 0xdd 0x87 0xba 0x3b 0xe2 0x93 0xdc 0x39 0xc1 0x72 0x06 0xbf 0xab
0x8b 0xde 0x59 0xe7
hmac-Sha1 result:
0xfc 0x66 0xa4 0xcb 0x9e 0xf4 0xe6 0x88 0x19 0xf3 0xe9 0x40 0xae 0xf0 0x7a 0x59
0x5b 0x72 0x7a 0x0f
hmac-Sha1 result:
0x73 0xd3 0x86 0xe3 0x0e 0x42 0x1a 0x27 0xc7 0x53 0xfa 0x45 0xa4 0x78 0x31 0x34
0xc0 0x2a 0x71 0x2b
****************** hmac_sha1 test PASS ******************
hmac-Sha256 result:
0xf1 0x2b 0xdb 0x85 0xbd 0x31 0xaa 0x46 0x84 0x3d 0xca 0x9b 0xde 0x9c 0xbf 0x63
0xba 0x00 0x55 0x02 0x60 0xdb 0xbf 0xc4 0xad 0x03 0xc4 0xdf 0x98 0x82 0x2c 0x57
hmac-Sha256 result:
0xef 0x03 0xc8 0xb5 0x2f 0xfc 0x02 0x3b 0x7a 0x99 0x69 0xf7 0x0e 0xf6 0x03 0x22
0x90 0x2b 0x47 0x98 0x1f 0x9b 0x8f 0xaf 0xfe 0x43 0xe5 0x61 0x33 0x8a 0xe3 0x44
hmac-Sha256 result:
0x4b 0x3b 0xf5 0xa2 0x57 0xb6 0xf9 0x10 0x35 0x9e 0xf4 0x8d 0x8a 0x3b 0xe1 0x6e
0x0a 0x09 0x3a 0x96 0x53 0x51 0x72 0xbd 0x6f 0x82 0x0d 0xbc 0xfb 0x1d 0x9b 0x00
****************** hmac_sha256 test PASS ******************
****************** sha224 test PASS ******************

################# FUNCTION 4 RUN SUCCESS #################

Success indicator: ################# FUNCTION 4 RUN SUCCESS #################, with each hash test showing ****************** test PASS ******************.

Fixed and variable parts

  • Fixed parts: all SHA1/SHA256/SHA224 hash results and HMAC results (for the fixed test data and keys)
  • Variable parts: none (the output of this test is entirely fixed)

Index 5: RNG (random number generation test)

~~~~~~~~~~~~~~~~~~~~~ run sample_rng ~~~~~~~~~~~~~~~~~~~
Random number: 0aeec5a2
Random number: 659363bd
Random number: 1ef83f38
Random number: fdd0708f
Random number: 8765b4e3
Random number: 25ac881e
Random number: 07cee115
Random number: 1c75e1b0
Random number: 88631d1a
Random number: c0e9987e

################# FUNCTION 5 RUN SUCCESS #################

Success indicator: ################# FUNCTION 5 RUN SUCCESS #################, with 10 random numbers generated.

Fixed and variable parts

  • Fixed parts: the output format (10 random numbers)
  • Variable parts: the value of each random number (different on every run)

Index 6: RSA-SIGN (RSA signature test)

~~~~~~~~~~~~~~~~~~~~~ run sample_rsa_sign ~~~~~~~~~~~~~~~~~~~
****************** rsa_sign_verify test PASS ******************
****************** rsa_sign_verify test PASS ******************
****************** rsa_sign_verify_crt test PASS ******************
****************** rsa_sign_verify_crt test PASS ******************

################# FUNCTION 6 RUN SUCCESS #################

Success indicator: ################# FUNCTION 6 RUN SUCCESS #################, with each signature verification test showing ****************** test PASS ******************. Failure case: if FAILED is displayed instead of PASS, the signature verification failed.

Fixed and variable parts

  • Fixed parts: the number of tests and their pass status (for the fixed test keys)
  • Variable parts: none (the output of this test is entirely fixed)

Index 7: RSA-ENC (RSA encryption test)

~~~~~~~~~~~~~~~~~~~~~ run sample_rsa_enc ~~~~~~~~~~~~~~~~~~~
****************** pkcs_crt_dec test PASS ******************
****************** pkcs_pub_enc test PASS ******************
****************** pkcs_pub_enc test PASS ******************
****************** pkcs_pub_enc test PASS ******************
****************** pkcs_pub_enc test PASS ******************
****************** pkcs_pub_enc test PASS ******************
****************** pkcs_pub_enc test PASS ******************
****************** pkcs_pri_enc test PASS ******************

################# FUNCTION 7 RUN SUCCESS #################

Success indicator: ################# FUNCTION 7 RUN SUCCESS #################, with each encryption/decryption test showing ****************** test PASS ******************. Failure case: if FAILED is displayed instead of PASS, the encrypted/decrypted data did not match.

Fixed and variable parts

  • Fixed parts: the number of tests and their pass status (for the fixed test keys)
  • Variable parts: none (the output of this test is entirely fixed)

Index 8: CIPHER-VIA (virtual address test)

~~~~~~~~~~~~~~~~~~~~~ run sample_cipher_via ~~~~~~~~~~~~~~~~~~~
chnid 0x2818049
CBC-AES-128-ORI:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
CBC-AES-128-ENC:
0x76 0x49 0xab 0xac 0x81 0x19 0xb2 0x46 0xce 0xe9 0x8e 0x9b 0x12 0xe9 0x19 0x7d
CBC-AES-128-DEC:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
****************** cbc_aes128 test PASS ******************
CFB-AES-128-ORI:
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
0xae 0x2d 0x8a 0x57 0x1e 0x03 0xac 0x9c 0x9e 0xb7 0x6f 0xac 0x45 0xaf 0x8e 0x51
CFB-AES-128-ENC:
0x3b 0x3f 0xd9 0x2e 0xb7 0x2d 0xad 0x20 0x33 0x34 0x49 0xf8 0xe8 0x3c 0xfb 0x4a
0xc8 0xa6 0x45 0x37 0xa0 0xb3 0xa9 0x3f 0xcd 0xe3 0xcd 0xad 0x9f 0x1c 0xe5 0x8b
CFB-AES-128-DEC
0x6b 0xc1 0xbe 0xe2 0x2e 0x40 0x9f 0x96 0xe9 0x3d 0x7e 0x11 0x73 0x93 0x17 0x2a
0xae 0x2d 0x8a 0x57 0x1e 0x03 0xac 0x9c 0x9e 0xb7 0x6f 0xac 0x45 0xaf 0x8e 0x51
****************** cfb_aes128 test PASS ******************
CTR-AES-128-ORI:
0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f
0x10 0x11 0x12 0x13 0x14 0x15 0x16 0x17 0x18 0x19 0x1a 0x1b 0x1c 0x1d 0x1e 0x1f
CTR-AES-128-ENC:
0x51 0x04 0xa1 0x06 0x16 0x8a 0x72 0xd9 0x79 0x0d 0x41 0xee 0x8e 0xda 0xd3 0x88
0xeb 0x2e 0x1e 0xfc 0x46 0xda 0x57 0xc8 0xfc 0xe6 0x30 0xdf 0x91 0x41 0xbe 0x28
CTR-AES-128-DEC
0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f
0x10 0x11 0x12 0x13 0x14 0x15 0x16 0x17 0x18 0x19 0x1a 0x1b 0x1c 0x1d 0x1e 0x1f
****************** ctr_aes128 test PASS ******************

################# FUNCTION 8 RUN SUCCESS #################

Success indicator: ################# FUNCTION 8 RUN SUCCESS #################, with virtual-address-mode encryption/decryption succeeding. Failure case: if FAILED is displayed instead of PASS, the virtual-address-mode data did not match.

Fixed and variable parts

  • Fixed parts: all AES encryption/decryption results (for the fixed test data and keys)
  • Variable parts: chnid (channel ID, may differ on each run)

3 Internal Execution Logic in Detail

3.1 Application Architecture

This application uses a simple command-line argument model: the argument to main() selects the test case:

int main(int argc, char *argv[])
{
    int index = 0;

    if (argc < 2) {
        usage();  // Print usage
        return -1;
    }

    index = atoi(argv[1]);

    switch(index) {
        case 1: sample_cipher_test();       break;  // Basic AES test
        case 2: sample_cipher_mult_test();  break;  // Multi-block batch test
        case 3: sample_cipher_ca_test();    break;  // efuse CA key test
        case 4: sample_hash_test();         break;  // HASH test
        case 5: sample_rng_test();          break;  // RNG test
        case 6: sample_rsa_sign_test();     break;  // RSA signature test
        case 7: sample_rsa_enc_test();      break;  // RSA encryption test
        case 8: sample_cipher_via_test();   break;  // Virtual address test
        default: usage(); break;
    }

    return 0;
}

3.2 AES Encryption/Decryption Flow

The AES test (index 1) demonstrates encryption and decryption in the ECB/CBC/CTR working modes:

// Step 1: Initialize the cipher module
xmedia_cipher_init();

// Step 2: Create a cipher channel
xmedia_cipher_create_handle(&chnid);

// Step 3: Configure cipher parameters
xmedia_cipher_ctrl ctrl;
ctrl.alg = XMEDIA_CIPHER_ALG_AES;              // Algorithm: AES
ctrl.mode = XMEDIA_CIPHER_WORK_MODE_CBC;      // Working mode: CBC
ctrl.aes_ctrl.bit_width = XMEDIA_CIPHER_BIT_WIDTH_128BIT;
ctrl.aes_ctrl.key_len = XMEDIA_CIPHER_KEY_AES_128BIT;
memcpy(ctrl.aes_ctrl.key, aes_key, 16);        // Key
memcpy(ctrl.aes_ctrl.iv, aes_iv, 16);         // IV (required by CBC/CTR)

xmedia_cipher_config_handle(chnid, &ctrl);

// Step 4: Allocate input/output buffers (MMZ physically contiguous memory)
input_phy  = xmedia_mmz_alloc(NULL, "CIPHER_BufIn",  data_len);
input_vir  = xmedia_mmz_map(input_phy, data_len, cached);
output_phy = xmedia_mmz_alloc(NULL, "CIPHER_BufOut", data_len);
output_vir = xmedia_mmz_map(output_phy, data_len, cached);

// Step 5: Encrypt
memcpy(input_vir, aes_src, data_len);
xmedia_cipher_encrypt(chnid, input_phy, output_phy, data_len);

// Step 6: Decrypt
xmedia_cipher_decrypt(chnid, output_phy, input_phy, data_len);

// Step 7: Verify
if (memcmp(input_vir, aes_src, data_len) == 0) {
    printf("memcmp decrypt and src OK!\n");
}

// Step 8: Clean up
xmedia_mmz_unmap(input_vir);
xmedia_mmz_free(input_phy);
xmedia_cipher_destroy_handle(chnid);
xmedia_cipher_exit();

3.3 RSA Signature and Verification Flow

The RSA signature test (index 6) demonstrates the complete flow of signing with an RSA private key and verifying with the public key:

// Step 1: Initialize the cipher module
xmedia_cipher_init();

// Step 2: Create a cipher channel
xmedia_cipher_create_handle(&chnid);

// Step 3: Configure RSA parameters
xmedia_cipher_ctrl ctrl;
ctrl.alg = XMEDIA_CIPHER_ALG_RSA;
ctrl.rsa_ctrl.rsa_len = XMEDIA_CIPHER_RSA_2048;  // 2048-bit RSA
// ... configure public/private key ...

xmedia_cipher_config_handle(chnid, &ctrl);

// Step 4: Sign (private key)
xmedia_cipher_sign(chnid, digest_phy, signature_phy);

// Step 5: Verify (public key)
xmedia_cipher_verify(chnid, digest_phy, signature_phy);

3.4 efuse CA Key Test

The efuse CA key test (index 3) demonstrates reading the CA key from the chip's efuse for encryption/decryption:

// Configure cipher to use the efuse CA key
ctrl.key_by_ca = XMEDIA_TRUE;  // Use the CA key stored in efuse

xmedia_cipher_config_handle(chnid, &ctrl);

// The subsequent encryption/decryption flow is the same as ordinary AES
xmedia_cipher_encrypt(chnid, input_phy, output_phy, data_len);

Warning

If the CA key has not been burned into efuse, this test fails — this is normal.

3.5 HASH Digest and Random Number Generation

The HASH test (index 4) and RNG test (index 5) are relatively simple:

// HASH digest
xmedia_cipher_init();
xmedia_cipher_create_handle(&chnid);

ctrl.alg = XMEDIA_CIPHER_ALG_SHA256;
xmedia_cipher_config_handle(chnid, &ctrl);

xmedia_cipher_hash(chnid, input_phy, input_len, output_phy);

// RNG random number generation
xmedia_cipher_init();
xmedia_cipher_create_handle(&chnid);

xmedia_cipher_rng(chnid, output_phy, output_len);

3.6 Multi-Block Batch Processing

The multi-block batch test (index 2) demonstrates processing multiple blocks of data in a single call:

// Allocate a large buffer
data_len = 32 * 10;  // 10 blocks, 32 bytes each
input_phy  = xmedia_mmz_alloc(NULL, "CIPHER_BufIn",  data_len);
output_phy = xmedia_mmz_alloc(NULL, "CIPHER_BufOut", data_len);

// Encrypt/decrypt in one call
xmedia_cipher_encrypt(chnid, input_phy, output_phy, data_len);
xmedia_cipher_decrypt(chnid, output_phy, input_phy, data_len);

3.7 Virtual Address Mode

The virtual address test (index 8) demonstrates encryption/decryption using virtual addresses:

// Use virtual addresses instead of physical addresses
xmedia_cipher_encrypt_via(chnid, input_vir, output_vir, data_len);
xmedia_cipher_decrypt_via(chnid, output_vir, input_vir, data_len);

Tips

The virtual address mode is more convenient, but may involve cache coherency issues.

4 Key Programming Points

4.1 MMZ Memory Management

Encryption/decryption operations require physically contiguous memory (MMZ); ordinary malloc() cannot be used:

// Allocate physical memory
xmedia_ulong phy = xmedia_mmz_alloc(NULL, "name", size);

// Map it into the virtual address space
void *vir = xmedia_mmz_map(phy, size, cached);

// When finished
xmedia_mmz_unmap(vir);
xmedia_mmz_free(phy);

4.2 Using the IV

CBC, CTR, CFB, and OFB modes require an IV (initialization vector); ECB does not:

if (mode != XMEDIA_CIPHER_WORK_MODE_ECB) {
    memcpy(ctrl.aes_ctrl.iv, aes_iv, AES_IV_LENGTH);
}

4.3 Key Length and Data Width

ctrl.aes_ctrl.bit_width = XMEDIA_CIPHER_BIT_WIDTH_128BIT;  // Fixed at 128-bit
ctrl.aes_ctrl.key_len = XMEDIA_CIPHER_KEY_AES_128BIT;      // 128-bit key
// or XMEDIA_CIPHER_KEY_AES_256BIT                         // 256-bit key

4.4 Error Handling

Check the return value of every API call:

ret = xmedia_cipher_init();
if (XMEDIA_SUCCESS != ret) {
    printf("cipher init failed!\n");
    return ret;
}

5 Troubleshooting

ProblemPossible causeSolution
Test 3 failsCA key not burned into efuseNormal; does not affect other functions
Encryption mismatchIV not set correctlyCBC/CTR modes require the correct IV
MMZ allocation failureInsufficient system memoryFree memory held by other processes
RSA verification failurePublic/private key mismatchCheck that the key configuration is correct

6 References