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 simplicity and more performances (both speed and size). Another important improvement is that the library is based on core support and no more dedicated to each product, therefore offering to easily use it from product to product sharing the same core, without porting effort.

To be noted that NIST deprecated algorithm were removed.

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

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-AES256

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[] = {…};
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 on simpler interface brought by the 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. 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	11,189	8,660	22.6%	8,218	4,592	44.1%
AES CBC 64 Bytes decryption	12,000	10,098	15.8%	8,218	4,592	44.1%
SHA256 16 bytes Digest	9,630	6,137	36.2%	2,204	2,144	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 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 path to the legacy_v3/src 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

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 is not providing it in the curve's parameter of structure EC_stt to the ECCinitEC function, you need to change this part of your code to have it working using the helpers+V4.x.x.

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

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 improvements.

Information

The provided helpers source code and the CMOX.chm file are here to help you understand how to the new APIs work, helping you in the migration process. Consider the possibility to modify your code to work with single-call API for better efficiency.