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
ARC4	More details of RC4/ARC4 vulnerabilities are available on the rfc7465
DES	Withdrawn by NIST on May 19, 2005: FIPS46-3
T-DES	Withdrawn by NIST on September 26, 2018: NIST-SP800-20

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

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.

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.