Migration from previous Cryptographic Library version

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

This page explains the differences between the previous Cryptographic Library version V3.x.x and the current one V4.x.x.

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

Cryptographic Library V4.x.x, in addition to new algorithms, brings more simplicity and more performances (both speed and size)

1.1. New algorithms

Here are the new algorithms 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-AES128

1.2. Simplicity

Here is an example on simpler interface brought 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[] = {…}, 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[] = {…}, 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);

1.3. Performances

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

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	11189	8660	22.6%	8218	4592	44.1%
AES CBC 64 Bytes decryption	12000	10098	15.8%	8218	4592	44.1%
SHA256 16 bytes Digest	9630	6137	36.2%	2204	2144	2.7%
ECDSA SECP256R1 Signature	20298504	2957360	85.4%	21616	14610	32.41%
ECDSA SECP256R1 Verification	26891792	6575536	75.55%	21616	15110	30.10%

2. Deprecated algorithms

Some algorithms available in the V3.x.x are no more supported, cause they have been deprecated for security reason.

Algorithm	Comment
MD5	More details on MD5 vulnerabilities are available here rfc6151
ARC4	More details on RC4/ARC4 vulnerabilities are available here 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: SHA1 algorithm, even if it is also considered as deprecated, is still available in the Cryptographic Library cause it comes with other SHA implementations.

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

In the Cryptographic Library middleware legacy_v3 folder, we provide migration helpers.

This files are provided to help you migrate your software designed upon 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 describe in Creating a project
Add to your project settings the path to the legacy_v3/include folder
Add to your project settings the sources to the legacy_v3/src files coresponding to the algorithms you are using
Rebuild all your project, it should work as before

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 of all the V4.x.x improvments.

Warning

Please notice: It is not recommended to use this helpers in your final product, as they are ONLY helpers for migration; and will not allow taking benefit of all the best of the Cryptographic Library