Difference between revisions of "Security:Migration from previous Cryptographic Library version"

[checked revision] [quality revision]
m
m
 

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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 here on the rfc6151[1]
ARC4 More details of RC4/ARC4 vulnerabilities are available here 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[edit]

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[edit]

  • 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[edit]

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[edit]


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

== 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 [[Security:Migration_from_previous_Cryptographic_Library_version#Deprecated_algorithms|deprecated algorithms]] were removed.

All cryptographic algorithms are NIST CAVP certified to provide security assurance. The [[Security:Cryptographic_Library_Certifications|certificates]] are publicly available for further use.

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

=== Simplicity ===

Here is an example using the simpler interface introduced by the Cryptographic Library V4.x.x in performing ''ECDSA verification'':
{| class="st-table"
!  V3.x.x 
!  V4.0.0
|-
|<syntaxhighlight   class="noscroll">

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);</syntaxhighlight>

||<syntaxhighlight   class="noscroll">

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);</syntaxhighlight>

|}

Here is another example using the simpler interface introduced by Cryptographic Library V4.x.x in performing ''AES GCM AEAD Encryption'':
{| class="st-table"
!  V3.x.x 
!  V4.0.0
|-
|<syntaxhighlight   class="noscroll">

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);</syntaxhighlight>

||<syntaxhighlight   class="noscroll">

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 */</syntaxhighlight>

|}

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

{| class="st-table"
! 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%'''''
|}

== Deprecated algorithms ==

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

{| class="st-table"
! Algorithm ||Comment
|-
| '''''MD5'''''   || More details of MD5 vulnerabilities are available here on the rfc6151<ref>[https://tools.ietf.org/html/rfc6151 rfc6151]</ref>

|- 
| '''''ARC4'''''   || More details of RC4/ARC4 vulnerabilities are available here on the rfc7465<ref>[https://tools.ietf.org/html/rfc7465 rfc7465]</ref>

|- 
| '''''DES''''' || Withdrawn by NIST on May 19, 2005: FIPS46-3<ref>[https://csrc.nist.gov/csrc/media/publications/fips/46/3/archive/1999-10-25/documents/fips46-3.pdf FIPS46-3]</ref>

|- 
| '''''T-DES'''''       || Withdrawn by NIST on September 26, 2018: NIST-SP800-20<ref>[https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-20.pdf NIST-SP800-20]</ref>

|}

{{info|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.}}

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

=== 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 [[Security:Getting_started_with_the_Cryptographic_Library#Creating_a_project_that_embeds_the_Cryptographic_Library|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
<blockquote>

'''''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.</blockquote>


{{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}}

=== 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| 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.}}
==References==<references />

<noinclude>

[[Category:Cryptographic_library|70]]
{{PublicationRequestId | 19924| 2020-05-06 |xx}}<noinclude>
Line 177: Line 177:
 
! Algorithm ||Comment
 
! Algorithm ||Comment
 
|-
 
|-
| '''''MD5'''''  || More details of MD5 vulnerabilities are available here [https://tools.ietf.org/html/rfc6151 rfc6151]
+
| '''''MD5'''''  || More details of MD5 vulnerabilities are available on the rfc6151<ref>[https://tools.ietf.org/html/rfc6151 rfc6151]</ref>
 
|-  
 
|-  
| '''''ARC4'''''  || More details of RC4/ARC4 vulnerabilities are available here [https://tools.ietf.org/html/rfc7465 rfc7465]
+
| '''''ARC4'''''  || More details of RC4/ARC4 vulnerabilities are available on the rfc7465<ref>[https://tools.ietf.org/html/rfc7465 rfc7465]</ref>
 
|-  
 
|-  
| '''''DES''''' || Withdrawn by NIST on May 19, 2005:[https://csrc.nist.gov/csrc/media/publications/fips/46/3/archive/1999-10-25/documents/fips46-3.pdf FIPS46-3]
+
| '''''DES''''' || Withdrawn by NIST on May 19, 2005: FIPS46-3<ref>[https://csrc.nist.gov/csrc/media/publications/fips/46/3/archive/1999-10-25/documents/fips46-3.pdf FIPS46-3]</ref>
 
|-  
 
|-  
| '''''T-DES'''''      || Withdrawn by NIST on September 26, 2018:[https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-20.pdf NIST-SP800-20]
+
| '''''T-DES'''''      || Withdrawn by NIST on September 26, 2018: NIST-SP800-20<ref>[https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-20.pdf NIST-SP800-20]</ref>
 
|}
 
|}
   
Line 219: Line 219:
   
 
{{info| 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.}}
 
{{info| 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.}}
  +
  +
==References==
  +
<references />
   
 
<noinclude>
 
<noinclude>