X-Cube-Cryptolib V4

加解密算法是实现信息安全设计的重要工具，在安全启动，安全通信等多个场景都会用到，STM32一直以来都提供支持全系列的算法库软件包X-CUBE-CRYPTOLIB，今年STM32对其加解密算法库又做了进一步的改进升级，发布了V4版本，这个版本的主要亮点有哪些？

接下来我们具体看一下V4版本的加解密库有哪些新变化。
. N, E5 g( k) F0 D6 e  l
2 I- p/ f2 o. N1 n' x) L

Cryptolib V4支持的算法

新增加的算法
1 F# |  ~2 P) C( o

·支持国密SM算法
-SM4 (CBC, CFB, CTR, ECB, OFB)
% G+ Z4 k" n9 K; Z. d-SM3
-SM2 (密钥对生成，计算ZA，签名，验签）
* D1 I5 c3 B4 G( a5 Y  J3 L, e3 Y

·散列算法
除了SM3，还增加了SHA3 (SHA3-224, SHA3-256, SHA3-384, SHA3-512) 和SHAKE
, f' x  c7 R  S; m+ `5 _
/ U5 O% ]- h" l6 n
·MAC算法
, M- F6 `, ~5 w6 W+ ]HMAC (SM3), KMAC (SHAKE)

* v7 P7 S# o9 L# e
  p8 L- |, V# ?- J" o0 m/ C5 O·ECC椭圆曲线算法
除了SM2，还增加了ECDSA的Ed448


/ h. b7 p% ~  S- h% S* }3 l·ECDH算法
. @. L7 L* D* p+ Q6 {9 M增加Curve448
  ^1 x5 u2 |% O7 l

( n) @- e7 x  u9 _) S" x, v' z·RSA算法
新增加PKCS#1 V2.2 以及 RSA CRT模式（包含抵御Bellcore攻击的防护）


·随机数生成
增加CTR_DRBG_AES256

不再包含的算法
- Z  F0 Y: ^+ \' t4 a3 g- W
·部分旧的算法，处于安全性考虑不推荐使用，因此在V4中不再包含，例如
3 Z# {8 L% o, v9 ?: g" |块加密算法中的ARC4, DES, TDES
散列算法中的MD5
: K; c  J6 c3 W4 B
0 \! P; f$ Y! E8 H9 u( H- Z3 G& Q
·密钥派生算法HKDF
V3中包含的HKDF-512算法在V4中不直接以库的形式提供
在ST wiki页面中会说明如何在HMAC基础上实现HKDF

软件包内容

新的软件包架构

新版本采用了新的软件包架构
" n( s1 y- \# F& J+ ^
0 @/ [# g9 j$ s1 X0 N5 v
加解密库仅按照内核提供（每个内核对应一个加解密库）
) [; S- O- R4 p  R加解密库不再按照STM32系列分别提供
加解密库不再区分编译器和优化方式（Speed、Size、FPU）
! d# p% d) z3 n

V4的目录结构 vs. V3的目录结构

V3软件包的目录结构是每一个STM32系列对应一个单独的目录

( L6 b& T6 b% E3 P
9 k" k- \3 L! j9 M' l8 _每个芯片系列都有对应的Middleware目录, 里面包含加解密库
' ]" T4 E& j9 A4 ~- t! q5 H' a; j加解密库有多个库文件，分别针对不同编译器以及不同的优化选项
; @- G! ~3 c/ f( }( A% r' O参考例程工程同样也在每个STM32系列子目录的Projects目录中。
: o! r1 Z9 Z& A7 w" }

V4的目录结构则完全兼容Cube/X-Cube软件包（STM32Cubexx / X-Cube-xxx）架构，方便与Cube/X-Cube包进行集成。
: {! D% u* m2 h5 F8 A7 l! @

+ m' N9 k4 Q; G2 R2 i/ \" ~/ G% b8 nV4中包含加解密库的Middleware文件夹直接在顶层目录
lib目录下的库文件不针对每个STM32系列，也不再区分不同的编译器和优化方式
加解密库文件按照Cortex内核版本，每个内核提供一个统一的库文件
同一个库文件可以适用于各种编译器（AEABI兼容）
$ f3 d6 F2 S+ `对于不同优化选项的选择可以在链接阶段进行配置
! y: ?4 B, D  j" }3 D

V4的参考例程则类似Cube/X-Cube包的结构，在Projects目录下的各个系列的子目录中提供。

新版本示例工程支持的系列包括
, K  B' z- V3 K" @0 I' X/ r1 N0 i
0 u, q* |6 {. z' ]9 Q$ V# v
: F' Y7 z5 d% }2 C( _+ l/ h8 F( lSTM32G0，STM32G4
STM32H7
. h# ?3 d3 |9 {8 o/ _: j# j# uSTM32L0，STM32L1，STM32L4，STM32L5，STM32U5 (V4.0.1中包含)
STM32WB，STM32WL
. a) J, Z% Y" z5 U& Z2 M2 s
) e" T& S  t; ~5 C, K8 p2 P- a
其他STM32系列虽然没有提供直接的参考例程，但也可以参考示例代码的方式使用库文件，因为库是针对不同Cortex®-M内核提供的，并不区分产品系列。
3 Z+ D; X; N; t; K6 W' _
5 d4 n" w' z, a6 n代码质量进一步提升

V4版本加解密库的源码经过MISRAC:2012检查，加解密库的头文件也同样符合MISRAC:2012标准，对于有MISRAC合规需求的场景，V4将提供很好的支持。

更小代码+更高性能

$ ]8 v5 R0 S$ t; ~3 g( d. ?V4的加解密库在优化方面做了很多提升。以STM32G4为例，我们可以用下表对比一下使用CryptoLib V3.1.3和V4.0.0版本，选择最高性能配置时的运算速度比较。可以看到，无论是对称算法，散列算法还是非对称算法，V4在性能上都有了很大提升，同时加解密库的代码量比V3还要更小。

更加灵活易用

方便灵活的方式选择加解密库的实现配置
" U  X' ~6 {- c$ O9 m4 l8 c
V4的加解密库为每个内核提供一个单一的库文件，但是允许客户在其应用工程中可以根据速度和代码大小的需要选择不同的配置。这个配置在链接和使用过程中完成。

5 `- }6 U: ]) b/ z5 K; x$ Z
: L4 @; n) G4 }+ UV3的加解密库在编译阶段使用不同配置，编译出不同的库文件
5 U6 R# l7 n' g2 q4 F2 T而V4在相同的算法服务中实现了对不同配置（性能高低和代码量大小）的支持
9 A) H$ \8 L3 b) W# h用户通过Construct API或者每个服务的Processing API来进行选择采用哪个实现
( l7 y, D- J( {# t) q& @缺省的配置以头文件形式提供

2 t. M- c  i6 V6 i以ECDSA签名算法为例，使用签名函数之前，首先需要调用cmox_ecc_construct（）函数，这个函数的第二个输入参数CMOX_ECC256_MATH_FUNCS就用来选择下层的具体实现使用哪一个。

CMOX_ECC256_MATH_FUNCS的定义决定了ECDSA的处理函数将会选择哪个实现，缺省配置为CMOX_MATH_FUNCS_SUPERFAST256，可选配置包括
  S& X  w$ C* {* E, ~
; _8 d0 ?% k4 `* N
CMOX_MATH_FUNCS_SMALL ：代码量小，性能相对低
. y& c0 j; E: Z; RCMOX_MATH_FUNCS_FAST ：性能高，代码量相对大
CMOX_MATH_FUNCS_SUPERFAST256：性能更高（针对长度为225到256的ECC曲线）
/ ~3 E9 K* j1 b( u0 a  a& j! O" q- F
' o! `9 K; z; S9 C: m其他算法的配置也可以使用类似的方法进行性能和代码量大小的选择，具体请参考Middlewares\ST\STM32_Cryptographic\include\cmox_default_config.h


; X( E  S. M6 i+ E  o* `如果希望所有的配置都按照最小代码量来选择，则可以直接使用相同目录下的cmox_small_config.h头文件的定义，如果希望所有配置都按照最高性能来选择，则可以直接使用相同目录下的cmox_fast_config.h头文件的配置。
; ?# y: r  D: d

% p% b; q0 q$ R7 A9 p* A应用代码调用更加简洁
同样以ECDSA为例，使用V3版本加解密库，应用程序需要调用多个API才能完成 一个ECDSA Verification，而使用V4的加解密库只需要两个API即可完成。

V3

1. int32_t rv;
   3 j! w# w9 U3 i
2. EC_stt EC_st;
     C, z4 T0 K6 t) Q1 v; W. Y
3. membuf_stt Crypto_Buffer;
   
4. ECpoint_stt *PubKey = NULL;
   
5. ECDSAsignature_stt *sign = NULL;
   6 E* w' M- o( F; _+ W8 ~, ^
6. uint8_t membuf[MAX_MEMBUF_SIZE];
   1 r) t6 O! R8 m
7. ECDSAverifyCtx_stt verctx;
   7 \/ f8 J2 l( B9 G6 `2 S
8. 
     x4 V+ C4 |4 R7 q- T. O; _
9. uint8_t pub_x[] = {…}, pub_y[] = {…};
   % F. M# x2 ~+ d8 e2 J. B* V
10. uint8_t sign_r[] = {…}, sign_s[] = {…};
    * G" K7 N0 c5 ?* V* H$ M
11. uint8_t digest[] = {…};
    
12. 
    
13. Crypto_Buf.pmBuf = membuf;
    2 i3 N: t2 s0 k+ k, z( V
14. Crypto_Buf.mUsed = 0;
    7 n& ]8 u% z# f' t
15. Crypto_Buf.mSize = sizeof(membuf);
    
16. 
    . e, a" T( l  R$ g) s+ u
17. /* Init the EC main struct */
    6 S7 x# w; p2 y$ F$ H
18. rv = ECCinitEC(&EC_st, &Crypto_Buf);
    
19. 
    
20. /* Init the public key */
    / l5 }8 B! u* c/ _5 n
21. ECCinitPoint(&PubKey,
    
22.              &EC_st,
    3 y3 y- @9 }+ e+ P2 s
23.              &Crypto_Buf);
    ' z/ {( b  F8 b4 v5 R' [
24. ECCsetPointCoordinate(PubKey,
    6 X4 ^! Y6 n1 b- y! |3 r
25.                E_ECC_POINT_COORDINATE_X,
    
26.                pub_x,
    ) I% A6 d! t5 |. T& u8 G" X; ]9 r
27.                sizeof(pub_x));
    ' K& a8 a- O8 X, X2 `  L6 t" y* l3 F+ _
28. ECCsetPointCoordinate(PubKey,
    
29.                E_ECC_POINT_COORDINATE_Y,
    
30.                pub_y,
    
31.                sizeof(pub_y));
    
32. 
    : ^8 O# j7 N! T) O9 X. `
33. /* Init the signature */
    & q( D. F# A/ F
34. ECDSAinitSign(&sign,
    ' M) `% \7 M, O3 ~
35.               &EC_st,
    6 f* D& ]& B1 O$ F* I: f: p/ E, q% s
36.               &Crypto_Buf);
    
37. ECDSAsetSignature(sign,
    
38.               E_ECDSA_SIGNATURE_R_VALUE,
    
39.               sign_r, sizeof(sign_r));
    * r6 T% W. y" g" g! m
40. ECDSAsetSignature(sign,
    0 K3 G1 y: w7 ~8 I# i, D  y
41.               E_ECDSA_SIGNATURE_S_VALUE,
    
42.               sign_s, sizeof(sign_s));
    + B+ X1 P# d+ g
43. 
    
44. /* Verification */
    
45. verif_ctx.pmEC = &EC_st;
    
46. verif_ctx.pmPubKey = PubKey;
    
47. rv = ECDSAverify(digest,
    6 H' ]! F0 L6 F+ W& K4 _
48.                  sizeof(digest),
    9 a9 e: ]: k4 n/ {- s
49.                  sign,
    
50.                  &verif_ctx,
    2 i* X+ H0 v, Z1 k  A0 u, E
51.                  &Crypto_Buf);

复制代码

V4

1. 
   
2. cmox_ecc_retval_t rv;
     x. C! \; G) N; i& }1 B' n# ~
3. cmox_ecc_handle_t Ecc_Ctx;
   ; [. A6 ^2 J4 c% K$ @+ I! N2 ~
4. uint8_t membuf[MAX_MEMBUF_SIZE];
   0 E, c& L5 G* n) |! E4 Z5 I4 W
5. uint32_t fault_check = CMOX_ECC_AUTH_FAIL;
   
6. 
   ' S- Q5 I& [0 D
7. uint8_t pubkey[] = {…}, digest[] = {…};
   
8. uint8_t signature[] = {…};
   
9. 
   . c  U# a/ {& U  U$ U, |* i! z
10. /* Construct a ECC context */
    & l4 |- q* }* K4 h, u3 _
11. cmox_ecc_construct(&Ecc_Ctx,
    $ G1 l7 Q  V9 Z( _' u
12.         CMOX_ECC256_MATH_FUNCS,
    3 l+ e2 u+ i* P0 A
13.         membuf, sizeof(membuf));
    7 E& f  @* F9 g$ W- C
14. 
    
15. /* Verify directly the signature passing
    
16.    all the needed parameters */
    
17. rv = cmox_ecdsa_verify(&Ecc_Ctx,
    ! y& c2 A# {7 y0 x! z; k. G
18.         CMOX_ECC_CURVE_SECP256R1,
    ( O8 E2 z2 g$ w
19.         pubkey, pubkey(Public_Key),
    * I9 y2 ^9 O. }# p* [0 ^
20.         digest, sizeof(digest),
    
21.         signature, sizeof(signature),
    & L: P0 L3 h# Z) `" E
22.         &fault_check);

复制代码

从V3到V4的快速切换
6 Y8 @, X2 W- D* f  f# i: h1 m
2 \4 m7 M9 t5 I7 q# k2 Z$ [


在V4的软件包中，还提供了一个wrapper实现，帮助以前V3的使用者快速切换到V4的，这个wrapper允许应用继续沿用V3 API但使用V4的库。当然，这种用法虽然快速切换到V4，但却不能最大化地利用V4的新优点，不是推荐用法，仅仅作为快速切换的目的使用。

算法认证

6 X/ f& \' ~3 e4 b& h
V4提供的加解密库经过了NIST CAVP（Cryptographic Algorithm Validation Program）的认证。
. J% b5 H: F4 }/ D* Y' U+ s
# @  J0 J7 [' R' C- P) {
( T, h$ G' E( g% s3 m认证测试覆盖了不同的性能和代码大小的配置方式（前面提到的可以通过头文件的宏定义进行的配置选择）
认证基于Cortex®-M内核，而不是和某个特定的STM32系列绑定，所以可以适用于所有STM32系列
( B* g$ m0 {  h9 j6 a0 X( ]
有关加解密库认证的详细信息可以参考此链接：https://wiki.stmicroelectronics. ... rary_Certifications

# Y$ _; j7 h* N* |' w# v
$ Z. {6 J# {/ T, c! p

资源链接

# K& y6 y5 Y( n# y( v$ T& I
文档
, ^7 _9 |, @. G4 N- x2 _" j2 |2 P所有Cryptolib V4相关的文档都通过STM32 MCU Wiki以网页形式提供，不再提供单独的UM和其他文档：https://wiki.st.com/stm32mcu/wiki/Category:Cryptographic_library
* F# P4 r4 q/ ~1 v3 [

) H; n' k  }  N% L. L7 H! Z内容包括

, A  |3 R7 o: ?% N+ R, o* F
加解密库简介、使用指南、密码学算法的基础知识
) r4 ^  _4 ]3 M

如何安全地使用加解密库、如何实现HKDF、加解密库认证信息、如何迁移到新版加解密库
4 c& b( Y9 \" d6 S& m' c

加解密库的性能及资源占用信息
( K& P" X: x9 q4 d0 Y: c, e

下载页面
V4版本加解密库可以从XCUBE-CRYPTOLIB常规的网址下载：
' Q3 D, ?/ W& r' Ghttps://www.st.com/en/embedded-software/x-cube-cryptolib.html
- N' ^2 ]; U- v" ]

" w( ?8 u- @1 |1 h3 E- ~8 k& vV3版本加解密库可以通过以下链接下载：
https://www.st.com/en/embedded-software/x-cube-crypto-v3.html

& |+ w9 Y1 ]1 s# {: Q/ }
; e3 m- E  b4 Q8 `4 T6 C/ V6 {