5.2 ALGO Guide

This chapter covers the files and the interface source of the N32H49x crypto algorithm library (ALGO), and the ALGO_DEMO example. The library is built on the hardware crypto algorithm accelerator (SAC); read it together with the “Crypto algorithm hardware accelerator (SAC)” chapter of the user manual for the supported algorithm list, key lengths, and working modes.

5.2.1 Related files

5.2.2 API reference

ALGO is a precompiled crypto algorithm library shipped with the SDK. It has no inc/src source files as a standard peripheral driver does; its interfaces are provided only as headers plus precompiled libraries, all under firmware/n32h49x_algo_lib/. The library comes in two toolchain sets: the Keil set has its headers under keil/inc/ and its libraries under keil/lib/ (n32h49x_common.lib, n32h49x_aes.lib, n32h49x_des.lib, n32h49x_hash.lib, n32h49x_rng.lib, and n32h49x_sm4.lib); the GCC set has its headers under gcc/inc/ and its libraries under gcc/lib/ (Common.a, AES.a, DES.a, HASH.a, RNG.a, and SM4.a). The two sets use the same header names, so a project only needs to add the matching inc/ to the header search path and the matching lib/ to the library path for the toolchain in use. The public entry points are grouped by header below:

• n32h49x_algo_common.h: RandomSort, Cpy_U8, Cpy_U32, XOR_U8, XOR_U32, SetZero_U8, SetZero_U32, ReverseBytesInWord_U32, Cmp_U32, and Cmp_U8, plus the return-value enumeration Cpy_OK, SetZero_OK, XOR_OK, Reverse_OK, Cmp_EQUAL, and Cmp_UNEQUAL.
• n32h49x_sm4.h: SM4_Init, SM4_Crypto, SM4_Close, and SM4_Version, plus the parameter structure SM4_PARM and the working-mode and direction macros SM4_ECB, SM4_CBC, SM4_ENC, and SM4_DEC.
• n32h49x_aes.h: AES_Init, AES_Crypto, AES_Close, and AES_Version, plus the parameter structure AES_PARM and the working-mode and direction macros AES_ECB, AES_CBC, AES_CTR, AES_ENC, and AES_DEC.
• n32h49x_des.h: DES_Init, DES_Crypto, DES_Close, and DES_Version, plus the parameter structure DES_PARM.
• n32h49x_hash.h: the streaming interfaces HASH_Init, HASH_Start, HASH_Update, HASH_Complete, and HASH_Close, the one-shot interfaces SM3_Hash, SHA1_Hash, SHA224_Hash, SHA256_Hash, and MD5_Hash, plus HASH_Version, the context structure HASH_CTX, and the algorithm descriptors HASH_ALG_SHA1, HASH_ALG_SHA224, HASH_ALG_SHA256, HASH_ALG_MD5, and HASH_ALG_SM3.
• n32h49x_rng.h: GetPseudoRand_U32, GetTrueRand_U32, and RNG_Version.

Every symmetric algorithm is used in three steps, initialize, crypto, and close: first XXX_Init fills the key, plaintext or ciphertext, and working mode into the parameter structure, then XXX_Crypto performs one encryption or decryption, and finally XXX_Close releases the resources; changing only the direction field of the same parameter structure reuses it for the opposite direction. A hash algorithm can either feed data in pieces through HASH_Init/HASH_Start/HASH_Update/HASH_Complete/HASH_Close, or use a one-shot interface such as SM3_Hash or MD5_Hash. The library version of each module is read through SM4_Version, AES_Version, DES_Version, HASH_Version, and RNG_Version.

5.2.3 Demo descriptions

This section covers the single ALGO example: ALGO_DEMO runs every algorithm in the library with a fixed set of test vectors and compares each result against the expected value.

5.2.3.1 ALGO_DEMO combined algorithm library demo

Example directory: projects/n32h49x_EVAL/examples/ALGO/ALGO_DEMO/

int main(void)
{
    log_init();
    log_info("-----------------------\nAlgorithm demo start.\n");
    /* config interface clock is 120MHz */
    RCC_ConfigPeriphClk(RCC_PERIPH_HCLK_DIV2);
    /* config work clock is 120MHz(must not exceed interface clock) */
    RCC_ConfigRngcClk(RCC_RNGCCLK_SYSCLK_DIV2);

    Cpy_U32(out, in1, 32);
    SM4_Parm.in = out;
    SM4_Parm.key = key1;
    SM4_Parm.out = out;
    SM4_Parm.inWordLen = 32;
    SM4_Parm.workingMode = SM4_ECB;
    SM4_Parm.EnDeMode = SM4_ENC;
    ret = SM4_Init(&SM4_Parm);

    if(ret != SM4_Crypto_OK)
    {
        flag1 = 0x5A5A5A5A;
    }
    else
    {

        if(Cmp_U32(SM4_ECB_EN, 32, out, 32))
        {
            flag1 = 0x5A5A5A5A;
        }
        else
        {
            flag1 = 0;
        }
    }

void TestRand(void)
{
    uint32_t buf[8];
    uint32_t seed[2] = {1, 2};
    uint8_t i;

    printf("\n");

    if (RNG_OK != GetPseudoRand_U32(buf, 8, seed))
    {
        printf("GetPseudoRand_U32 failed.\n");
    }
    else
    {
        printf("Pseudo random with seed 1,2 success: ");
        printf("\n");
    }

5.2.4 Notes and troubleshooting