Migration from previous Cryptographic Library version

This page describes the main changes compared to legacy Cryptographic Library version V3.x.x, and helps with the migration of user code to the new Cryptographic Library version V4.x.x

1. What's new in the V4.x.x version

Cryptographic Library V4.x.x, in addition to new algorithms, brings simplicity and performances (both speed and size). Another important improvement is that the library is based on core support and is no longer dedicated to each product, which allows its easy reuse across products sharing the same core, without duplicated effort.

Note that NIST deprecated algorithms were removed.

All cryptographic algorithms are NIST CAVP certified to provide security assurance. The certificates are publicly available for further use.

1.1. New algorithms

The new algorithms below are available:

Hash
SHA3, SHAKE, SM3
MAC
KMAC
Cipher
SM4
ECC
SM2, ECDH on Curve448, EdDSA on edwards448 curve
RSA
PKCS#1 v2.2, CRT, Bellcore Attack protection
DRBG
CTR_DRBG-AES256

1.2. Simplicity

Here is an example using the simpler interface introduced by the Cryptographic Library V4.x.x in performing ECDSA verification:

V3.x.x V4.0.0 
int32_t rv;
EC_stt EC_st;
membuf_stt Crypto_Buffer;
ECpoint_stt *PubKey = NULL;
ECDSAsignature_stt *sign = NULL;
uint8_t membuf[MAX_MEMBUF_SIZE];
ECDSAverifyCtx_stt verctx;

uint8_t pub_x[] = {…}, pub_y[] = {…};
uint8_t sign_r[] = {…}, sign_s[] = {…};
uint8_t digest[] = {…};

Crypto_Buf.pmBuf = membuf;
Crypto_Buf.mUsed = 0;
Crypto_Buf.mSize = sizeof(membuf);

// ToDo: manually fill EC_st with
// curve parameters!!!

/* Init the EC main struct */
rv = ECCinitEC(&EC_st, &Crypto_Buf);

/* Init the public key */
ECCinitPoint(&PubKey,
        &EC_st,
        &Crypto_Buf);
ECCsetPointCoordinate(PubKey,
        E_ECC_POINT_COORDINATE_X,
        pub_x,
        sizeof(pub_x));
ECCsetPointCoordinate(PubKey,
        E_ECC_POINT_COORDINATE_Y,
        pub_y,
        sizeof(pub_y));

/* Init the signature */
ECDSAinitSign(&sign,
        &EC_st,
        &Crypto_Buf);
ECDSAsetSignature(sign,
        E_ECDSA_SIGNATURE_R_VALUE,
        sign_r, sizeof(sign_r));
ECDSAsetSignature(sign,
        E_ECDSA_SIGNATURE_S_VALUE,
        sign_s, sizeof(sign_s));

/* Verification */
verif_ctx.pmEC = &EC_st;
verif_ctx.pmPubKey = PubKey;
rv = ECDSAverify(digest,
        sizeof(digest),
        sign,
        &verif_ctx,
        &Crypto_Buf);
 
cmox_ecc_retval_t rv;
cmox_ecc_handle_t Ecc_Ctx;
uint8_t membuf[MAX_MEMBUF_SIZE];
uint32_t fault_check = CMOX_ECC_AUTH_FAIL;

uint8_t pubkey[] = {…}, digest[] = {…};
uint8_t signature[] = {…};

/* Construct a ECC context */
cmox_ecc_construct(&Ecc_Ctx,
        CMOX_ECC256_MATH_FUNCS,
        membuf, sizeof(membuf));

/* Verify directly the signature passing
   all the needed parameters */
rv = cmox_ecdsa_verify(&Ecc_Ctx,
        CMOX_ECC_CURVE_SECP256R1,
        pubkey, pubkey(Public_Key),
        digest, sizeof(digest),
        signature, sizeof(signature),
        &fault_check);

Here is another example using the simpler interface introduced by Cryptographic Library V4.x.x in performing AES GCM AEAD Encryption:

V3.x.x V4.0.0 
AESGCMctx_stt AESctx;
uint32_t error_status = AES_SUCCESS;

AESctx.mFlags = E_SK_DEFAULT;
AESctx.mKeySize = sizeof(Key);
AESctx.mIvSize = sizeof(IV);
AESctx.mTagSize = 16;
/* Initialize the operation, by passing key and IV */
error_status = AES_GCM_Encrypt_Init(&AESctx, 
        Key, IV);
/* Append AAD  */
error_status = AES_GCM_Header_Append(&AESctx,
        AddData, sizeof(AddData));
/* Append plaintext */
error_status = AES_GCM_Encrypt_Append(&AESctx,
        Plaintext, sizeof(Plaintext),
        Computed_Ciphertext, &computed_size);
/* Finalize and compute tag */
error_status = AES_GCM_Encrypt_Finish(&AESctx,
        Tag, &tag_size);
 
cmox_cipher_retval_t rv;
rv = cmox_aead_encrypt(CMOX_AES_GCM_ENC_ALGO,
        Plaintext, sizeof(Plaintext),
        sizeof(Expected_Tag),
        Key, sizeof(Key),
        IV, sizeof(IV),
        AddData, sizeof(AddData),
        Computed_Ciphertext, &computed_size);
/* NB: tag included in Computed_Ciphertext */

1.3. Performance

A comparative view of the best performances achievable on a STM32G4 using both the Cryptographic Library V3.x.x and V4.x.x versions is given below.

Use cases V3.1.3 Cycles V4.0.0 Cycles Improvements V3.1.3 Code Size V4.0.0 Code size Improvements
AES CBC 64 Bytes encryption 11 189 8660 22.6% 8218 4592 44.1%
AES CBC 64 Bytes decryption 12 000 10 098 15.8% 8218 4592 44.1%
SHA256 16 bytes Digest 9630 6137 36.2% 2204 2144 2.7%
ECDSA SECP256R1 Signature 20 298 504 2 957 360 85.4% 21 616 14 610 32.41%
ECDSA SECP256R1 Verification 26 891 792 6 575 536 75.55% 21 616 15 110 30.10%

2. Deprecated algorithms

Some algorithms available in the V3.x.x are no longer supported as they have been deprecated for security reasons.

Algorithm Comment
MD5 More details of MD5 vulnerabilities are available on the rfc6151[1]
ARC4 More details of RC4/ARC4 vulnerabilities are available on the rfc7465[2]
DES Withdrawn by NIST on May 19, 2005: FIPS46-3[3]
T-DES Withdrawn by NIST on September 26, 2018: NIST-SP800-20[4]
Info white.png Information
NOTE: The SHA1 algorithm, even though it is also considered as deprecated, is still available in the Cryptographic Library as it comes with other SHA implementations.

3. V3.x.x to V4.x.x migration information and links

Migration helpers are provided in the cryptographic library middleware legacy_v3 folder.

These files are provided to help you migrate your software designed on V3.x.x APIs onto the V4.x.x APIs.

3.1. Switch your project from V3.x.x to V4.x.x

  • Remove the old V3.x.x library from your project, including the path to the V3.x.x library header folder.
  • Update your project to include the V4.x.x as described in Creating a project
  • Add to your project settings the path to the legacy_v3/include folder
  • Add to your project settings the path to the legacy_v3/src folder
  • Add to your project settings the sources to the legacy_v3/src files corresponding to the algorithms you are using
  • Add a call to cmox_initialize before any other call to the cryptographic services. (Do not forget to include cmox_crypto.h header to make this call)
  • Rebuild all your project; it should work as before

ECC particular case:

In the V4.x.x library ECC module, to avoid specific attacks (invalid point/curve attacks), the parameter B is mandatory and must be given to successfully instantiate an ECC curve.

Thus, if your code running on the V3.x.x library does not provide it in the curve's parameter of structure EC_stt to the ECCinitEC function, you need to change this part of your code using the helpers+V4.x.x in order for it to work.

Warning white.png Warning
Please note: Use of these helpers is not recommended in your final product, as they are ONLY helpers for migration and do not provide the benefit of all of the best cryptographic libraries

3.2. Migrate your project from V3.x.x to V4.x.x

You can now rewrite your application progressively to use the V4.x.x APIs and then fully benefit from all the V4.x.x improvements.

Info white.png Information
The provided helpers source code and the CMOX.chm file are given here to help you understand how to the new APIs work, which helps you in the migration process. Consider also the possibility of modifying your code to work with a single-call API for better efficiency.

4. References

  1. ↑ rfc6151
  2. ↑ rfc7465
  3. ↑ FIPS46-3
  4. ↑ NIST-SP800-20


Retrieved from "https://wiki.stmicroelectronics.cn/stm32mcu/index.php?title=Security:Migration_from_previous_Cryptographic_Library_version&oldid=14192"