3.19. sample_crypto Usage Instructions

3.19.1. Function Overview

sample_crypto demonstrates the usage of common security operation interfaces through multiple operation examples. Below is a description of each example’s functionality:

sample_cipher: Implements symmetric encryption and decryption operations
- Supports configuration of encryption algorithms, including AES / DES / SM4
- Supports configuration of key sizes: 64 / 128 / 192 / 256 bits
sample_digest: Implements hash digest computation
- Supports configuration of hash algorithms, including MD5 / SHA1 / SHA2 / SHA3
sample_hmac: Implements message authentication code (HMAC) computation
- Supports configuration of hash algorithms, including MD5 / SHA1 / SHA2 / SHA3
- Supports arbitrary key length configuration
sample_rsa: Implements asymmetric encryption and decryption operations
- Supports generating RSA key pairs
- Supports configuring RSA key length: 1024 / 2048 / 3072 / 4096 / 8192 bits
- Uses public key for encryption and private key for decryption

3.19.1.1. Software Architecture Description

3.19.1.2. Code Location and Directory Structure

Code location: app/samples/platform_samples/sample_crypto
Directory structure

sample_crypto
├── sample_cipher
│   ├── Makefile
│   └── sample_cipher.c
├── sample_digest
│   ├── Makefile
│   └── sample_digest.c
├── sample_hmac
│   ├── Makefile
│   └── sample_hmac.c
└── sample_rsa
    ├── Makefile
    └── sample_rsa.c

3.19.1.3. API Process Description

3.19.2. Compilation & Deployment

3.19.2.1. Compilation

Execute the make command in each subdirectory of sample_crypto to complete compilation. Taking sample_cipher as an example:

cd /app/samples/platform_samples/sample_cryto/sample_cipher
make

For detailed program compilation methods, please refer to the Compilation Methods section.

3.19.2.2. Deployment

After flashing the system software image, all sample programs of sample_crypto are located at /app/platform_samples/sample_crypto on the device.

3.19.3. Execution

3.19.3.1. sample_cipher Execution

sample_cipher Execution Method

Directly run the program ./sample_cipher -h to get help information

sample_cipher Parameter Options Description

Usage: sample_cipher [Options] [value]
Options:
  -s <cipher name>      Select Cipher Name
  -k <key size>         Key Size [64/128/192/256]
  -h                    Show this help message
Available Cipher:
        Cipher Name     Recommend Key Size
         1. aes_ecb     128/192/256-bit
         2. aes_cbc     128/192/256-bit
         3. aes_cfb     128/192/256-bit
         4. aes_ofb     128/192/256-bit
         5. aes_ctr     128/192/256-bit
         6. sm4_ecb     128/-bit
         7. sm4_cbc     128/-bit
         8. sm4_cfb     128/-bit
         9. sm4_ofb     128/-bit
         10. sm4_ctr    128/-bit
         11. des_ecb    64/-bit
         12. des_cbc    64/-bit
         13. des_ofb    64/-bit

Options:

-s <cipher name>: Select encryption algorithm.
-k <key size>: Set key size.
-h: Display help message.

Supported key sizes for each encryption algorithm are as follows:

Encryption Algorithm	64bit	128bit	192bit	256bit
aes_ecb	×	✔	✔	✔
aes_cbc	×	✔	✔	✔
aes_cfb	×	✔	✔	✔
aes_ofb	×	✔	✔	✔
aes_ctr	×	✔	✔	✔
sm4_ecb	×	✔	×	×
sm4_cbc	×	✔	×	×
sm4_cfb	×	✔	×	×
sm4_ofb	×	✔	×	×
sm4_ctr	×	✔	×	×
des_ecb	✔	×	×	×
des_cbc	✔	×	×	×
des_ofb	✔	×	×	×

sample_cipher Execution Results

Taking the AES algorithm as an example, using ECB mode with a 256-bit key length, perform encryption and decryption on the text string Test message for encryption, Cipher[aes_ecb], KeySize[256].
Execute the following command:

./sample_cipher -s aes_ecb -k 256

Output:

Encrypted text (hex): ffbc5dcf79a3e0bf45fb3f974983c3258f800e9eb65f78749710d35d9494dabc083f1481350d73fce81f5d513bb5e7da00c12f646cc2c3ae1a9604915ddad2ae
Decrypted text: Test message for encryption, Cipher[aes_ecb], KeySize[256]

It can be confirmed that the decrypted string matches the original text.

3.19.3.2. sample_digest Execution

sample_digest Execution Method

Directly run the program ./sample_digest -h to get help information

sample_digest Parameter Options Description

Usage: sample_digest [Options] [value]
Options:
  -s <hash name>      Select Hash Name
  -h                  Show this help message
Available Hash:
         1. md5
         2. sha1
         3. sha224
         4. sha256
         5. sha384
         6. sha512
         7. sha3-224
         8. sha3-256
         9. sha3-384
         10. sha3-512

Options:

-s <hash name>: Select hash algorithm.
-h: Display help message.

Hash algorithms supported by sample_digest include:

MD5
SHA1
SHA-2: SHA-224 / 256 / 384 / 512
SHA-3: SHA3-224 / 256 / 384 / 512

sample_digest Execution Results

Taking SHA256 as an example, compute the hash of the text string Test message for digest [sha256].
Execute the following command:

./sample_digest -s sha256

Output:

plain_text:
Test message for digest [sha256]
[sha256] hash is:
ded9cd0a4ac6e11c38ab3ceb3cff7cff5d18a3bbc37b9fc578f96b3ee63df4b4

The hash value computed by sample_digest is ded9cd0a4ac6e11c38ab3ceb3cff7cff5d18a3bbc37b9fc578f96b3ee63df4b4.

Compare with the system command sha256sum:

echo -n "Test message for digest [sha256]" | sha256sum
ded9cd0a4ac6e11c38ab3ceb3cff7cff5d18a3bbc37b9fc578f96b3ee63df4b4

It can be confirmed that the hash value computed by sample_digest matches the system command output.

3.19.3.3. sample_hmac Execution

sample_hmac Execution Method

Directly run the program ./sample_hmac -h to get help information

sample_hmac Parameter Options Description

Usage: sample_hmac [Options] [value]
Options:
  -s <hash name>  Select hash Name
  -k <key size>   Key Size
  -h              Show this help message

Options:

-s <hash name>: Select hash algorithm.
-k <key size>: Configure key length.
-h: Display help message.

Note: HMAC keys can be of any length, but it is recommended that the key length matches the selected hash algorithm.

Hash algorithms supported by sample_hmac and their recommended key lengths are as follows:

Available Hash:
        Hash Name        Recommend Key Size
         1. md5          128-bits
         2. sha1         160-bits
         3. sha224       224-bits
         4. sha256       256-bits
         5. sha384       384-bits
         6. sha512       512-bits
         7. sha3-224     224-bits
         8. sha3-256     256-bits
         9. sha3-384     384-bits
         10. sha3-512    512-bits

sample_hmac Execution Results

Using SHA256 with a 256-bit key length, compute the HMAC of the text string Test message for Hmac: Hash[sha256] Key[256].
Execute the following command:

./sample_hmac -s sha256 -k 256

Output:

plain_text:
Test message for Hmac: Hash[sha256] Key[256]

Key is:
37099184641824357814880241575040

HMAC is:
8c5b046e961c4dfaea07c60293ebd36b9cea95cfba7e31c02c583a5cdb2303e2

The HMAC computed by sample_hmac is 8c5b046e961c4dfaea07c60293ebd36b9cea95cfba7e31c02c583a5cdb2303e2.

Use the openssl command with the same KEY and message to verify the HMAC:

Note: sample_hmac generates a random number based on key size as the key each time; copy the key string as the openssl command parameter

echo -n "Test message for Hmac: Hash[sha256] Key[256]" \
| openssl dgst -sha256 -hmac "37099184641824357814880241575040"

Output: 8c5b046e961c4dfaea07c60293ebd36b9cea95cfba7e31c02c583a5cdb2303e2

It can be confirmed that the HMAC value computed by sample_hmac matches the system command output.

3.19.3.4. sample_rsa Execution

sample_rsa Execution Method

Directly run the program ./sample_cipher -h to get help information

sample_rsa Parameter Options Description

Usage: sample_rsa [Options] [value]
Options:
  -k <key size>     Key Size [1024/2048/3072/4096/8192]
  -h                Show this help message

Options:

-k <key size>: Set key length, supports 1024 / 2048 / 3072 / 4096 / 8192
-h: Display help message.

sample_rsa Execution Results

Using RSA-2048 as an example, encrypt the text string The test message for RSA-2048 encryption! with the private key and decrypt with the public key.
Execute the following command:

./sample_rsa -k 2048

It can be confirmed that the decrypted string matches the original text.

3.19.4. Common Issues

3.19.4.1. What are the differences when using different key lengths in HMAC?

HMAC key length can be flexibly chosen. When the key length does not match the hash function’s block length, the following processing is applied:

Key length smaller than hash function block length: For example, using SHA-256 with a 512-bit key, the algorithm internally pads zeros at the end of the key to reach the block length.
Key length larger than hash function block length: For example, using SHA-256 with a 128-bit key, the algorithm internally hashes the key and uses the hash result as the actual key.

Generally, for security reasons, it is recommended that the key length equals the output length of the hash function.