Home

UM0586 User manual - STMicroelectronics

1. ES ECB Encrypt Append Launches cryptographic operation can be called several times ES_ECB_Decrypt_Init Loads the key and ivec performs key schedule init hw and so on ES_ECB_Decrypt_Append Launches cryptographic operation can be called several times A A AES_ECB_Encrypt_Finish Possible final output A A A ES_ECB_Decrypt_Finish Possible final output 2 DoclD14989 Rev 4 UMO586 AES algorithm Figure 7 AES AAA flowchart Encryption Begin AES Encryption Initialization API AES AAA Encrypt Init y Decryption Begin AES Decryption Initialization API AES AAA Decrypt Init error status AES ERR BAD CONTEXT AES SUCCESS AES_ERR_BAD_PARAMETER AES Encryption API AES_AAA_Encrypt_Append i error_status AES ERR BAD CONTEXT AES SUCCESS AES ERR BAD PARAMETER AES Decryption API AES AAA Decrypt Append error status AES ERR BAD PARAMETER AES ERR BAD INPUT SIZE used only with CBC and ECB AES ERR BAD OPERATION DMA BAD ADDRESS DMA ERR TRANSFER AES SUCCESS AES Encryption Finalization API AES_AAA Encrypt Finish error status gt AES_ERR_BAD_PARAMETER AES_ERR_BAD_INPUT_SIZE used only with CBC and ECB AES_ERR_BAD_OPERATION DMA_BAD_ADDRESS DMA_ERR_TRANSFER AES_SUCCESS AES Decryption Finaliz
2. const uint8 t pmTag Size of the Tag to return Must be set by the caller prior to calling Init int32 t mTagSize Size of the Tag to return Must be set by the caller prior to calling Init ky DoclD14989 Rev 4 55 131 AES algorithm UMO586 4 5 2 AES_CMAC_Encrypt_Append function Table 48 AES_CMAC_Encrypt_Append Function name AES CMAC Encrypt Append int32 t AES CMAC Encrypt Append AESCMACctx_stt P_pAESCMACctx Prototype const uint8 t P pInputBuffer int32 t P_inputSize Behavior AES Encryption in CMAC Mode in out P pAESCMACctx AES CMAC already initialized context Parameter in P_pInputBuffer Input buffer in P inputSize Size of input data in uint8_t octets Return value AES SUCCESS Operation Successful AES ERR BAD PARAMETER At least one parameter is a NULL pointer AES ERR BAD INPUT SIZE P inputSize lt 0 P inputSize 16 0 88 P pAESCMACctx mFlags amp E SK FINAL APPEND E SK FINAL APPEND AES ERR BAD OPERATION Append not allowed 1 This function can be called multiple times with P_inputSize multiple of 16 bytes The last call allows any positive value for P_inputSize but flag E_SK_FINAL_APPEND must be set inside P_pAESCMACctx mFlags i e with a simple P pAESCMACctx gt mFlags E SK FINAL APPEND 4 5 3 AES CMAC Encrypt Finish function Table 49 AES CMAC Encrypt Finish Functio
3. EE EE ee 93 RSA PKCS1v15 Verify function ie AA 94 RSApubKey stt data structure EE EG GE Ge ee 94 ECC algorithm functions cesera EE Ee eee 96 ECCinitEC function EE EE EE EE se ee a tees 101 EC stt data structure su ss cra RAE a N RR ad Bek Ca Rl ee ANG 101 ECCfreeEC function see EE aaa 102 ECCinitPoint function se EE EE EE Ee ee ee tenes 102 DocID14989 Rev 4 Ly UMO586 List of tables Table 101 ECpoint stt data structure is EE a 102 Table 102 ECCfreePoint function EE EE EE EG EG eee 103 Table 103 ECCsetPointCoordinate function EE EE ee ee ee ee ee ee ee eek ee ee 103 Table 104 ECCgetPointCoordinate function EE EE Ee EE ee eae 104 Table 105 ECCgetPointFlag function ie Ee ene 104 Table 106 ECCsetPointFlag function EE ES a 104 Table 107 ECCcopyPointfunctON 0 0 105 Table 108 ECCinitPrivKey function ee se Se ee ke te ee ee ee ee 105 Table 109 ECCprivKey_stt data structure ee ee ee ee ee ee ee ee ee ee Ge ee ee ee 105 Table 110 ECCfreePrivKey function ii EE ek ee Ge ee ee tenes 106 Table 111 ECCsetPrivKeyValue function ii EE EE ee tenes 106 Table 112 ECCgetPrivKeyValue function 0 0 EE Ee EE ke teens 107 Table 113 ECCscalarMul function 0 EG ee ee eee ee 107 Table 114 ECCsetPointGenerator function EE EE EE cee ee ee 108 Table 115 ECDSAinitSign function ee EE ri
4. Return value DES SUCCESS Operation Successful DES ERR BAD PARAMETER At least one parameter is a NULL pointer 1 DDD is ECB or CBC Note This function won t write output data thus it can be skipped lt is kept for API compatibility 4 DoclD14989 Rev 4 23 131 DES and Triple DES algorithms UMO586 3 3 24 131 TDES library functions Table 11 describes the encryption library s TDES functions below Table 11 TDES algorithm functions TTT ECB or CBC Function name Description TDES_TTT_Encrypt_Init Initialization for TDES Encryption in TTT mode TDES_TTT_Encrypt_Append TDES Encryption in TTT mode TDES_TTT_Encrypt_Finish TDES Encryption Finalization of TTT mode TDES TTT Decrypt_Init Initialization for TDES Decryption in TTT mode TDES_TTT_Decrypt_Append TDES Decryption in TTT mode TDES TTT Decrypt Finish TDES Decryption Finalization in TTT mode TTT represents the mode of operations of the TDES algorithm The following modes of operation can be used for TDES algorithm e ECB e CBC Figure 6 describes the TDES algorithm For example if you want to use ECB mode as a TDES algorithm you can use the following functions Table 12 TDES ECB algorithm functions Function name Description TDES_ECB_Encrypt_Init Initialization for TDES Encryption in ECB mode TDES_ECB_Encrypt_Append TDES Encryption in ECB mode TDES_ECB_Encrypt_Finish TDES Encryption Finalizat
5. Figure 17 ECC Verify flowchart HASH Initialization API HASH_Init error_status HASH_ERR_BAD_PARAMETER HASH_SUCCESS HASH Data Process API HASH_Append error_status HASH_ERR_BAD_PARAMETER HASH_ERR_BAD_OPERATION DMA BAD ADDRESS only if HASH MD5 or SHA1 DMA ERR TRANSFER only if HASH MD5 or SHA1 HASH SUCCESS HASH Finalization API HASH Finish error status gt p HASH_ERR_BAD_PARAMETER HASH_SUCCESS HASH_ERR_BAD_CONTEXT Initialization of the Elliptic Curve API ECCinitEC gt a error_status gt ECC_ERR_BAD_PARAMETER ECC_ERR_BAD_CONTEXT ECC_SUCCESS ERR MEMORY FAIL Initialization of an ECC Point API ECCinitPoint error status ECC ERR BAD PARAMETER ECC ERR BAD CONTEXT ERR MEMORY FAIL ECC SUCCESS Set the coordinate of the ECC Point API ECCsetPointCoordinate ECC ERR BAD PARAMETER ECC ERR BAD PRIVATE KEY No then repeat twice to set both coordinates Initialization of the Signature API ECDSAinitSign error_status ECC_ERR_BAD_PARAMETER ECC_ERR_BAD_CONTEXT ERR_MEMORY_FAIL ECC_SUCCESS Import Signature Value API ECDSAsetSignature error_status ECC_ERR_BAD_PARAMETER ECC_SUCCESS MATH_ERR_BIGNUM_OVERFLOW Both signature values imported No then repeat twice to import both values Signature Verification API ECDSAsign
6. STM32CryptoLibVer TypeDef LibVersion Behavior Get the STM32 Cryptographic Library setting in out STM32CryptoLibVer_TypeDef Pointer to structure that will be Parameter E F used to store the internal library setting Return value None ky DoclD14989 Rev 4 117 131 Cryptographic library performance and memory requirements UMO586 11 11 1 118 131 Cryptographic library performance and memory requirements This section provides a performance evaluation of the cryptographic library for the STM32 microcontroller series In particular this analysis targets the STM32F4xx family as the series STM32F41x includes some cryptographic accelerators specifically it includes e One CRYP Accelerator capable of encryption decryption with AES in ECB CBC CTR and KEYWRAP with all three key sizes 128 192 256 bit DES and TDES in ECB and CBC e One HASH Accelerator capable of MD5 and SHA 1 HASH and HMAC operations e One RNG Random Number Generator The tests were conducted on STM32F41x with CPU running at a frequency of 168 MHz and using RealView Microcontroller Development Kit MDK ARM toolchain V4 70 ST Link Symmetric key algorithms performance results In this section we provide performance results for e DES in ECB and CBC e TDES in ECB and CBC e AES 128 in ECB CBC and CTR and CMAC modes e AES 192 in ECB CBC and CTR and CMAC modes e AES 256 in ECB CBC and CTR and CMAC modes e ARC
7. P plInputBuffer The data that will be processed using HHH in P inputSize Size of input data expressed in bytes Return value HASH SUCCESS Operation Successful HASH ERR BAD PARAMETER At least one parameter is a NULL pointer HASH ERR BAD OPERATION HHH Append can t be called after HHH Finish has been called If in DMA mode then SHA1_Append or MD5 Append can be called only once DMA BAD ADDRESS Input or output buffer addresses are not word aligned used only in SHA1 and MD5 DMA_ERR_TRANSFER Errors in the DMA transfer used only in SHA1 and MD5 1 HHH is MD5 SHA1 SHA224 or SHA256 2 In DMA mode P pMD5ctx 5mFlags amp E HASH USE DMA E HASH USE DMA the Append function can be called one time only otherwise it will return HASH ERR BAD OPERATION 3 In DMA mode P_pSHA1ctx gt mFlags 8 E HASH USE DMA E HASH USE DMA the Append function can be called one time only otherwise it will return HASH ERR BAD OPERATION 4 This function can be called multiple times with no restrictions on the value of P_inputSize DoclD14989 Rev 4 ky UMO586 HASH algorithm 7 2 3 HHH_Finish function Table 85 HHH_Finish Function name HHH_Finish int32_t HHH Finish HHHctx_stt P_pHHHctx Prototype uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior HHH Finish function produce the output HHH digest in out P pHHHctx HASH context Parameter out P p
8. AES ERR BAD OPERATION AUTHENTICATION SUCCESSFUL AES GCM Encryption Finalization API AES_GCM_ Encrypt_Finish a End error_status AES ERR BAD PARAMETER AES SUCCESS AES ERR BAD CONTEXT MS30070V1 40 131 DoclD14989 Rev 4 2 UMO586 AES algorithm 4 3 1 AES GCM Encrypt Init function Table 30 AES GCM Encrypt Init Function name AES GCM Encrypt Init int32 t AES GCM Encrypt Init AESGCMctx stt P pAESGCMctx Prototype const uint8 t P_pKey const uint8 t P pIv Behavior Initialization for AES GCM encryption in out P_pAESGCMctx AES GCM context Parameter in P_pKey Buffer with the Key in P_plv Buffer with the IV AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values see note Note 1 P_pAESGCMctx mKeySize see AESGCMctx_stt must be set with the size of the key prior to calling this function Otherwise the following predefined values can be used CRL_AES128 KEY CRL_AES192 KEY CRL_AES256_KEY 2 P pAESGCMctx mFlags must be set prior to calling this function Default value is E_SK_DEFAULT See SKflags_et for details 3 P pAESGCMctx mlvSize must be set with the size of the IV 12 is the only supported value prior to calling this function 4 P_pAESGCMctx mTagSize must
9. DES Decryption in DDD mode Parameter in P_pDESDDDctx DES DDD already initialized context in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P pOutputSize Size Pointer to integer that will contain the size of written output data expressed in bytes Return value DES SUCCESS Operation Successful DES ERR BAD PARAMETER At least one parameter is a NULL pointer DES ERR BAD INPUT SIZE P_inputSize is not a multiple of CRL DES BLOCK or less than 8 DMA BAD ADDRESS Input or output buffer addresses are not word aligned DMA ERR TRANSFER Error occurred in the DMA transfer DES ERR BAD OPERATION Append not allowed 1 DDD is ECB or CBC Note This function can be called multiple times provided that P_inputSize is a multiple of 8 3 2 6 DES_DDD_Decrypt_Finish function Table 10 DES_DDD_Decrypt_Finish Function name DES DDD Decrypt Finish int32 t DES ECB Decrypt Finish DESDDDctx stt P pDESECBctx Prototype j uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior DES Decryption Finalization of DDD Mode in out P_pDESDDDctx DES DDD already initialized context Parameter out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes
10. lt 7 UMO586 WI life augmented User manual STM32 Cryptographic Library Introduction This manual describes the API of the STM32 cryptographic library STM32 CRYP LIB that supports the following cryptographic algorithms e AES 128 AES 192 AES 256 bits Supported modes are ECB Electronic Codebook Mode CBC Cipher Block Chaining with support for ciphertext stealing CTR Counter Mode CCM Counter with CBC MAC GCM Galois Counter Mode CMAC KEY WRAP e ARC4 e DES TripleDES Supported modes are ECB Electronic Codebook Mode CBC Cipher Block Chaining e HASH functions with HMAC support MD5 SHA 1 SHA 224 SHA 256 e Random engine based on DRBG AES 128 e RSA signature functions with PKCS 1v1 5 e ECC Elliptic Curve Cryptography Key generation Scalar multiplication the base for ECDH ECDSA These cryptographic algorithms can run in the series STM32F1 STM32 L1 STM32F2 STM32F4 STM32F0 and STM32F3 with hardware enhancement accelerators September 2013 DoclD14989 Rev 4 1 131 www st com Contents UMO586 Contents 1 Terminology KEER ADA KA KA ER RE EER DAE OE a A 11 2 STM32 cryptographic library package presentation 12 2 1 Architectures iie OE AA EE A See 12 2 2 Package organization eid since oS oS a AD ed GN he RUE 13 2 2 1 Libraries favored haat AA AR RR ed dees nade ad 14 2 2 2 soe N ie ER EE a Sn eee eee 15 2 2 3 A eek O
11. 1 AAA is ECB CBC or CTR Note This function won t write output data thus it can be skipped It is kept for API compatibility 4 DoclD14989 Rev 4 35 131 AES algorithm UMO586 4 2 4 AES AAA Decrypt Init function Table 26 AES AAA Decrypt Init Function name AES AAA Decrypt Init int32 t AES AAA Decrypt Init AESAAACtx_stt P pAESAAACtx Prototype j const uint8_t P_pKey const uint8 t P pIv Behavior Initialization for AES Decryption in AAA Mode in out P pAESAAActx AES AAA context Parameter in P_pKey Buffer with the Key in P_plv Buffer with the IV AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES ERR BAD CONTEXT Context not initialized with valid values see note 1 AAA is ECB CBC or CTR Note 1 P_pAESAAActx mKeySize see AESAAActx_stt must be set before calling this function with the size of the key or with the following predefined values CRL_AES128 KEY CRL_AES192_KEY CRL_AES256_KEY 2 P_pAESAAActx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 3 P pAESAAActx mlvSize used with CBC and CTR modes must be set with the size of the IV default CRL AES BLOCK prior to calling this function 4 In ECB the IV is not used so the value of P plv is not checked or used 36 131 DoclD14989 Rev 4
12. 4 MS30068V1 4 DoclD14989 Rev 4 25 131 DES and Triple DES algorithms UMO586 3 3 1 TDES TTT Encrypt Init function Table 13 TDES TTT Encrypt Init Function name TDES TTT Encrypt Init int32 t TDES DDD Encrypt Init TDESTTTctx stt P pTDESTTTctx Prototype const uint8 t P_pKey const uint8 t P pIv Behavior Initialization for TDES Encryption in DDD Mode in out P pTDESDDDctx TDES TTT context Parameter in P_pKey Buffer with the Key in P_plv Buffer with the IV Return value TDES SUCCESS Operation Successful TDES ERR BAD PARAMETER At least one parameter is a NULL pointer TDES ERR BAD CONTEXT Context not initialized with valid values see note 2 below This return value is only used with CBC algorithm 1 TTT is ECB or CBC 2 In ECB IV is not used so the value of P plv is not checked or used In CBC IV size must be already written inside the fields of P_pTDESCBCctx The IV size must be at least 1 and at most 16 to avoid the TDES_ERR_BAD_CONTEXT return Note 1 P_pTDESTTTctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 2 P_pTDESCBCctx mlvSize must be set with the size of the IV default CRL TDES BLOCK prior to calling this function TDESTTTctx_stt data structure Structure type for public key Field name Description uint32 t mCon
13. List of tables UMO586 Table 49 Table 50 Table 51 Table 52 Table 53 Table 54 Table 55 Table 56 Table 57 Table 58 Table 59 Table 60 Table 61 Table 62 Table 63 Table 64 Table 65 Table 66 Table 67 Table 68 Table 69 Table 70 Table 71 Table 72 Table 73 Table 74 Table 75 Table 76 Table 77 Table 78 Table 79 Table 80 Table 81 Table 82 Table 83 Table 84 Table 85 Table 86 Table 87 Table 88 Table 89 Table 90 Table 91 Table 92 Table 93 Table 94 Table 95 Table 96 Table 97 Table 98 Table 99 Table 100 8 131 AES CMAC Encrypt Finish o oocococcocco Ee ee Se ee ee ee ee ee ee ee ee 56 AES CMAC Decrypt IN EE 0 200000 cece ee 57 AES CMAC Decrypt Append 222 anaana aaa 58 AES CMAC Decrypt Finish 0 00200 58 AES CCM algorithm functions AG 59 AES COM Encrypt Init a e KA AGARANG 61 AESCCMctx_stt data structure EE EG ES eee 62 AES CCM Header Append EE EE EG ES ee See ee ee ee ee ee ee 63 AES CCM Encrypt Append 63 AES CCM Encrypt Finish sois da ee ee Ge a Re a avs 64 AES CCM Decrypt Init ii ia Ve baat gee estas ee RR a a eae a e RE EG 65 AES CCM Decrypt Append 222 2 e 66 AES CCM Decrypt Finish teas 66 ARC4 algorithm functions EE EE Ee EE eee 68 ARCA Encrypt Init tse ER OE SA EE OO OE EE OE EG 70 ARC4_Encrypt_Append o 70 ARC4ctx_stt data structure 2 2 0
14. Return value SIGNATURE_VALID The Signature is valid SIGNATURE_INVALID The Signature is NOT valid RSA_ERR_BAD_PARAMETER Some of the inputs were NULL RSA_ERR_UNSUPPORTED_HASH The Hash type passed doesn t correspond to any among the supported ones ERR_MEMORY_FAIL Not enough memory left available RSA ERR MODULUS TOO SHORT RSA modulus is too short to handle this hash type The structure pointed by P_pMemBuf must be properly initialized RSApubKey_stt data structure Structure type for RSA public key Table 95 RSApubKey_stt data structure Field name uint8_t pmModulus int32_t mModulusSize uint8_t pmExponent Description RSA Modulus Size of RSA Modulus RSA Public Exponent int32_t mExponentSize Size of RSA Public Exponent DoclD14989 Rev 4 2 UMO586 RSA algorithm 8 3 RSA Signature generation verification example tinclude crypt h int32_t main uint8_t uint8_t uint8_t uint8_t uint8_t ant32 t modulus 2048 8 Ji public exponent 3 0x01 0x00 0x01 digest CRL SHA256 SIZE signature 2048 8 private exponent 2048 8 retval RSAprivKey stt privKey RSApubKey stt pubKey Set values of private key privKey mExponentSize sizeof private exponent privKey pmExponent private exponent privKey mModulusSize sizeof modulus privKey pmModulus modulus Generate the signatu
15. transformation from ciphertext to plaintext is called deciphering or decryption Cipher key a private key that is used by the cipher to perform cryptographic operations The cipher key size is the important element that determines the security level of the encryption algorithm Plaintext raw data to be encrypted Inthe case of an encryption it is the input of the cipher Inthe case of a decryption it is the output of the cipher Ciphertext converted data result of plaintext encryption Symmetric cipher cipher that uses a single key for enciphering and deciphering Asymmetric cipher cipher that uses two keys one for enciphering and the other for deciphering DoclD14989 Rev 4 11 131 STM32 cryptographic library package presentation UMO586 2 STM32 cryptographic library package presentation 2 1 Architecture The library is built around a modular programming model ensuring e independencies between the components building the main application e easy porting on a large product range e use of integrated firmware components for other applications with minimum changes to common code The following figure provides a global view of the STM32 cryptographic library usage and interaction with other firmware components Figure 2 STM32 cryptographic library architecture Customer application Examples Middleware STM32 Cryptographic Library object code only 2 AES pm HASH Others Components Hardware
16. 2 131 DoclD14989 Rev 4 hy UMO586 Contents 425 AES AAA Decrypt Append function ananasa 37 4 2 6 AES AAA Decrypt Finish function snaa aana aaa aaee 38 4 3 AES GCM library functions ss EE RE we KG RE RE RE RAE ee Beas 39 4 3 1 AES GCM Encrypt Init function 41 4 3 2 AES_GCM_Header_Append function 43 4 3 3 AES_GCM_Encrypt_Append function 5 43 4 3 4 AES_GCM_Encrypt_Finish function anaana aaa 44 4 3 5 AES GCM Decrypt Init function anaa aana 45 4 3 6 AES GCM Decrypt Append function EE Ee Se ee ee 46 4 3 7 AES GCM Decrypt Finish function aasan 46 4 4 AES KeyWrap library functions 0 000 cee eee eee 47 4 4 1 AES KeyWrap Encrypt Init function aaaea 49 442 AES KeyWrap Encrypt Append function 50 44 3 AES KeyWrap Encrypt Finish function o oo o oooooo o 50 444 AES KeyWrap Decrypt Init function EE ee ee 51 44 5 AES KeyWrap Decrypt Append function 52 446 AES KeyWrap Decrypt Finish function saaa aaaea 52 4 5 AES CMAC library functions ie ee ee Ee ee ee ke ee ee 53 4 5 1 AES_CMAC Encrypt Init function o oooococoooooooooo 55 4 5 2 AES CMAC Encrypt Append function a 56 4 5 3 AES CMAC Encrypt Finish function Es ee ee 56 4 5 4 AES CMAC Decrypt Init function ooooocooooooooo 57 4 5 5
17. ERR MEMORY FAIL Not enough memory 1 This function keeps some value stored in membuf_stt pmBuf so when exiting this function membuf stt mUsed will be greater than it was before the call The memory is freed when ECDSAfreeSign is called 2 108 131 DoclD14989 Rev 4 UMO586 ECC algorithm 9 2 17 9 2 18 9 2 19 4 ECDSAfreeSign function Table 116 ECDSAfreeSign function Function name Prototype ECDSAfreeSign int32_t ECDSAfreeSign ECDSAsignature_stt P_ppSignature membuf_stt P_pMemBuf Behavior Free an ECDSA signature structure Parameter in out P_pSignature The ECDSA signature that will be freed in out P_pMemBuf Pointer to the membuf stt structure that currently stores the ECDSA signature internal values Return value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER P_pSignature NULL P_pMemBuf NULL ECDSAsetSignature function Table 117 ECDSAsetSignature function Function name Prototype ECDSAsetSignature int32_t ECDSAsetSignature ECDSAsignature_stt ECDSAsignValues_et P_pSignature P Rors const uint8 t P pValue int32 t P valueSize Behavior Set the value of the parameters one at a time of an ECDSAsignature stt Parameter Return value out P_pSignature The ECDSA signature whose one of the value will be set in P_RorS Flag selects if the param
18. P pIv Behavior Initialization for TDES Decryption in TTT Mode in out P_pTDESTTTctx TDES TTT context Parameter in P pKey Buffer with the Key fin P_plv Buffer with the IV Return value TDES SUCCESS Operation Successful TDES ERR BAD PARAMETER At least one parameter is a NULL pointer TDES ERR BAD CONTEXT Context not initialized with valid values see note 2 below This return value is only used with CBC algorithm 1 TTT is ECB or CBC 2 In ECB IV is not used so the value of P plv is not checked or used In CBC IV size must be already written inside the fields of P_pTDESCBCctx The IV size must be at least 1 and at most 16 to avoid the TDES ERR BAD CONTEXT return 1 P_pTDESTTTctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 2 P pTDESCBCctx mlvSize must be set with the size of the IV default CRL TDES BLOCK prior to calling this function 2 DoclD14989 Rev 4 UMO586 DES and Triple DES algorithms 3 3 5 TDES_TTT_Decrypt_Append function Table 18 TDES_TTT_Decrypt_Append Function name TDES TTT Decrypt Append int32 t TDES TTT Decrypt Append TDESTTTctx_stt P pTDESTTTCtx const uint8 t P pInputBuffer Prototype i int32 t P_inputSize uint8 t P_pOutputBuffer int32 t P_pOutputSize Behavior TDES Decryption in TTT mode in P_pTDESTTTctx DES TTT already initialized c
19. error status AES ERR BAD PARAMETER AES ERR BAD INPUT SIZE AES ERR BAD OPERATION AES SUCCESS AES Decryption Finalization API AES KeyWrap Decrypt Finish error status gt AES ERR BAD PARAMETER AUTHENTICATION SUCCESSFUL AUTHENTICATION FAILED 4 MS30071V1 2 UMO586 AES algorithm 4 4 1 AES KeyWrap Encrypt Init function Table 39 AES KeyWrap Encrypt Init Function name AES KeyWrap Encrypt Init int32 t AES KeyWrap Encrypt Init AESKWctx stt P_pAESKWctx Prototype P const uint8 t P pKey const uint8 t P pIv Behavior Initialization for AES KeyWrap Encryption in out P pAESKWctx AES Key Wrap context Parameter in P_pKey Buffer with the Key KEK in P_plv Buffer with the 64 bits IV AES SUCCESS Operation Successful AES ERR BAD PARAMETER At least one parameter is a NULL pointer AES ERR BAD CONTEXT Context not initialized with valid values Return value Note 1 P pAESKWctx mkKeySize see AESKWctx_stt must be set with the size of the key prior to calling this function Otherwise the following predefined values can be used CRL_AES128KEY CRL AES192 KEY CRL AES256 KEY 2 P_pAESKWctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 3 If hardware support is enabled DMA will not be used even ifE SK USE DMA is set insid
20. error status ECC ERR BAD PARAMETER ECC ERR BAD CONTEXT ECC ERR MISSING EC PARAMETER MATH ERR BIGNUM OVERFLOW SIGNATURE INVALID SIGNATURE VALID Deinitialization of the Signature API ECDSAfreeSign error_status ECC_ERR_BAD_PARAMETER ECC SUCCESS 4 Deinitialization of the ECC Point API ECCfreePoint ECC_ERR_BAD_PARAMETER ECC SUCCESS ECC ERR BAD CONTEXT Deinitialization of the Elliptic Curve API ECCfreeEC O ECC_ERR_BAD_PARAMETER ECC_ERR_BAD_CONTEXT DoclD14989 Rev 4 o MS30080V1 99 131 ECC algorithm UMO586 Figure 18 ECC key generator flowchart Begin Initialization of the Random Engine API RNGinit 3 ad error status RNG ERR BAD ADD INPUT SIZE RNG SUCCESS RNG ERR BAD ENTROPY SIZE Initialization of the Elliptic Curve API ECCinitEC error status ECC ERR BAD PARAMETER ECC ERR BAD CONTEXT ERR MEMORY FAIL Initialization of an ECC Point API ECCinitPoint ECC SUCCESS error status ECC ERR BAD PARAMETER ECC ERR BAD CONTEXT ECC SUCCESS ERR MEMORY FAIL ECC ERR BAD PARAMETER ECC ERR BAD PRIVATE KEY Initialization of the ECC Private Key API ECCinitPrivKey pi Deinitialization of the ECC Point API ECCfreePoint error status Do LL 3 ECC ERR BAD PARAMETER ECC ERR BAD CONTEXT ECC SUCCESS ERR MEMORY FAIL ECC ERR BAD PARAMETER ECC Key Gener
21. n a saasaa EE EE SE SE Ee ee ee ee ee ee 102 9 2 4 ECCfreePoint function 2 00 EE EE EE eee 103 9 2 5 ECCsetPointCoordinate function EE ee eee 103 9 2 6 ECCgetPointCoordinate function eee ee 104 9 2 7 ECCgetPointFlag function sssaaa aaau 104 9 2 8 ECCsetPointFlag function 0 0 0 eee 104 9 2 9 ECCcopyPoint function EE EE eee 105 9 2 10 ECCinitPrivKey function 105 9 2 11 ECCfreePrivKey function 0 0 0 cee eee 106 9 2 12 ECCsetPrivKeyValue function 0 0 0 eee 106 9 2 13 ECCgetPrivKeyValue function 0 00 cee eee 107 9 2 14 ECCscalarMul function Ee Ee ee 107 9 2 15 ECCsetPointGenerator function ssaa saaa aaae 108 9 2 16 ECDSAinitSign function EE Ee ee 108 9 2 17 ECDSAfreeSign function ii EE EE ee ee 109 9 2 18 ECDSAsetSignature function ii EE EE ee 109 9 2 19 ECDSAgetSignature function 0 0 0 ee 109 9 2 20 ECDSAverify function 0 eee 110 9 2 21 ECCvalidatePubKey function eee eae 111 9 2 22 ECCkeyGen function a 111 92 23 ECDSAsign function EE 00 ce 112 9 3 ECC example anaana aaan e 113 10 STM32 encryption library settings ooooooooomo 115 10 1 Configuration parameters si MERE EE EE RR EE RE Ed SE EE HER De EN NG 115 10 2 STM32 CryptoLibraryVersion ii se EE Ee ee ee eee 117 11 Cryptographic library performance and memory requirements 118
22. out P_pOutputSize Size of written output data in uint8_t Return value AES_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_OPERATION Append not allowed 4 3 7 AES_GCM_Decrypt_Finish function Table 37 AES_GCM_Decrypt_Finish Function name AES_GCM_Decrypt_Finish int32_t AES GCM Decrypt Finish AESGCMctx_stt P_pAESGCMctx Return value Prototype uint8 t P pOutputBuffer int32 t P_pOutputSize Behavior AES GCM Finalization during decryption the authentication TAG will be checked in out P pAESGCMctx AES GCM already initialized context out P pOutputBuffer Kept for API compatibility but won t be used should be Parameter NULL out P pOutputSize Kept for API compatibility must be provided but will be set to zero AES ERR BAD PARAMETER At least one parameter is a NULL pointer AES ERR BAD CONTEXT Context not initialized with valid values AUTHENTICATION SUCCESSFUL if the TAG is verified AUTHENTICATION FAILED if the TAG is not verified Note This function requires P_pAESGCMctx gt pmTag to be set to a valid pointer to the tag to be checked P_pAESGCMctx gt mTagSize to contain a valid value between 1 and 16 46 131 2 DoclD14989 Rev 4 UMO586 AES algorithm 4 4 4 AES KeyWrap library functions Table 38 describes the AES KeyWrap library T
23. 0 EE EE eee 71 ARCA Encrypt FINISH ss oa eg a oe ee ep A EA kd Sg ARO wad 71 ARC4 Decrypt II ias es as ia bias A a SO fd 72 ARC4 Decrypt Append cc 72 ARC4 Decrypt Finish 00000 e eee eee 73 RNG algorithm functions tees 75 RNGeS6ed AA A DA AA da ee ee aa 71 RNGrelnput sttstructreference EE 00 cece tee 77 RNGstate_stt struct reference nauuna nanana 77 RINGS ma EE MEER EA EE RM KAG BAG MA ME OER EE OE RAL DE gases aes 78 RNGstate_stt struct reference is EE 0002 cette 78 BRING MOC a a MEER eee pate eG AIN NG aaah cs O eae eat A Ee 79 RNGgenBytes 0 0 a ieee adi eve NENG ee eee ead Ga aed 79 RNGgenWords ss AP 80 HASH algorithm functions HHH MD5 SHA1 SHA224 or SHA256 82 HASH SHA1 algorithm functions 0 2 EE EE Ee ee eae 83 HAH Nita gi ie aa AA es Pe ede ee ae BSE 85 HASHctx_stt struct reference anaana ES See Se ee ee ee ee ee ee ee ee 85 HashFlags et mFlags is se EE Ee eee ee GE aaa aaa 85 HH Append ss a EE RE OE HE OR RO SADO NA EE 86 ARE RINS 20405 O RE aed AOS iors ee OE IE E 87 AMAG EA AE dae a OR ER Es ares ae OO EI N 87 HMACctx_stt struct reference EE SE SS ES Ge eee 88 HMAC HHH Append 0 e 88 HMAC HHH FiniSh wicca pus ada A an NG da Pee BALA RR RIESE ges 89 RSA algorithm functions 2 0 0 0 eee 91 RSA PKCS1v15 Sign function EE ESE Ee Ee eee 93 RSAprivKey stt data structure eee ee 93 membuf stt data structure
24. 103 ECCsetPointCoordinate function Function name ECCsetPointCoordinate int32 t ECCsetPointCoordinate ECpoint_stt P_pECPnt Prototype ECcoordinate_et P_Coordinate const uint8_t P_pCoordinateValue int32_t P_coordinateSize Behavior Set the value of one of coordinate of an ECC point in out P pECPnt The ECC point that will have a coordinate set in P_Coordinate Flag used to select which coordinate must be set see ECcoordinate_et Parameter in P_pCoordinateValue Pointer to an uint8_t array that contains the value to be set in P_coordinateSize The size in bytes of P_pCoordinateValue Return value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER One of the input parameters is invalid DoclD14989 Rev 4 103 131 ECC algorithm UMO586 9 2 6 Note 9 2 7 9 2 8 104 131 ECCgetPointCoordinate function Table 104 ECCgetPointCoordinate function Function name Prototype ECCgetPointCoordinate int32_t ECCgetPointCoordinate const ECpoint_stt P_pECPnt ECcoordinate_et P_Coordinate uint8_t P_pCoordinateValue int32_t P_pCoordinateSize Behavior Get the value of one of coordinate of an ECC point Parameter in P_pECPnt The ECC point from which extract the coordinate in P_Coordinate Flag used to select which coordinate must be retrieved see ECcoordinate_et out
25. 11 1 Symmetric key algorithms performance results 118 11 1 1 Software optimized for speed cee eee 119 11 1 2 Hardware enhanced 0 000 eee eee eee 121 ky DoclD14989 Rev 4 5 131 Contents UM0586 11 2 Authenticated encryption algorithms performance results 123 11 2 1 Software optimized for speed 2020 cece eee 123 11 2 2 Hardware enhanced ee ee ee ee 124 11 3 AES key Wrap results sis EES we EE EE DERS ED NANG DE OR WE ee 125 11 3 1 Software optimized for speed EE EE EE ee eee 125 11 3 2 Hardware enhanced EE Ee teas 125 11 4 HASH and HMAC algorithm results o o o oocoooooooo 126 11 4 1 Software optimized for speed eee eee 126 11 4 2 Hardware enhanced 0 0 eae 127 Io od oi cera OR EL EL ET N ES 128 11 6 EGO SUE is n see RR Ee Re Se AR ERA EA ER eN 129 12 Revision history css cosas 130 6 131 DoclD14989 Rev 4 kyy UMO586 List of tables List of tables Table 1 DES algorithm functions DDD ECB or CBC oocccccccccc ee 17 Table 2 DES ECB algorithm functions ee ee Ge ee ee ee ee ee ee ee 17 Table 3 DES DDD Encrypt IN EE Ee ee ee eae 19 Table 4 DESDDDctx_stt data structure es Ee SG Ge eee 19 Table 5 oK flags etmFlags iss nah LARA BE BAD asa PAA Re oe ROER EER RR a KANG 20 Table 6 DES DDD Encrypt Append 0 2020 21 Table
26. 7 DES DDD Encrypt Finish se Ee GE Ge ee ee ESE ee ee ee ee ee 21 Table 8 DES DDD Decrypt Init SS ea 22 Table 9 DES DDD Decrypt Append iis EE GEE GE GE Se ee ee ee ee 23 Table 10 DES DDD Decrypt Finish is EE EE EG ee ee Ge Ge tee 23 Table 11 TDES algorithm functions TTT ECB or CBO ie ee eee 24 Table 12 TDES ECB algorithm functions ii ee ee Ee ee ee ee tee 24 Table 13 TDES TTT Encrypt Nites eee r a eee 26 Table 14 TDESTTTctx stt data structure is EE EG ee ee ee ee eee 26 Table 15 TDES TTT Encrypt Append EE EE GE Ge ee ee ee ee ee ee ee ee 27 Table 16 TDES TTT Encrypt Finish iis es ee ee ee ee ee ee ee ee ee ee ee ee 27 Table 17 TDES TIT Decrypt Init tedavi samne ee ee es se ee ee eee 28 Table 18 TDES TTT Decrypt Append EE ES e 29 Table 19 TDES TTT Decrypt Finish is EE EE ee EG ee se ee eee 29 Table 20 AES algorithm functions AAA ECB CBC or CTR ei ke Ee ee ee ke ee 31 Table 21 AES ECB algorithm functions 32 Table 22 AES AAA Encrypt Init EE EE Ee Se ee ee ee eee 34 Table 23 AESAAActx stt data structure eens 34 Table 24 AES AAA Encrypt Append 222 2G 35 Table 25 AES AAA Encrypt Finish EE se EE Ee ee Ge ee ee ee ee ee ee 35 Table 26 AES AAA Decrypt Init EE Ee Ee Se ee ee eee 36 Table 27 AES AAA Decrypt Append iss EE EE e 37 Table 28 AES AAA Decrypt Finish iis EE Se ee tees 38 Ta
27. ARC4ctx mKeySize KeyLength Initialize the operation by passing the key Third parameter is NULL because ARC4 doesn t use any IV error status ARC4 Encrypt Init amp ARC4ctx ARC4 Key NULL check for initialization errors if error status ARC4 SUCCESS Encrypt Data error status ARC4 Encrypt Append amp ARC4ctx InputMessage InputMessageLength OutputMessage amp outputLength if error status ARC4 SUCCESS Write the number of data written OutputMessageLength outputLength Do the Finalization error status ARC4 Encrypt Finish amp ARC4ctx OutputMessage OutputMessageLength amp outputLength Add data written to the information to be returned OutputMessageLength outputLength return error status 2 DoclD14989 Rev 4 UMO586 RNG algorithm 6 6 1 6 2 RNG algorithm Description The security of cryptographic algorithms relies on the impossibility of guessing the key The key has to be a random number otherwise the attacker can guess it Random number generation RNG is used to generate an unpredictable series of numbers The random engine is implemented in software using a CTR_ DRBG based on AES 128 while a True RNG is done entirely by the hardware peripheral in the STM32F21x and STM32F41x The STM32 cryptographic library includes functions required to support the RNG module to generate a random
28. Behavior Set the value of an ECC private key object from a byte array in out P_pECCprivKey The ECC private key object to set in P_pPrivateKey Pointer to an uint8_t array that contains the value of the Parameter private key in P_privateKeySize The size in bytes of P_pPrivateKey Return value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER One of the input parameters is invalid ECC_ERR_BAD_PRIVATE_KEY Private Key uninitalized 106 131 2 DoclD14989 Rev 4 UMO586 ECC algorithm 9 2 13 ECCgetPrivKeyValue function Table 112 ECCgetPrivKeyValue function Function name ECCgetPrivKeyValue int32_t ECCgetPrivKeyValue const ECCprivKey_stt P pECCprivkey Prototype uint8 t P_pPrivateKey int32 t P pPrivateKeySize Behavior Get the private key value from an ECC private key object in P pECCprivKey The ECC private key object to be retrieved in P_pPrivateKey Pointer to an uint8 t array that contains the value of the Parameter private key in P_privateKeySize Pointer to an int that will contain the size in bytes of P_pPrivateKey ECC_SUCCESS Operation Successful ECC ERR BAD PARAMETER One of the input parameters is invalid Return value 1 The Coordinate size depends only on the size of the Order N of the elliptic curve Specifically if P pECctx 5mNsize is not a multiple of 4 then the size will be expand
29. CMAC Encrypt Finish error status AES ERR BAD PARAMETER AES SUCCESS AES ERR BAD CONTEXT 54 131 DoclD14989 Rev 4 Decryption Begin AES CMAC Decryptiorinitialization API AES_CMAC_Decrypt_lnit y error_status AES ERR BAD CONTEXT _AES ERR BAD PARAMETER AES SUCCESS AES CMAC Decryption API AES CMAC Decrypt Append error status AES ERR BAD PARAMETER AES ERR BAD INPUT SIZE AES ERR BAD OPERATION AES SUCCESS AES CMAC Decryption Finalization API AES CMAC Decrypt Finish error status gt AES ERR BAD PARAMETER AES ERR BAD CONTEXT AUTHENTICATION FAILED AUTHENTICATION SUCCESSFUL MS30072V1 2 UMO586 AES algorithm 4 5 1 AES CMAC Encrypt Init function Table 46 AES CMAC Encrypt Init Function name AES CMAC Encrypt Init int32 t AES CMAC Encrypt Init Prototype i AESCMACctx_stt P_pAESCMACctx Behavior Initialization for AES CMAC for Authentication TAG Generation Parameter in out P pAESCMACctx AES CMAC context AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values Note 1 P_pAESCMACctx pmKey see AESCMACctx_stt must be set with a pointer to the AES key before calling this function 2 P_pAESCMACctx mKeySize must be se
30. DRBG Table 144 Code size for ECC operations with speed optimization Constant data size Curve Code size byte byte Heap size byte ECC 192 15960 6040 1424 ECC 224 15960 6040 1564 ECC 256 15960 6040 1704 ECC 384 15960 6040 2264 ECC 521 15960 6040 2964 DoclD14989 Rev 4 129 131 Revision history UMO586 12 130 131 Revision history Table 145 Document revision history Date Revision Changes 13 Oct 2008 1 Initial release 41 Jul 2011 2 Added support for new algorithms Added support for STM32F1 F2 and L1 23 Aug 2013 3 Added support for STM32F4 FO and F3 13 Sep 2013 4 Publishing scope changed to Public Added part number STM32 CRYP LIB DoclD14989 Rev 4 2 UMO586 Please Read Carefully Information in this document is provided solely in connection with ST products STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections modifications or improvements to this document and the products and services described herein at any time without notice All ST products are sold pursuant to ST s terms and conditions of sale Purchasers are solely responsible for the choice selection and use of the ST products and services described herein and ST assumes no liability whatsoever relating to the choice selection or use of the ST products and services described herein No license express or impli
31. LENGTH OutputMessage amp outputLength if error_status TDES_SUCCESS Write the number of data written OutputMessageLength outputLength Do the Finalization error status TDES_ECB_Encrypt_Finish amp TDESctx OutputMessage OutputMessageLength amp outputLength Add data written to the information to be returned OutputMessageLength outputLength 2 30 131 DoclD14989 Rev 4 UMO586 AES algorithm 4 4 1 4 2 AES algorithm Description The advanced encryption standard AES known as the Rijndael algorithm is a symmetric cipher algorithm that can process data blocks of 128 bits using a key with a length of 128 192 or 256 bits The STM32 cryptographic library includes AES 128 bit 192 bit and 256 bit modules to perform encryption and decryption in the following modes e ECB Electronic Codebook mode e CBC Cipher Block Chaining with support for Ciphertext Stealing e CTR CounTer mode e CCM Counter with CBC MAC e GCM Galois Counter mode e CMAC e KEY WRAP These modes can run with the STM32F1 STM32L1 STM32F20x STM32F05x STM32F40x STM32F37x and the STM32F30x series using a software algorithm implementation The STM32F21x and STM32F41x series include cryptographic accelerators in particular a cryptographic Accelerator capable of encrypting decrypting with e AES in ECB CBC CTR with all three key sizes 128 192 256 bi
32. P_pCoordinateValue Pointer to an uint8_t array that will contain the returned coordinate out P_pCoordinateSize Pointer to an integer that will contain the size of the returned coordinate Return value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER One of the input parameters is invalid The Coordinate size depends only on the size of the Prime P of the elliptic curve Specifically if P_pECctx gt mPsize is not a multiple of 4 then the size will be expanded to be a multiple of 4 In this case P_pCoordinateValue will contain one or more leading zeros ECCgetPointFlag function Table 105 ECCgetPointFlag function Function name Prototype Behavior Parameter ECCgetPointFlag int32_t ECCgetPointFlag const ECpoint_stt P_pECPnt Reads the flag member of an Elliptic Curve Point structure in P_pECPnt The point whose flag will be returned Return value ECC_ERR_BAD_PARAMETER P_pECPnt NULL ECCsetPointFlag function Table 106 ECCsetPointFlag function Function name ECCsetPointFlag void ECCsetPointFlag ECpoint_stt P_pECPnt ECPntFlags_et Prototype P newFlag Behavior Set the flag member of an Elliptic Curve Point structure BE sies in out P pECPnt The point whose flag will be set out P_newFlag The flag value to be set 2 DoclD14989 Rev 4 UMO586 ECC algorithm 9 2 9 ECCcopyPo
33. a NULL pointer Return value 1 TTT is ECB or CBC Note This function won t write output data thus it can be skipped lt is kept for API compatibility 4 DoclD14989 Rev 4 29 131 DES and Triple DES algorithms UMO586 3 4 DES with ECB mode example Main DES enciphering and deciphering example include crypto h const uint8_t Plaintext PLAINTEXT_LENGTH 0x54 0x68 0x65 0x20 0x71 0x75 0x66 0x63 0x6B 0x20 0x62 0x72 0x6F 0x77 Ox6E 0x20 0x66 Ox6F 0x78 0x20 Ox6A 0x75 Ox6D 0x70 Key to be used for AES encryption decryption uint8_t Key CRL_TDES_KEY 0x01 0x23 0x45 0x67 0x89 OXAB OxCD OxEF 0x23 0x45 0x67 0x89 OxAB OxCD OxEF 0x01 0x45 0x67 0x89 OxAB OxCD OxEF 0x01 0x23 int32_t main Buffer to store the output data uint8_t OutputMessage PLAINTEXT LENGTH TDESECBctx stt TDESctx uint32 t error status TDES SUCCESS int32 t outputLength 0 Set flag field to default value TDESctx mFlags E SK DEFAULT Initialize the operation by passing the key Third parameter is NULL because ECB doesn t use any IV error status TDES ECB Encrypt Init amp TDESctx TDES Key NULL check for initialization errors if error status TDES SUCCESS Encrypt Data error status TDES_ECB_Encrypt_Append amp TDESctx Plaintext PLAINTEXT
34. a multiple of 16 A single final call with P inputSize not multiple of 16 is allowed Note This function shouldn t process the TAG which is part of the ciphertext according to CCM standard 4 6 7 AES CCM Decrypt Finish function Table 61 AES CCM Decrypt Finish Function name AES CCM Decrypt Finish int32 t AES CCM Decrypt Finish AESCCMctx stt P pAESCCMctx Prototype uint8 t P pOutputBuffer int32 t P pOutputSize Behavior AES CCM Finalization during decryption the authentication TAG will be checked in out P pAESCCMctx AES CCM context Parameter out P pOutputBuffer Won t be used out P pOutputSize Will contain zero AES ERR BAD PARAMETER At least one parameter is a NULL pointer AES ERR BAD CONTEXT pmTag should be set and mTagSize must be valid AUTHENTICATION SUCCESSFUL ifthe TAG is verified AUTHENTICATION FAILED if the TAG is not verified Return value Note This function requires P pAESCCMctx gt pmTag to be set to a valid pointer to the tag to be checked P_pAESCCMctx gt mTagSize to contain a valid value in the set 4 6 8 10 12 14 16 ky 66 131 DoclD14989 Rev 4 UMO586 AES algorithm 4 7 4 AES CBC enciphering and deciphering example The following code performs a CBC encryption with AES 128 of 1024 in 4 Append calls include crypto h int32_t main uint8_t key 128 CRL AES128 KEY 0 1 2 3 4 5 6 7 8 9 10 11
35. following predefined values can be used CRL AES128 KEY CRL_AES192 KEY CRL_AES256_KEY 2 P_pAESGCMctx mFlags must be set prior to calling this function Default value is E_SK_DEFAULT See SKflags_et for details 3 P pAESGCMctx mlvSize must be set with the size of the IV 12 is the only supported value prior to calling this function 4 P_pAESGCMctx mTagSize must be set with the size of authentication TAG that will be generated by the AES GCM Encrypt Finish 5 If hardware support is enabled DMA will not be used even if E SK USE DMA is set inside P pAESGCMctx gt mFlags as GCM is implemented with an interleaved operation and the AES engine is used one block at a time 6 Following recommendation by NIST expressed in section 5 2 1 1 of NIST SP 800 38D this implementation supports only IV whose size is of 96 bits DoclD14989 Rev 4 45 131 AES algorithm UMO586 4 3 6 AES_GCM_Decrypt_Append function Table 36 AES_GCM_Decrypt_Append Function name Prototype AES_GCM_Decrypt_Append int32_t AES GCM Decrypt Append AESGCMctx_stt P_pAESGCMctx const uint8_t P_pInputBuffer int32_t P_inputSize uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior AES GCM Decryption function Parameter in out P_pAESGCMctx AES GCM context in P_pInputBuffer Input buffer in P_inputSize Size of input data in uint8_t octets out P_pOutputBuffer Output buffer
36. in P_pSignCtx Pointer to an initialized ECDSAsignCtx_stt structure in out P_pMemBuf Pointer to the membuf_stt structure that will be used to store the internal values required by computation Return value ECC_SUCCESS Key Pair generated Successfully ERR_MEMORY_FAIL There s not enough memory ECC_ERR_BAD_PARAMETER One of input parameters is not valid RNG_ERR_UNINIT_STATE Random engine not initialized MATH_ERR_BIGNUM_OVERFLOW P_pPubKey was not properly initialized ECC_ERR_BAD_CONTEXT Some values inside P_pSignCtx are invalid ECC_ERR_MISSING_EC_PARAMETER P_pSignCtx must contain a p n Gx Gy This function requires that P_pSignCtx pmEC points to a valid and initialized EC_stt structure P_pSignCtx pmPrivKey points to a valid and initialized private key ECCprivKey_stt structure P_pSignCtx pmRNG points to a valid and initialized Random State RNGstate_stt structure 2 DoclD14989 Rev 4 UMO586 ECC algorithm 9 3 ECC example Initialize the EC_stt structure with the known values We also initialize to NULL and zero the unknown parameter ECparams mAsize sizeof ecc 160 a ECparams pmA ecc 160 a ECparams mPsize sizeof ecc 160 p ECparams pmP ecc 160 p ECparams pmN ecc 160 n ECparams mNsize sizeof ecc 160 n ECparams pmB NULL ECparams mBsize 0 ECparams pmGx NULL ECparams mGxsi
37. is a NULL pointer AES ERR BAD INPUT SIZE Only with CBC and ECB Size of input is less Return value than CRL_AES_BLOCK CBC or is not a multiple of CRL AES BLOCK ECB AES ERR BAD OPERATION Append not allowed DMA BAD ADDRESS Input or output buffer addresses are not word aligned DMA ERR TRANSFER Error occurred in the DMA transfer Prototype Parameter 1 AAA is ECB CBC or CTR Note This function can be called multiple times provided that P_inputSize is a multiple of 16 In CBC mode for a call where P_inputSize is greater than 16 and not multiple of 16 Ciphertext Stealing will be activated See CBC CS2 of lt SP 800 38 A Addendum gt NIST SP 800 384 Addendum In CTR mode a single final call with P_inputSize not multiple of 16 is allowed 4 2 3 AES_AAA Encrypt Finish function Table 25 AES_AAA Encrypt_Finish Function name AES_AAA Encrypt_Finish int32_t AES AAA Encrypt Finish AESAAActx stt P_pAESAAActx uint8 t P_pOutputBuffer int32 t P pOutputSize Prototype Behavior AES Finalization of AAA mode in out P pAESAAActx AES AAA already initialized context out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer containing size of written output data in bytes AES_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer Parameter Return value
38. is not a multiple of Return value CRL DES BLOCK or less than 8 DMA BAD ADDRESS Input output buffer address not word aligned DMA ERR TRANSFER Error occurred in the DMA transfer TDES ERR BAD OPERATION Append not allowed 1 TTT is ECB or CBC Note This function can be called multiple times provided that P inputSize is a multiple of 8 3 3 3 TDES TTT Encrypt Finish function Table 16 TDES TTT Encrypt Finish Function name TDES TTT Encrypt Finish int32 t TDES TTT Encrypt Finish TDESTTTctx stt P_pTDESTTTCEX Prototype uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior TDES Encryption Finalization of TTT mode in out P pTDESTTTctx TDES TTT already initialized context Parameter out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes TDES SUCCESS Operation Successful Return value TDES ERR BAD PARAMETER At least one parameter is NULL pointer 1 TTT is ECB or CBC Note This function won t write output data thus it can be skipped lt is kept for API compatibility 4 DoclD14989 Rev 4 27 131 DES and Triple DES algorithms UMO586 3 3 4 Note 28 131 TDES TTT Decrypt Init function Table 17 TDES TTT Decrypt Init Function name TDES TTT Decrypt Init 1 int32 t TDES TTT Decrypt Init TDESTTTctx_stt P_pTDESTTTCEX Prototype const uint8_t P_pKey const uint8 t
39. not initialized with valid values Note HHH is MD5 SHA1 SHA224 or SHA256 4 P_pHHHctx gt mTagSize must contain a valid value between 1 and CRL_HHH_SIZE DoclD14989 Rev 4 89 131 HASH algorithm UMO586 7 3 HASH SHA1 example A simple example of using SHA 1 is shown in the following example include crypt h int32_t main uint8 t input 141 uint8_t digest 20 int32_t outSize SHA 1 Context Structure SHAlctx stt SHAlctx st Set the size of the desired hash digest SHAlctx st mTagSize 20 Set flag field to default value SHAlctx st mFlags E HASH DEFAULT Initialize context retval SHA1 Init amp SHAlctx st 1f retval HASH SUCCESS E osar N retval SHA1_Append amp SHAlctx_st input sizeof input if retval HASH_SUCCESS to aba retval SHA1 Finish amp SHAlctx st digest amp outSize if retval HASH SUCCESS TC saad printf Resulting SHA 1 digest for i 0 i lt outSize i printf 02X digest i return 0 90 131 DoclD14989 Rev 4 ky UMO586 RSA algorithm 8 8 1 8 2 RSA algorithm Description This section describes RSA functions for signature generation validation These functions should only be used for signature verification modular exponentiation with a small exponent because the more efficient functions for modular exponentiation have been removed to save memory footprin
40. structure RNGinit_st pmEntropyData entropy_data RNGinit_st mEntropyDataSize sizeof entropy data RNGinit_st pmNonce nonce RNGinit_st mNonceSize sizeof nonce There is no personalization data in this case RNGinit_st mPersDataSize 0 RNGinit_st pmPersData NULL Init the random engine if RNGinit amp RNGinit st C_SW_DRBG_AES128 amp RNGstate 0 printf Error in RNG initialization n return 1 Generate retval RNGgenBytes amp RNGstate randombytes sizeof randombytes if retval 0 printf Error in RNG generation n return 1 return 0 DoclD14989 Rev 4 81 131 HASH algorithm UMO586 7 7 1 7 2 82 131 HASH algorithm Description This algorithm provides a way to guarantee the integrity of information verify digital signatures and message authentication codes It is based on a one way hash function that processes a message to produce a small length condensed message called a message digest The STM32 cryprogratphic library includes functions required to support HASH HMAC modules to guarantee the integrity of information using the following modes e MD5 e SHA 1 e SHA 224 e SHA 256 This algorithm can run with the STM32F1 STM32L1 STM32F20x STM32F05x STM32F40x STM32F37x and the STM32F30x series using a software algorithm implementation You can optimize the performance by using pure hardware accelerators
41. thanks to STM32F21x and STM32F41x devices Modes support by the hardware in STM32F21x and STM32F41x are e MD5 e SHA 1 e For other modes SHA 224 or SHA 256 runs using software algorithm implementation For HASH library settings refer to Section 10 STM32 encryption library settings For HASH library performance and memory requirements refer to Section 11 Cryptographic library performance and memory requirements HASH library functions Table 79 HASH algorithm functions HHH MD5 SHA1 SHA224 or SHA256 Function name Description HHH_Init Initialization a Hash algorithm Context Process input data and the HASH algorithm context that will HHH Append be updated Hash algorithm finish function produce the output HASH PAR Finish algorithm digest HMAC HHH Init Initialize a new HMAC of select Hash algorithm context Process input data and update a HMAC Hash algorithm context that will be updated HMAC HHH Finish function produce the output HMAC Hash algorithm tag HMAC HHH Append HMAC HHH Finish HHH represents the mode of operation of HASH algorithm DoclD14989 Rev 4 hy UMO586 HASH algorithm 4 The following mode of operation can be used for HASH algorithm e MD5 e SHA1 e SHA224 e SHA256 The next flowchart in Figure 14 describes the HHH algorithm For example if you want to use SHA1 for HASH algorithm you can call the functions Table 80 HASH SHA
42. 1 This function keeps values stored in membuf stt pmBuf so when exiting this function membuf stt mUsed is greater than it was before the call The memory is freed when ECCfreePrivKey is called ECCprivKey stt data structure Object used to store an ECC private key Must be allocated and unitized by ECCinitPrivKey and freed by ECCfreePrivKey Table 109 ECCprivKey stt data structure Field name Description BigNum stt pmD BigNum Representing the Private Key 4 DoclD14989 Rev 4 105 131 ECC algorithm UMO586 9 2 11 ECCfreePrivKey function Table 110 ECCfreePrivKey function Function name ECCfreePrivKey int32 t ECCfreePrivKey ECCprivKey stt P_ppECCprivKey Prototype membuf stt P_pMemBuf Behavior Free an ECC Private Key in out P_ppECCprivKey The private key that will be freed Parameter in out P_pMemBuf Pointer to the membuf_stt structure that currently stores the Ellitpic Curve Private Key internal value Return value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER P ppECCprivKey NULL P pMemBuf NULL ECC ERR BAD PRIVATE KEY Private Key uninitalized 9 2 12 ECCsetPrivKey Value function Table 111 ECCsetPrivKey Value function Function name ECCsetPrivKeyValue int32 t ECCsetPrivKeyValue ECCprivKey stt P pECCprivKey Prototype f const uint8_t P pPrivatekey int32 t P privateKeySize
43. 1 algorithm functions Function name HA1 Init Description Initialize a new SHA1 context HA1 Append SHA1 Update function process input data and update a SHA1ctx_stt SHA1 Finish function produce the output SHA1 digest S S SHA1_Finish H MAC SHAI Init Initialize a new HMAC SHA1 context HMAC SHA1 Append HMAC SHA1 Finish HMAC SHA1 Update function process input data and update a HMAC SHA1 context that will be updated HMAC SHA1 Finish function produce the output HMAC SHA1 tag DoclD14989 Rev 4 83 131 HASH algorithm UMO586 Figure 14 Hash HHH flowchart po HHH Initialization API HHH Init y error_status HMAC HHH Begin HMAC_HHH Initialization API HMAC_HHH_Init HASH_ERR_BAD_PARAMETER Gl HHH update context and hashing API HHH Append error status gt HASH_ERR_BAD_PARAMETER HASH_ERR_BAD_OPERATION DMA_BAD_ADDRESS used only with SHA1 and MD5 DMA_ERR_TRANSFER used only with SHA1 and MD5 HASH_SUCCESS HHH output digest API HHH_Finish error status gt HASH_ERR_BAD_PARAMETER HASH_ERR_BAD_CONTEXT HASH_SUCCESS v error status HASH ERR BAD PARAMETER HASH SUCCESS HMAC HHH update context and hashing API HMAC HHH Append error_status gt HASH_ERR_BAD_PARAMETER HASH_ERR_BAD_OPERATION DMA_BAD_ADDRESS used on
44. 115 131 STM32 encryption library settings UMO586 Table 123 Library build options continued Configuration Configuration parameter Description type name Enables RSA functions for signature generation validation Algorithms INCLUDE ECC Enables RSA functions INCLUDE MD5 Permits MD5 functions in the library INCLUDE SHA1 Permits SHA 1 functions in the library HASH Algorithms INCLUDE SHA224 Permits SHA 224 functions in the library INCLUDE SHA256 Permits SHA 256 functions in the library INCLUDE HMAC Enables HMAC for the selected hash algorithms i Enables the Deterministic Random Bit Generator DRBG INCLUDE DRBG AES128 Deterministic feature Requires AES128 with Encryption capabilities Random Bit CRL RANDOM REOUTRE xx CRL RANDOM REQUIRE RESEED implements the request Generator SEED REQ for reseed when using the DRBG too many times for security standards Selects the AES algorithm version with 522 bytes of look up CRL AES ALGORITHM 3 AES Algorithm tables slower than version 2 N a version Selects the AES algorithm version with 2048 bytes of look up CRL_AES_ALGORITHM tables faster than version 1 N N Speeds up RSA operation with private key at expense of RAM memory It can t be less than one and memory grows according to the formula RSA_WINDOW_SIZE 4 MemoryRequired 24 RSA_WINDOW_SIZE 1 20
45. 12 13 14 15 uint8 t iv CRL AES BLOCK 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 uint8 t plaintext 1024 uint8 t ciphertext 1024 outSize is for output size retval is for return value int32_t outSize retval AESCBCctx_stt AESctx_st The AES context Initialize Context Flag with default value AESctx_st mFlags E_SK_DEFAULT Set Iv size to 16 AESctx_st mIvSize 16 Set key size to 16 AESctx st mKeySize CRL AES128 KEY call init function retval AES CBC Encrypt Init amp AESctx st key iv if retval AES SUCCESS Lo ox 3 Loop to perform four calls to AES CBC Encrypt Append each processing 256 bytes for i 0 1 lt 1024 i 256 Encrypt i bytes of plaintext Put the output data in ciphertext and number of written bytes in outSize retval AES_CBC_Encrypt_Append amp AESctx_st plaintext 256 ciphertext amp outSize if retval AES SUCCESS le feats o Do the finalization call in CBC it will not return any output retval AES CBC Encrypt Finish amp context st ciphertext outSize amp outSize if retval AES SUCCESS o gt DoclD14989 Rev 4 67 131 ARCA algorithm UMO586 5 5 1 5 2 68 131 ARCA algorithm Description The ARCA also known as RC4 encryption algorithm was designed by Ronald Rivest of RSA It is used identically for encrypti
46. 399 2048 65537 6 195 481 2048 Private Key 228 068 226 The following table shows the required code size and heap note that dynamically allocated memory is a requirement because the private key operation is optimized with pre calculations which impacts performance and heap usage Code size is independent from the key size or the exponent used Table 142 Code size required by RSA algorithms Key Size Code size byte Constant data size byte Heap size byte 1024 6654 0 2132 2048 6654 0 4052 DoclD14989 Rev 4 UMO586 Cryptographic library performance and memory requirements 11 6 ECC results Table 143 shows required clock cycles for ECC operations executed on all the NIST approved prime curves The results are provided for software compiled with speed optimization Table 143 Number of cycles for ECC operations with for speed optimization Operations ECC 192 ECC 224 ECC 256 ECC 384 ECC 521 Init Key Generation 7 400 421 9 849 334 12713277 29 180 298 62 531 611 Signanture 7720020 10414487 13102 239 29 673 252 64 664 144 Verification 14 716 374 19558 528 24 702 099 58 986 725 124 393 892 Code size is independent from the key size or the exponent used Table 144 shows the required code size and heap memory includes DRBG AES 128 required for ECDSA Signature Generation This data groups together all three functionalities and the required
47. 4 AES modes CTR and CMAC do not have a proper decryption mode like ARC4 In these cases decryption works exactly like encryption To calculate the number of cycles needed to perform each operation mode Cycles Init key cycle Init message cycle Process block of data cycle number of blocks The code size required by these algorithms is shown in Table 126 on page 120 DoclD14989 Rev 4 ky UMO586 Cryptographic library performance and memory requirements 11 1 1 4 Software optimized for speed Table 125 shows the clock cycles needed by each algorithm to process a block of data Table 125 Performance of symmetric key encryption algo optimized for speed Algorithm mode Operation Init key Init message Process block of data Encryption 19 539 205 1 553 DES ECB Decryption 19 542 219 1 554 Encryption 19 548 390 1 556 DES CBC Decryption 19 548 402 1578 Encryption 58 638 215 4 569 TDES ECB Decryption 58 629 200 4 565 Encryption 58 650 469 4 569 TDES CBC Decryption 58 650 395 4 587 Encryption 639 622 1 622 AES 128 CBC Decryption 2 928 630 1 644 Encryption 630 316 1 885 AES 192 ECB Decryption 3411 311 1 936 Encryption 636 735 1 909 AES 192 CBC Decryption 3 432 702 1975 Encryption 837 340 2 183 AES 256 ECB Decryption 4 131 316 2 204 Encryption 843 632 2 180 AES 256 CBC Decryption 4 155 694 2 243 Encryp
48. A 1 Zong E SHA 224 SHA 256 HMAC SHA 224 ee di HMAC SHA 256 126 131 DoclD14989 Rev 4 ky UMO586 Cryptographic library performance and memory requirements 11 4 2 Hardware enhanced Table 139 Clock cycles required by HASH HMAC algorithms with HW acceleration Algorithm Init message Block of data 64 bytes Finalization MD5 330 119 374 SHA 1 308 135 419 HMAC MD5 496 119 596 HMAC SHA 1 489 135 686 Table 140 Code size required by HASH HMAC algorithms Algorithm Code size byte Constant data size byte MD5 SHA 1 1166 0 SSHA 224 SHA 256 2098 880 MD5 SHA 1 HMAC MDS 2282 0 HMAC SHA 1 SHA 224 HMAC SHA 224 3458 s o HMAC SHA 256 DoclD14989 Rev 4 127 131 Cryptographic library performance and memory requirements UMO586 11 5 128 131 RSA results RSA operates with different key sizes and different exponents The time required by the operation depends on these values In this section we provide the results for the three most common public key exponents which are 3 17 and 65537 Considered key sizes are 1024 and 2048 bit The following table shows RSA algorithm performance with speed optimization Table 141 RSA performance with optimization for speed Key size Exponent Clock cycles 1024 3 1 213 793 1024 17 1 284 982 1024 65537 1573 079 1024 Private Key 30 627 432 2048 3 4 839 035 2048 17 5 109
49. AES CMAC Decrypt Append function se ee ee eie 58 4 5 6 AES CMAC Decrypt Finish function EE EE se ee ee 58 4 6 AES CCM library functions ss se a a ha BAD 59 4 6 1 AES CCM Encrypt Init function a a sssaaa aaaea 61 4 6 2 AES_CCM_Header_Append function iis se Ee ee eie 63 4 6 3 AES CCM Encrypt Append function EE Ee ee ee ee 63 4 6 4 AES CCM Encrypt Finish function 2 asana aaae 64 4 6 5 AES CCM Decrypt Init function EE EE EE Se ee ee 65 4 6 6 AES CCM Decrypt Append function aaaea aa 66 4 6 7 AES CCM Decrypt Finish function o 66 4 7 AES CBC enciphering and deciphering example 67 5 ARCA algoritmes Es eso ica EE RED RR ENE 68 5 1 Description association id e e Rd ante ds 68 kyy DoclD14989 Rev 4 3 131 Contents UMO586 5 2 ARCA library functions asd sms a a de ad 68 5 2 1 ARC4 Encrypt Init function ee ee ee ee ee 70 5 2 2 ARC4 Encrypt Append function aaaea EE EE EE ee eee 70 5 2 3 ARC4 Encrypt Finish function ee EE EE EE Se cee ee ee 71 5 2 4 ARC4_Decrypt_Init function EE EE EE EE Ee EE ee eie 72 5 2 5 ARC4 Decrypt Append function EE EE EE EE EE Ee ee ee 72 5 2 6 ARC4 Decrypt Finish function aaas saaa aaaea 73 5 3 ARC4 example peaa EE EE EE EE EE ee Ee ss EE ee ee 74 6 RNG algoritmo tarro NANG NG tarse 75 6 1 Descrip ici A oa 75 6 2 RNG library functions o 2G maa mGA direis as da Pee e
50. AES256_KEY 2 P_pAESCCMctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 3 P_pAESCCMctx mNonceSize must be set with the size of the CCM Nonce Possible values are 7 8 9 10 11 12 13 4 P_pAESCCMctx mTagSize must be set with the size of authentication TAG that will be generated by the AES_CCM_Encrypt_Finish Possible values are values are 4 6 8 10 12 14 16 5 P_pAESCCMctx mAssDataSize must be set with the size of the Associated Data i e Header or any data that will be authenticated but not encrypted 6 P_pAESCCMctx mPayloadSize must be set with the size of the Payload i e Data that will be authenticated and encrypted 7 In CCM standard the TAG is appended to the Ciphertext In this implementation for API compatibility with GCM the user must supply a pointer to AES CCM Encrypt Finish that will be used to output the authentication TAG 8 If hardware support is enabled DMA will not be used even if E SK USE DMA is set inside P pAESCCMctx gt mFlags as CCM is implemented with an interleaved operation and the AES engine is used one block at a time ky DoclD14989 Rev 4 61 131 AES algorithm UMO586 AESCCMctx_stt data structure Table 55 AESCCMctx_stt data structure Field name Description Unique ID of this AES CCM Context Not used in current uint32 t mContextId E implementation 32 bit mFlags used to perform keyschedule see SKflags et
51. Cparams if retval 0 printf ECCscalarMul returned d n retval return 1 Now PubKey contains the result point we can get its coordinates through ECCgetPointCoordinate KP E_ECC_POINT_COORDINATE_X pubKeyX amp Xsize E ECCgetPointCoordinate KP E ECC POINT COORDINATE Y pubKeyY amp Ysize Finally we free everything we initialized ECCfreePrivKey privkey ECCfreePoint G ECCfreePoint PubKey ECCfreeEC amp ECparams 2 114 131 DoclD14989 Rev 4 UMO586 STM32 encryption library settings 10 STM32 encryption library settings The flexibility of the Cryptographic library allows the user to select just the algorithm and the modes needed and the necessary object code will be generated Customization leads to a very small code size 10 1 Configuration parameters Table 123 describes the configuration parameters used to build the STM32 cryprtographic library These parameters are defined in the file inc config h Table 123 Library build options Configuration Configuration parameter Description type name Specifies the memory representation of the platform Endianness CRL_ENDIANNESS 1 CRL_ENDIANNESS 1 for LITTLE ENDIAN CRL_ENDIANNESS 2 for BIG ENDIAN MISALIGNED CRL_CPU_SUPPORT_MISAL When set to 1 this flag improves the performance of AES when read write i IGNED used through hig
52. D_PARAMETER P_pRandomState NULL RNG_ERR_UNINIT_STATE Random engine not initialized 6 2 4 RNGgenBytes function Table 77 RNGgenBytes Function name RNGgenBytes int32_t RNGgenBytes RNGstate_stt P pRandomState Return value Note The user has to be careful to not invoke this function more than 2148 times without calling Prototype const RNGaddInput_stt P_pAddInput uint8_t P_pOutput int32 t P OutLen Behavior Generation of pseudorandom octets to a buffer in out P pRandomState The current state of the random engine in P_pAddInput Optional Additional Input can be NULL Parameter lin P_p E P PUNA in P pOutput The output buffer in P OutLen The number of random octets to generate RNG SUCCESS Operation Successful RNG ERR BAD PARAMETER P pRandomState NULL or P pOutput NULL 88 P_OutLen gt 0 RNG_ERR_UNINIT_STATE Random engine not initialized RNG_ERR_RESEED_NEEDED Returned only if it s defined CRL_RANDOM_REQUIRE_RESEED The count of number of requests between reseed has reached its limit Reseed is necessary the RNGreseed function 4 DoclD14989 Rev 4 RNG algorithm UM0586 6 2 5 80 131 RNGgenWords function Table 78 RNGgenWords Function name RNGgenWords int32 t RNGgenWords RNGstate_stt P pRandomState Prototype const RNGaddInput_stt P_pAddInput uint32_t P_pWordBuf int32 t P BufSi
53. E eee OE Ta ee eo ee 15 3 DES and Triple DES algorithms ooooooomommmmmom o 16 3 1 A Fe oie EO eee MI EE OK 16 3 2 DES library functions se tl dE ER od a KA A EAN 17 3 2 1 DES DDD Encrypt Init function ooo 19 3 2 2 DES DDD Encrypt Append function se Ee ee eie 21 3 2 3 DES DDD Encrypt Finish function oo 21 3 2 4 DES DDD Decrypt Init function 2 0000 22 3 2 5 DES DDD Decrypt Append function 23 3 2 6 DES DDD Decrypt Finish function 2 23 3 3 TDES library functions as soe nde deen RE WG HUN N DERS BEHEER 24 3 3 1 TDES TTT Encrypt Init function EE EE se ee ee ee ese 26 3 3 2 TDES TTT Encrypt Append function ie se EE EE ees se 27 3 3 3 TDES TTT Encrypt Finish function aaaea 27 3 3 4 TDES TTT Decrypt Init function saaa oo 28 3 3 5 TDES TTT Decrypt Append function a 29 3 3 6 TDES TTT Decrypt Finish function 0 2 0000 eeu 29 3 4 DES with ECB mode example eee eee 30 4 AES algorithM Didi AA NENG US BE IE da 31 4 1 Description ss dada da id ad a da 31 4 2 AES library functions ECB CBC and CTR 0 05 31 4 2 1 AES AAA Encrypt Init function 000000 eee 34 4 2 2 AES_AAA Encrypt_Append function aaa aaae 35 4 2 3 AES AAA Encrypt Finish function o 35 4 2 4 AES AAA Decrypt Init function 0000000505 36
54. ECCvalidatePubKey Prototype int32_t ECCvalidatePubKey const ECpoint_stt P_pECCpubKey const EC_stt P_pECctx membuf_stt P_pMemBuf Behavior Checks the validity of a public key in pECCpubKey The public key to be checked Parameter in P_pECctx Structure describing the curve parameters in out P_pMemBuf Pointer to the membuf_stt structure that will be used to store the internal values required by computation ECC_SUCCESS pECCpubKey is a valid point of the curve ECC_ERR_BAD_PUBLIC_KEY pECCpubKey is not a valid point of the curve Return value ECC_ERR_BAD_PARAMETER One of the input parameter is NULL ECC_ERR_BAD_CONTEXT One of the values inside P_pECctx is invalid ERR_MEMORY_FAIL Not enough memory 1 This function does not check that PubKey group_order infinity_point This is correct assuming that the curve s cofactor is 1 9 2 22 ECCkeyGen function Table 121 ECCkeyGen function Function name ECCkeyGen int32_t ECCkeyGen ECCprivKey_stt P_pPrivKey ECpoint_stt P_pPubKey Prototype RNGstate_stt P_pRandomState const EC_stt P_pECctx membuf_stt P_pMemBuf Behavior Generate an ECC key pair out P_pPrivKey Initialized object that will contain the generated private key out P_pPubKey Initialized point that will contain the generated public key in P_pRandomState The random engine current state Parameters
55. ECctx gt mNsize is not a multiple of 4 then the size is expanded to be a multiple of 4 In this case P_pValue contains one or more leading zeros 9 2 20 ECDSAverify function Table 119 ECDSAverify function Function name Prototype ECDSAverify int32_t ECDSAverify const uint8_t P_pDigest int32_t P_digestSize const ECDSAsignature_stt P_pSignature const ECDSAverifyCtx_stt P_pVerifyCtx membuf_stt P pMemBuf Behavior ECDSA signature verification with a digest input Parameter in P_pDigest The digest of the signed message in P_digestSize The mSize in bytes of the digest in P_pSignature The public key that will verify the signature in P_pVerifyCtx The ECDSA signature that will be verified in out P_pMemBuf Pointer to the membuf_stt structure that will be used to store the internal values required by computation I I I Return value ERR_MEMORY FAIL There s not enough memory ECC_ERR_BAD_PARAMETER ECC_ERR_BAD_CONTEXT ECC_ERR_MISSING_EC_PARAMETER MATH_ERR_BIGNUM_OVERFLOW SIGNATURE_INVALID SIGNATURE_VALID Note This function requires that P_pVerifyCtx pmEC points to a valid and initialized EC_stt structure P_pVerifyCtx pmPubKey points to a valid and initialized public key ECpoint_stt structure 110 131 2 DoclD14989 Rev 4 UMO586 ECC algorithm 9 2 21 ECCvalidatePubKey function Table 120 ECCvalidatePubKey function Function name
56. ES key wrap unwrap with HW acceleration 0020 e eee eee eee 125 Table 136 Code size for AES key wrap unwrap with HW acceleration 125 Table 137 Clock cycles for HASH and HMAC algorithms optimized for speed 126 Table 138 Clock cycles for HASH and HMAC algorithms with SW acceleration 126 Table 139 Clock cycles required by HASH HMAC algorithms with HW acceleration 127 Table 140 Code size required by HASH HMAC algorithms Ee Ee ee ee eee 127 Table 141 RSA performance with optimization for speed 000 ee eee eee 128 Table 142 Code size required by RSA algorithms eae 128 Table 143 Number of cycles for ECC operations with for speed optimization 129 Table 144 Code size for ECC operations with speed optimization 129 Table 145 Document revision history ii EE EE EE ee ene 130 Ly DoclD14989 Rev 4 9 131 List of figures UMO586 List of figures Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 Figure 10 Figure 11 Figure 12 Figure 13 Figure 14 Figure 15 Figure 16 Figure 17 Figure 18 10 131 Block diagram Of a COMMON cipher eee eae 11 STM32 cryptographic library architecture oooocccoocccocoooo ee ee ee ee 12 STM32 cryptographic library package organization EE EE EE EE Ee eee ee 13 Project fold
57. ETER SEER AES ERR BAD OPERATION AES CCM Encryption API AES_CCM_Encrypt_Append AES CCM Decryption Finalization API AES_CCM_Decrypt_Finish error status gt AES ERR BAD PARAMETER AES ERR BAD PARAMETER AES ERR BAD OPERATION AES ERR BAD CONTEXT AUTHENTICATION FAILED AUTHENTICATION SUCCESSFUL error status AES SUCCESS AES CCM Encryption Finalization API AES CCM Encrypt Finish a error status End AES ERR BAD PARAMETER AES SUCCESS MS30073V1 2 60 131 DoclD14989 Rev 4 UMO586 AES algorithm 4 6 1 AES CCM Encrypt Init function Table 54 AES CCM Encrypt Init Function name AES CCM Encrypt Init int32 t AES CCM Encrypt Init AESCCMctx stt P pAESCCMctx Prototype Na const uint8_t P_pKey const uint8_t P_pNonce Behavior Initialization for AES CCM encryption in out P pAESCCMctx AES CCM context Parameter in P_pKey Buffer with the Key in P_pNonce Buffer with the Nonce AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values Note 1 P_pAESCCMctx mKeySize see ref AESCCMctx_stt must be set with the size of the key prior to calling this function Otherwise the following predefined values can be used CRL AES128 KEY CRL_AES192 KEY CRL_
58. Even without the appropriate hardware evaluation board this layer allows you to rapidly get started with a brand new STM32 cryptographic library 2 2 Package organization The library is supplied in a zip file The extraction of the zip file generates one folder STM32_Cryptographic_Lib_VX Y Z which contains the following subfolders Figure 3 STM32 cryptographic library package organization di STM32 Cryptographic Lib VX Y Z dy _htmresc de Libraries di CMSIS p STM32_Cryptographic_Library W binary dy EWARM Ly MK ARM We inc Lo STM32F0xx_StdPeriph_Driver Le STM32F2xx StdPeriph Driver ie STM32F4xx_StdPeriph_Driver de STM32F10x_StdPeriph_Driver d STM32F30x StdPeriph Driver Le STM32F37x StdPeriph Driver do STM32LIxx StdPeriph Driver p Project Utilities di STM32 EVAL Note VX Y Z refers to the library version ex V1 0 0 The STM32 cryptographic library package consists of three main folders Libraries Projects and Utilities ky DoclD14989 Rev 4 13 131 STM32 cryptographic library package presentation UMO586 2 2 1 14 131 Libraries This folder contains two subfolders CMSIS files and STM32 cryptographic library followed by drivers for STM32 Standard Peripheral CMSIS subfolder contains STM32FOxx STM32F2xx STM32F4xx STM32F10x STM32F30x STM32F37x and STM32L1xx CMSIS files STM32_Cryptographic_library contains two subfolders binary and inc binary contains five STM32 cryptographic libraries
59. GCM_Encrypt_Append AES GCM encryption function AES_GCM_Encrypt_Finish AES GCM finalization during encryption this will create the Authentication TAG AES_GCM_Decrypt_Init Initialization for AES GCM decryption AES_GCM_Decrypt_Append AES GCM decryption function AES_GCM_Decrypt_Finish AES GCM finalization during decryption the authentication TAG will be checked The following flowchart describes the AES_GCM algorithm DoclD14989 Rev 4 39 131 AES algorithm UMO586 Figure 8 AES GCM flowchart Encryption Decryption Ba AES GCM Encryption Initialization API AES GCM Encrypt Init AES GCM Decryption Initialization API AES_GCM_Decrypt_Init y y error_status error_status AES_ERR_BAD_CONTEXT AES ERR BAD PARAMETER AES SUCCESS EE mha AES SUCCESS 7 AES ERR BAD PARAMETER AES GCM Header processing API AES GCM Decryption API AES GCM Header Append AES GCM Decrypt Append error status error status AES ERR BAD PARAMETER RES ERR PAD OPERATION AES SUCCESS AES ERR BAD PARAMETER gui AES ERR BAD OPERATION AES SUCCESS AES GCM Encryption API AES GCM E t A d kaw SA aa AES GCM Decryption Finalization API AES GCM Decrypt Finish error status gt AES ERR BAD PARAMETER AES ERR BAD CONTEXT AUTHENTICATION FAILED error status AES SUCCESS AES_ERR_BAD_PARAMETER
60. I ARC4 Encrypt Append error status ARC4 ERR BAD PARAMETER ARC4 ERR BAD OPERATION ARC4 SUCCESS ARC4 Encryption Finalization API ARC4 Encrypt Finish gt error_status ARC4_ERR_BAD_PARAMETER ARC4_SUCCESS 4 gt Decryption ARC4 Decryption Initialization API ARC4_Decrypt_Init y error_status ARC4_ERR_BAD_CONTEXT Bisa ARC4 ERR BAD PARAMETER ARC4 Decryption API ARC4 Decrypt Append error status Lg ARC4 ERR BAD PARAMETER ARC4 ERR BAD OPERATION ARC4 SUCCESS ARC4 Decryption Finalization API ARC4 Decrypt Finish 4 error_status gt ARC4_ERR_BAD_PARAMETER ARC4_SUCCESS MS30074V1 DoclD14989 Rev 4 69 131 ARCA algorithm UMO586 5 2 1 ARC4 Encrypt Init function Table 63 ARC4 Encrypt Init Function name ARC4 Encrypt Init int32 t ARC4 Encrypt Init ARC4ctx_stt P_pARC4ctx Prototype const uint8 t P_pKey const uint8 t P pIv Behavior Initialization for ARC4 algorithm in out P pARC4ctx ARC4 context Parameter in P_pKey Buffer with the Key in P_plv Buffer with the IVO Return value ARC4 SUCCESS Operation Successful ARC4 ERR BAD PARAMETER At least one parameter is a NULL pointer ARC4 ERR BAD CONTEXT Context not initialized with valid value See note 1 1 In ARC4 the IV
61. Initialization for DES Decryption in ECB mode ECB _Decrypt_Append DES Decryption in ECB mode ECB Decrypt_Finish DES Decryption Finalization in ECB mode Figure 5 describes the DES algorithm 4 DoclD14989 Rev 4 17 131 DES and Triple DES algorithms UMO586 Figure 5 DES DDD flowchart 18 131 Encryption Begin DES Encryption Initialization API DES_DDD Encrypt Init error_status Decryption Begin DES Decryption Initialization API DES DDD Decrypt Init DES ERR BAD CONTEXT used only with CBC DES ERR BAD PARAMETER DES SUCCESS DES Encryption API DES DDD Encrypt Append y error_status DES_ERR_BAD_CONTEXT used only with CBC DES_ERR_BAD_PARAMETER DES_SUCCESS DES Decryption API DES DDD Decrypt Append error status DES ERR BAD PARAMETER DES ERR BAD INPUT SIZE DES ERR BAD OPERATION DMA BAD ADDRESS DMA ERR TRANSFER DES SUCCESS DES Encryption Finalization API DES_DDD _Encrypt _ Finish error_status error status DES ERR BAD PARAMETER DES ERR BAD INPUT SIZE DES ERR BAD OPERATION DMA BAD ADDRESS DMA ERR TRANSFER DES SUCCESS DES Decryption Finalization API DES DDD Decrypt Finish DES ERR BAD PARAMETER DES SUCCESS DoclD14989 Rev 4 error status DES ERR BAD PARAMETER DES
62. ORY FAIL RSA ERR MODULUS TOO SHORT SIGNATURE VALID MS30077V1 2 UMO586 RSA algorithm 8 2 1 RSA_PKCS1v15_Sign function Table 91 RSA_PKCS1v15_Sign function Function name RSA PKCS1v15 Sign int32 t RSA PKCS1v15 Sign const RSAprivKey_stt P pPrivKey const uint8 t P pDigest Prototype hashType et P hashType uint8 t P pSignature membuf stt P pMemBuf Behavior PKCS 1v1 5 RSA Signature Generation Function in P_pPrivKey RSA private key structure RSAprivKey stt in P pDigest The message digest that will be signed in P hashType Identifies the type of Hash function used out P_pSignature The returned message signature in P_pMemBuf Pointer to the membuf_stt structure that will be used to store the internal values required by computation RSA SUCCESS Operation Successful RSA ERR BAD PARAMETER Some of the inputs were NULL RSA ERR UNSUPPORTED HASH Hash type passed not supported RSA ERR BAD KEY Some member of structure P_pPrivKey were invalid ERR MEMORY FAIL Not enough memory left available RSA ERR MODULUS TOO SHORT RSA modulus too short for this hash type Parameter Return value 1 P pSignature has to point to a memory area of suitable size modulus size The structure pointed by P pMemBuf must be properly initialized RSAprivKey_stt data structure Structure type for RSA private key Table 92 RSAprivKey stt dat
63. OutputBuffer Buffer that will contain the digest out P pOutputSize Size of the data written to P pOutputBuffer HASH SUCCESS Operation Successful HASH ERR BAD PARAMETER At least one parameter is a NULL pointer HASH ERR BAD CONTEXT P pHHHctx not initialized with valid values see the notes below Return value Note 1 HHH is MD5 SHA1 SHA224 or SHA256 2 P_pSHA1ctx gt mTagSize must contain a valid value between 1 and CRL HHH SIZE before calling this function 7 2 4 HMAC HHH Init function Table 86 HMAC HHH Init Function name HMAC HHH Init int32 t HMAC HHH Init HMAC HHHctx stt Prototype P_pHMAC_HHHctx Behavior Initialize a new HMAC HHH context Parameter in out P pHMAC HHHctx The context that will be initialized HASH_SUCCESS Operation Successful Return value HASH_ERR_BAD_PARAMETER Parameter P pHMAC HHHctx is invalid Note 1 HHH is MD5 SHA1 SHA224 or SHA256 2 P_pHMAC_HHHctx pmKey see HMAC HHHctx stt must be set with a pointer to HMAC key before calling this function 3 P_pHMAC_HHHctx mKeySize see HMAC_HHHctx_stt must be set with the size of the key in bytes prior to calling this function 4 P_pHMAC_HHHctx mFlags must be set prior to calling this function Default value is E_HASH_DEFAULT See HashFlags_et for details 5 P pHMAC HHHctx mTagSize must be set with the size of the required authentication TAG that will be generated b
64. P_pOutputSize Behavior AES KeyWrap UnWrapping function Parameter in out P pAESKWctx AES KeyWrap context in P_pInputBuffer Input buffer containing the Key to be unwrapped in P_inputSize Size of input data in uint8_t octets out P_pOutputBuffer Output buffer out P_pOutputSize Size of written output data in uint8_t Return value AES_SUCCESS Operation Successful AES ERR BAD PARAMETER At least one parameter is a NULL pointer AES ERR BAD OPERATION Append not allowed AES ERR BAD INPUT SIZE P inputSize must be a non zero multiple of 64 bits and at maximum 264 1 This function can be called only once passing in it the whole Wrapped Key 2 P_inputSize must be a non zero multiple of 64 bits and be a maximum of 264 or AES_ERR_BAD_INPUT_SIZE is returned 3 P_pOutputBuffer must be at least 8 bytes smaller than P_pInputBuffer AES KeyWrap Decrypt Finish function Function name Table 44 AES KeyWrap Decrypt Finish AES KeyWrap Decrypt Finish int32 t AES KeyWrap Decrypt Finish AESKWctx_stt P_pAESKWctx Prototype uint8_t P pOutputBuffer int32 t P pOutputSize Behavior AES KeyWrap Finalization during Decryption the authentication will be checked in out P pAESKWctx AES KeyWrap context Parameter out P pOutputBuffer Won t be used out P pOutputSize Will contain zero Return value Result
65. R AUTOMOTIVE AUTOMOTIVE SAFETY OR MEDICAL INDUSTRY DOMAINS ACCORDING TO ST PRODUCT DESIGN SPECIFICATIONS PRODUCTS FORMALLY ESCC QML OR JAN QUALIFIED ARE DEEMED SUITABLE FOR USE IN AEROSPACE BY THE CORRESPONDING GOVERNMENTAL AGENCY Resale of ST products with provisions different from the statements and or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever any liability of ST ST and the ST logo are trademarks or registered trademarks of ST in various countries Information in this document supersedes and replaces all information previously supplied The ST logo is a registered trademark of STMicroelectronics All other names are the property of their respective owners 2013 STMicroelectronics All rights reserved STMicroelectronics group of companies Australia Belgium Brazil Canada China Czech Republic Finland France Germany Hong Kong India Israel Italy Japan Malaysia Malta Morocco Philippines Singapore Spain Sweden Switzerland United Kingdom United States of America www st com ky DoclD14989 Rev 4 131 131
66. RAMETER ECC SUCCESS HASH SUCCESS HASH ERR BAD CONTEXT y PJ 4 Both signature values exported Initialization of the Random Engine API RNGinit No then repeat twice to retrieve both signature values Yes Bi gt O LL error status Deinitialization of the Signature API RNG_ERR_BAD_ADD_INPUT_SIZE EGDEAf22e reeSign RNG SUCCESS RNG ERR BAD ENTROPY SIZE igi v Initialization of the Elliptic Curve API initEC 4 error status ECC ERR BAD PARAMETER ECC SUCCESS 4 v lt error status PP si Deinitialization of the ECC Private Key API ECC_ERR_BAD_PARAMETER ECCfreePrivateKey ECC SUCCESS ECC_ERR_BAD_CONTEXT y E ERR MEMORY FAIL Initialization of the ECC Private Key API ECCinitPrivKey lt lt error status ECC_ERR_BAD_PARAMETER Ecc success ECC ERR BAD PRIVATE KEY v Deinitialization of the Elliptic Curve API gt gt ECC_ERR_BAD_PARAMETER nee reel ECC SUCCESS ECC ERR BAD CONTEXT ERR MEMORY FAIL error status Y Set the value of the ECC Private Key API i ECCsetPrivKeyValue error status y ECC_ERR_BAD_PARAMETER O ECC SUCCESS a ECC_ERR_BAD_CONTEXT M Deinitialization of the Random Engine API RNGfree v status gt RNG_ERR_BAD_PARAMETER RNG_ERR_UNINIT_STATE MS30078V1 98 131 DoclD14989 Rev 4 ky UMO586 ECC algorithm
67. RR BAD PARAMETER P pECctx NULL ECC ERR BAD CONTEXT Some values inside P pECctx are invalid ERR DYNAMIC ALLOCATION FAILED Not enough memory ECpoint stt data structure Object used to store an elliptic curve point Should be allocated and unitized by ECCinitPoint and freed by ECCfreePoint Table 101 ECpoint_stt data structure Field name Description BigNum_stt pmX BigNum_stt integer for pmX coordinate BigNum_stt pmY BigNum_stt integer for pmY coordinate BigNum_stt pmZ BigNum_stt integer pmZ coordinate used in projective representations ECPntFlags et mFla a flag CRL_EPOINT_INFINITY to denote the infinity point flag CRL EPOINT GENERAL point which may have pmZ not equal to 1 flag CRL_EPOINT_NORMALIZED point which has pmZ equal to 1 DoclD14989 Rev 4 2 UMO586 ECC algorithm 9 2 4 ECCfreePoint function Table 102 ECCfreePoint function Function name ECCfreePoint Prototype e ECCfreePoint ECpoint stt P pECPnt membuf stt P pMemBuf Behavior Free Elliptic curve point in P pECPnt The point that will be freed Parameters in out P pMemBuf Pointer to membuf stt structure that stores Ellitpic Curve Point internal values ECC SUCCESS Operation Successful Return value ECC ERR BAD PARAMETER P_pECPnt NULL P pMemBuf NULL ECC ERR BAD CONTEXT P pECPnt NULL 9 2 5 ECCsetPointCoordinate function 4 Table
68. RSAKeySizelnBytes Suggested values are 3 or 4 Entering a value of 7 or more will be probably worst than using 6 RSA Window size Specifies algorithm used for polynomial multiplication in AES GCM This also defines the size of the precomputed table made to speed up the multiplication There are two types of table one is based on the value of the key and so needs to be generated at running through AES_GCM_keyschedule the other is constant and is defined if included here in privkey h There are 3 possible choices 0 Without any tables No space required Slower version 1 Key dependent table for Poly y 0000 lt y lt 1111 and constant table for x 4 256 key dependent bytes 32 constant bytes 2 4 key dependent tables for Poly y 24 32 i and 4 key dependent tables for Poly y x 4 24 32 i with 0000 lt y lt 1111 and 0 lt i lt 4 and constant tables for x48 and for x44 2048 key dependent bytes 544 constant bytes AES GCM GF 2M28 Table CRL GFMUL 2 Precomputations 2 116 131 DoclD14989 Rev 4 UMO586 STM32 encryption library settings 10 2 STM32_CryptoLibraryVersion To get information about the STM32 Cryptographic Library setting and version call the STM32_CryptoLibraryVersion function in the application layer Table 124 STM32_CryptoLibraryVersion Function name STM32_CryptoLibraryVersion void TM32_CryptoLibraryVersion Prototype i
69. SKflags et mFlags mFlags const uint8 t pmKey Pointer to original Key buffer const uint8 t pmNonce Pointer to original Nonce buffer Size of the Nonce in bytes This must be set by the caller prior to DEP mNoncesize calling Init Possible values are 7 8 9 10 11 12 13 uint32 t amIvCTR 4 This is the current IV value for encryption uint32 t amIvCBC 4 This is the current IV value for authentication AES Key length in bytes This must be set by the caller prior to int32 t mKeySize a E ee calling Init Pointer to Authentication TAG This value must be set in const uint8_t pmTag decryption and this TAG will be verified Size of the Tag to return This must be set by the caller prior to AE AE Mragsrze calling Init Possible values are values are 4 6 8 10 12 14 16 Size of the associated data to be processed yet This must be set i 2 mAssD i y E An o ssDatasize by the caller prior to calling Init Size of the payload data to be processed yet size This must be ea mpayloadsize set by the caller prior to calling Init uint32_t amExpKey CRL_AES_MAX_EXPKEY_SIZ AES Expanded key For internal use E uint32 t amTmpBuf CRL AES BLOCK Temp buffer sizeof uint32 t int32 t mImpBufUse Number of bytes actually in use 2 62 131 DoclD14989 Rev 4 UMO586 AES algorithm 4 6 2 AES_CCM_Header_Append function T
70. SUCCESS 4 MS30067V1 2 UMO586 DES and Triple DES algorithms 3 2 1 DES DDD Encrypt Init function Table 3 DES DDD Encrypt Init Function name DES DDD Encrypt Init 1 int32 t DES DDD Encrypt Init DESDDDctx_stt P_pDESDDDctx Prototype const uint8 t P_pKey const uint8 t P pIv Behavior Initialization for DES Encryption in DDD mode in out P pDESDDDctx DES DDD context Parameter in P pKey Buffer with the Key fin P_plv Buffer with the IV DES SUCCESS Operation Successful DES ERR BAD PARAMETER At least one parameter is a NULL pointer DES ERR BAD CONTEXT Context not initialized with valid values see note 2 below This return value is only used with CBC algorithm Return value DDD is ECB or CBC 2 In ECB IV is not used so the value of P plv is not checked or used In CBC IV size must be already written inside the fields of P_pDESCBCctx The IV size must be at least 1 and at most 16 to avoid the DES_ERR_BAD_CONTEXT return Note 1 P pDESDDDctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 2 P pDESCBCctx mlvSize must be set with the size of the IV default CRL DES BLOCK prior to calling this function DESDDDctx_stt data structure Structure type for public key Table 4 DESDDDctx_stt data structure Field name Description uint32_t mContextId Uniq
71. S_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_OPERATION Append not allowed 4 3 3 AES_GCM_Encrypt_Append function Table 33 AES GCM Encrypt Append Function name Prototype AES GCM Encrypt Append int32 t AES GCM Encrypt Append AESGCMctx stt P_pAESGCMctx const uint8 t P pInputBuffer int32 t P inputSize uint8 t P_pOutputBuffer int32 t P_pOutputSize Behavior AES GCM Encryption function Parameter Return value in out P_pAESGCMctx AES GCM already initialized context in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes AES_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES ERR BAD OPERATION Append not allowed 1 This function can be called multiple times provided that P inputSize is a multiple of 16 A single final call with P_inputSize not multiple of 16 is allowed 4 DoclD14989 Rev 4 43 131 AES algorithm UMO586 4 3 4 44 131 AES_GCM_Encrypt_Finish function Table 34 AES GCM Encrypt Finish Function name AES GCM Encrypt Finish int32 t AES GCM Encrypt Finish AESGCMctx_stt P_pAESGCMc
72. Se eens 108 Table 116 ECDSAfreeSign function 0 0c tenes 109 Table 117 ECDSAsetSignature function 0 0 0 0 aaau aaaea 109 Table 118 ECDSAgetSignature function 109 Table 119 ECDSAverify function nee 110 Table 120 ECCvalidatePubKey function EE EE EE EE EE eee 111 Table 121 ECCkeyGen function Ee SE GE teens 111 Table 122 ECDSAsignfuncHON ee Ee Ee ee Ge tenes 112 Table 123 Library build options ii EE EE Ee eee 115 Table 124 STM32_CryptoLibraryVersion ee EE cee 117 Table 125 Performance of symmetric key encryption algo optimized for speed 119 Table 126 Code size required by symmetric key encryption algo aa 120 Table 127 Symmetric key encrypt algo performance with HW acceleration 121 Table 128 Code size for symmetric key encryption algo with HW acceleration 122 Table 129 Clock cycles for authenticated encryption algorithms optimized for speed 123 Table 130 Code size for authenticated encryption algorithms optimized for speed 123 Table 131 Clock cycles for authenticated encryption algorithms amp HW acceleration 124 Table 132 Code size for authenticated encryption algorithm amp HW acceleration 124 Table 133 AES Key Wrap Unwrap in software cece eet eee 125 Table 134 Code size for AES key wrap unwrap in software cece eee 125 Table 135 A
73. UMO586 AES algorithm 4 2 5 Note AES_AAA Decrypt_Append function Table 27 AES_AAA Decrypt_Append Function name Prototype AES_AAA Decrypt Append int32 t AES AAA Decrypt_Append AESAAActx_stt P pAESAAACtx const uint8 t P pInputBuffer int32 t P inputSize uint8 t P pOutputBuffer int32 t P pOutputSize Behavior AES Decryption in AAA Mode Parameter in P pAESAAActx AES AAA context in P_pInputBuffer Input buffer in P_inputSize Size of input data in bytes out P_pOutputBuffer Output buffer out P pOutputSize Size of written output data in bytes Return value AES_SUCCESS Operation Successful AES ERR BAD PARAMETER At least one parameter is a NULL pointer AES ERR BAD OPERATION Append not allowed AES ERR BAD INPUT SIZE P inputSize lt 16 in CBC mode or is not a multiple of CRL AES BLOCK in ECB mode DMA BAD ADDRESS Input or output buffer addresses are not word aligned DMA ERR TRANSFER Error occurred in the DMA transfer 1 AAA is ECB CBC or CTR 1 This function can be called multiple times provided that P_inputSize is a multiple of 16 2 In CBC mode and in case of a call where P_inputSize is greater than 16 and not multiple of 16 Ciphertext Stealing will be activated See CBC CS2 of lt SP 800 38 A Addendum gt NIST SP 800 38A Addendum 3 IN CTR mode a single final call with P_inputSize
74. W Key unwrap 3 486 3519 3 522 Key wrap 7 143 7 146 AES 192 KW Key unwrap 4 134 4 137 Key wrap 7 800 AES 256 KW Key unwrap 4 752 Table 136 Code size for AES key wrap unwrap with HW acceleration Algorithm Code size byte Constant data size byte AES 128 192 256 KW 1578 0 1 Note that Key Wrap even with HW acceleration needs to allocate a memory whose size is equal to the input size plus 8 bytes oc ev Ly DocID14989 Rev 4 125 131 Cryptographic library performance and memory requirements UMO586 11 4 HASH and HMAC algorithm results 11 4 1 Software optimized for speed Table 137 Clock cycles for HASH and HMAC algorithms optimized for speed Algorithm Init message Block of data 64 bytes Finalization MD5 175 909 1 608 SHA 1 250 2 466 3 063 SHA 224 230 3 352 3 906 SHA 256 210 3 352 3 948 HMAC MD5 2 001 909 4 344 HMAC SHA 1 3813 2 466 8 823 HMAC SHA 224 4 708 3 352 11 340 HMAC SHA 256 4 789 3 352 11 403 Table 138 shows the required sizes for the algorithms SHA 224 and SHA 256 are shown together because they share the same core function thus leaving only one of them provide just a small improvement in code size reduction Table 138 Clock cycles for HASH and HMAC algorithms with SW acceleration Algorithm Code size byte Constant data size byte MD5 2684 6040 SHA 1 1692 SHA 224 SHA 256 2098 6040 MD5 HMAC MD5 3264 6040 SHA 1 HMAC SH
75. _stt P_pDESDDDctx Prototype const uint8 t P_pKey const uint8 t P pIv Behavior Initialization for DES Decryption in DDD Mode in out P pDESDDDctx DES DDD context Parameter in P_pKey Buffer with the Key in P_plv Buffer with the IV Return value DES SUCCESS Operation Successful DES ERR BAD PARAMETER At least one parameter is a NULL pointer DES ERR BAD CONTEXT Context not initialized with valid values see note 2 below This return value is only used with CBC algorithm 1 DDD is ECB or CBC 2 In ECB IV is not used so the value of P_plv is not checked or used In CBC IV size must be already written inside the fields of P pDESCBCctx The IV size must be at least 1 and at most 16 to avoid the DES ERR BAD CONTEXT return 1 P_pDESDDDctx mFlags must be set before calling this function Default value is E SK DEFAULT See SKflags et for details 2 P pDESCBCctx mlvSize must be set with the size of the IV default CRL DES BLOCK prior to calling this function 2 DoclD14989 Rev 4 UMO586 DES and Triple DES algorithms 3 2 5 DES_DDD_Decrypt_Append function Table 9 DES DDD Decrypt Append Function name Prototype DES DDD Decrypt Append int32 t DES DDD Decrypt Append DESDDDctx stt P pDESDDDctx const uint8 t P pInputBuffer int32 t P_inputSize uint8 t P pOutputBuffer int32 t P_pOutputSize Behavior
76. a structure Field name Description uint8 tt pmModulus RSA Modulus int32_t mModulusSize Size of RSA Modulus uint8 t pmExponent RSA Private Exponent int32_t mExponentSize Size of RSA Private Exponent membuf_stt data structure Structure type definition for a pre allocated memory buffer Table 93 membuf_stt data structure Field name Description uint8 t pmBuffer Pointer to the pre allocated memory buffer uint16_t mSize Total size of the pre allocated memory buffer uint16_t mUsed Currently used portion of the buffer should be inititalized by user to zero 4 DoclD14989 Rev 4 93 131 RSA algorithm UMO586 8 2 2 Note 94 131 RSA_PKCS1v15_Verify function Table 94 RSA_PKCS1v15_Verify function Function name Prototype RSA_PKCS1v15_Verify int32_t RSA_PKCSlv15_Verify const RSApubKey_stt P_pPubKey const uint8_t P_pDigest hashType_et P_hashType const uint8_t P_pSignature membuf_stt P pMemBuf Behavior PKCS 1v1 5 RSA Signature Verification Function Parameter in P_pPubKey RSA public key structure RSApubKey st in P_pDigest The hash digest of the message to be verified in P_hashType Identifies the type of Hash function used in P_pSignature The signature that will be checked in P_pMemBuf Pointer to the membuf_stt structure that will be used to store the internal values required by computation
77. able 38 AES KeyWrap algorithm functions Function name Description AES KeyWrap Encrypt Init Initialization for AES KeyWrap Encryption AES_KeyWrap_Encrypt_Append AES KeyWrap Wrapping function AES_KeyWrap_Encrypt_Finish AES KeyWrap Finalization AES KeyWrap Decrypt Init Initialization for AES KeyWrap Decryption AES KeyWrap Decrypt Append AES KeyWrap UnWrapping function AES KeyWrap Finalization during Decryption the AES KeyW D Finish O f KeyWrap_Decrypt_Finis authentication will be checked The next flowchart describes the AES_KeyWrap algorithm DoclD14989 Rev 4 47 131 AES algorithm UMO586 Figure 9 AES_KeyWrap flowchart Encryption Begin AES Encryption Initialization API AES_KeyWrap Encrypt Init y error_status AES ERR BAD CONTEXT AES ERR BAD PARAMETER AES SUCCESS AES Encryption API AES KeyWrap Encrypt Append error status AES ERR BAD PARAMETER AES ERR BAD INPUT SIZE AES ERR BAD OPERATION AES SUCCESS AES Encryption Finalization API AES_KeyWrap_Encrypt_Finish error status AES ERR BAD PARAMETER AES SUCCESS 48 131 DoclD14989 Rev 4 Decryption N egin AES Decryption Initialization API AES KeyWrap Decrypt Init a error status AES ERR BAD CONTEXT AES SUCCESS AES ERR BAD PARAMETER AES Decryption API AES_KeyWrap_Decrypt_Append
78. able 56 AES_CCM_Header_Append Function name AES_CCM_Header_Append int32 t AES CCM Header Append AESCCMctx_stt P_pAESCCMctx Prototype Na const uint8_t P_pInputBuffer int32_t P_inputSize Behavior AES CCM Header processing function in out P pAESCCMctx AES CCM context Parameter in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_OPERATION Append not allowed 1 This function can be called multiple times provided that P_inputSize is a multiple of 16 A single final call with P_inputSize not multiple of 16 is allowed 4 6 3 AES_CCM_Encrypt_Append function Table 57 AES CCM Encrypt Append Function name AES_CCM_Encrypt_Append int32_t AES_CCM_Encrypt_Append AESCCMctx_stt P_pAESCCMctx const uint8_t P_pInputBuffer Prototype i p int32_t P_inputSize uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior AES CCM Encryption function in out P pAESCCMctx AES CCM context in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P_pOutputSize Size of written output data expressed in bytes AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At leas
79. abstraction layer HAL Note 1 For algorithms that are not supported by the HW Cryptographic peripheral only the firmware version will be available when enabling HW acceleration Note 2 HW acceleration is only available for STM32F21x and STM32F41x devices For other devices all cryptographic algorithms are implemented in firmware Note 3 CRC peripheral is used e The HAL controls the STM32 device registers and features based on two main libraries 3 CMSIS layer Core Peripheral Access Layer STM32xx Device Peripheral Access Layer STM32 standard peripheral driver e STM32 cryptographic library As presensented in Figure 2 the STM32 cryptographic library is based on modular archictecture that means new algorithms can be added 12 131 DoclD14989 Rev 4 ky UMO586 STM32 cryptographic library package presentation without any impact on the current implementation To provide flexibility for cryptographic functions each algorithm can be compiled with different options to manage the memory and execution speed Chapter 11 is dedicated to the performance evaluation of the cryptographic library for the STM32 microcontroller series This analysis targets the STM32F4xx family in particular as the series STM32F41x includes some cryptographic accelerators e Application layer The application layer consists of a set of examples covering all available algorithms with template projects for the most common development tools
80. ameter in P pKey Buffer with the Key in P_plv Buffer with the IVO Return value ARC4_SUCCESS Operation Successful ARC4_ERR_BAD_PARAMETER At least one parameter is a NULL pointer ARC4 ERR BAD CONTEXT Context not initialized with valid values see note 1 In ARC4 the IV is not used so the value of P_plv is not checked or used Note P_pARC4ctx mKeySize see ARC4ctx_stt must be set with the size of the key before calling this function 5 2 5 ARC4_Decrypt_Append function Table 68 ARC4_Decrypt_Append Function name Prototype Behavior ARC4_Decrypt_Append int32_t ARC4 Decrypt Append ARC4ctx_stt P_pARC4ctx const uint8 t P_pInputBuffer int32 t P inputSize uint8 t P pOutputBuffer int32 t P_pOutputSize ARC4 Decryption Parameter in out P pARC4ctx ARC4 already initialized context in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes Return value ARC4_SUCCESS Operation Successful ARC4 ERR BAD PARAMETER At least one parameter is a NULL pointer ARC4 ERR BAD OPERATION Append can t be called after a Final Note This function can be called multiple times 72 131 2 DoclD14989 Rev 4 UMO586 ARCA algorith
81. ation Algorithm mode Operation Init key Init message Process block of data Encryption 0 601 28 DES ECB on Decryption 0 607 28 Encryption 0 799 28 DES CBC ae Decryption 0 787 28 Encryption 0 616 59 TDES ECB Decryption 0 631 59 Encryption 0 818 59 TDES CBC Decryption 0 817 59 Encryption 0 702 34 AES 128 ECB Decryption 0 819 34 Encryption 0 1170 34 AES 128 CBC Decryption 0 1 281 34 Encryption 0 726 34 AES 192 ECB Decryption 0 849 34 Encryption 0 1197 34 AES 192 CBC Decryption 0 1311 34 Encryption 0 728 34 AES 256 ECB Decryption 0 854 34 Encryption 0 1 205 34 AES 256 CBC Decryption 0 1322 34 AES 128 CTR Encryption 0 1 085 34 AES 128 CTR Decryption 0 1 107 34 AES 128 CMAC Encryption 0 1079 128 AES 128 CMAC Decryption 0 982 128 AES 192 CTR Encryption 0 1 112 34 AES 192 CTR Decryption 0 1131 34 AES 192 CMAC Encryption 0 1 104 128 AES 192 CMAC Decryption 0 1 002 128 AES 256 CTR Encryption 0 1 120 34 AES 256 CTR Decryption 0 1 142 34 AES 256 CMAC Encryption 0 1 096 128 AES 256 CMAC Decryption 0 1 002 128 1 Block of data represent 8 bytes for DES and TDES 16 for AES 1 for ARC4 4 DoclD14989 Rev 4 121 131 Cryptographic library performance and memory requirements UMO586 Table 128 Code size for symmetric key encryption algo with HW acceleration Algorithm mode C
82. ation API AES_AAA Decrypt Finish error_status AES ERR BAD PARAMETER AES SUCCESS End error status gt AES_ERR_BAD_PARAMETER AES SUCCESS End MS30069V1 4 DoclD14989 Rev 4 33 131 AES algorithm UMO586 4 2 1 Note 34 131 AES_AAA Encrypt Init function Table 22 AES AAA Encrypt Init Function name AES AAA Encrypt Init int32 t AES AAA Encrypt_Init AESAAActx stt P_pAESAAActx Prototype const uint8 t P pKey const uint8 t P pIv Behavior Initialization for AES Encryption in AAA Mode in out P pAESAAActx AES AAA context Parameter in P_pKey Buffer with the Key int P plv Buffer with the IV Can be NULL since no IV is required in ECB AES SUCCESS Operation Successful Return value AES ERR BAD PARAMETER At least one parameter is a NULL pointer AES ERR BAD CONTEXT Context not initialized with valid values See note 1 AAA is ECB CBC or CTR 1 P_pAESCTRctx mKeySize see AESCTRctx_stt must be set with the size of the key prior to calling this function Instead of the size of the key you can also use the following predefined values CRL_AES128_KEY CRL_AES192_KEY CRL_AES256_KEY 2 P_pAESCTRctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for detail 3 P pAESCTRctx mlvSize must be set with the size of the IV defa
83. ation API ECC ERR BAD CONTEXT ECCkeyGen Deinitialization of the Elliptic Curve API ECCfreeEC error_status ERR_MEMORY_FAIL ECC_ERR_BAD_PARAMETER ECG SUCCESS RNG_ERR_UNINIT_STATE ECC_ERR_MISSING_EC_PARAM ECC_ERR_BAD_PARAMETER MATH_ERR_BIGNUM_OVERFLO ECC_SUCCESS ECG ERR BAD CONTEXT Export ECC Private Key API ECCget PrivKeyValue Deinitialization of the Random Engine API RNGfree error_status ECC_ERR_BAD_PARAMETER ECC_SUCCESS RNG_ERR_BAD_PARAMETER RNG_ERR_UNINIT_STATE Export Public Key Point Coordinate API ECCgetPointCoordinate Both coordinates l e public key exported No then repeat twice to retrieve both coordinates MS30081V1 100 131 DoclD14989 Rev 4 hy UMO586 ECC algorithm 9 2 1 ECCinitEC function This is the first EC operation performed it loads elliptic curve domain parameters Table 97 ECCinitEC function Function name ECCinitEC Prototype int32_t ECCinitEC EC_stt P_pECctx membuf_stt P_pMemBuf Behavior Initialize the elliptic curve parameters into a EC_stt structure in out P_pECctx EC_stt context with parameters of ellliptic curve used Parameter in out P_pMemBuf Pointer to membuf stt structure that will be used to store the Ellitpic Curve internal values ECC SUCCESS Operation Successful ECC ERR BAD PARAMETER P_pECctx NULL ECC ERR BAD CONTEXT Some
84. be non zero multiple of 64 bits 1 This function can be called only once passing in it the whole Key to be Wrapped 1 P_inputSize must be a non zero multiple of 64 bits up to a maximum of 256 or AES ERR BAD INPUT SIZE is returned 2 P pOutputBuffer must be at least 8 bytes longer than P_pInputBuffer AES_KeyWrap_Encrypt_Finish function Table 41 AES KeyWrap Encrypt Finish Function name AES KeyWrap Encrypt Finish int32 t AES KeyWrap Encrypt Finish AESKWctx_stt P_pAESKWctx Prototype uint8 t P pOutputBuffer int32 t P pOutputSize Behavior AES KeyWrap Finalization in out P pAESKWctx AES KeyWrap already initialized context Parameter out P pOutputBuffer Output buffer won t be used out P pOutputSize Size of written output data It will be zero Return value AES_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer 1 This function won t write output data thus it can be skipped It is kept for API compatibility 2 DoclD14989 Rev 4 UMO586 AES algorithm 4 4 4 AES KeyWrap Decrypt Init function Table 42 AES KeyWrap Decrypt Init Function name AES KeyWrap Decrypt Init int32 t AES KeyWrap Decrypt Init AESKWctx_stt P_pAESKWctx Prototype const uint8_t P_pKey const uint8 t P pIv Behavior Initialization for AES KeyWrap Decryption in
85. be set with the size of authentication TAG that will be generated by the AES GCM Encrypt Finish 5 If hardware support is enabled DMA will not be used even if E SK USE DMA is set inside P pAESGCMctx gt mFlags as GCM is implemented with an interleaved operation and the AES engine is used one block at a time 6 Following recommendation by NIST expressed in section 5 2 1 1 of NIST SP 800 38D this implementation supports only IV whose size is of 96 bits ky DoclD14989 Rev 4 41 131 AES algorithm UM0586 42 131 AESGCMctx_stt data structure Structure used to store the expanded key and eventually precomputed tables according to the defined value of CRL_GFMUL in the config h file Table 31 AESGCMctx_stt data structure Field name uint32 t mContextId Description Unique ID of this AES GCM context Not used in current implementation SKflags et mFlags 32 bit mFlags used to perform keyschedule see SKflags et mFlags const uint8 t pmKey Pointer to original key buffer const uint8_t pmIv Pointer to original initialization vector buffer Size of the initialization vector in bytes This must be set by the int32 t mIvSize A E y caller prior to calling Init uint32 t amIv 4 This is the current IV value int32_t mKeySize AES key length in bytes Must be set by the caller prior to calling Init const uint8_t pmTag Pointer to Authentication TAG Must be set in decryption a
86. ble 29 AES GCM algorithm functions ie EE ee ee eee 39 Table 30 AES GCM Encrypt Init ee EE tenes 41 Table 31 AESGCMctx_stt data structure ee eee 42 Table 32 AES GCM Header Append ii EE EE ES Ee eee eee 43 Table 33 AES GCM Encrypt Append ie EE ESE Se ee ee ee ee ee ee ee 43 Table 34 AES GCM Encrypt Finish ee Ee Ee ee ee ee ee ee ee Ge eed ee ee ee ee ee 44 Table 35 AES GCM Decrypt II ie ee Ee ed ee eee 45 Table 36 AES GCM Decrypt Append ooo 46 Table 37 AES GCM Decrypt Finish ii ee Ee ee ee ee ee ee ee ee ee ee ee ee ee ee 46 Table 38 AES KeyWrap algorithm functions ii se ee ee ee ee ee ee ee ee ke ee ee ee ke ee 47 Table 39 AES KeyWrap_Encrypt_Init 20 0 EE ee ee ee ee ee ee ee ee ee 49 Table 40 AES KeyWrap Encrypt Append ii EE ES Ee cece eee eee 50 Table 41 AES KeyWrap Encrypt Finish is EE ES ee cece eee eee ee 50 Table 42 AES KeyWrap Decrypt Init EE SE ee ee ee ee eee 51 Table 43 AES KeyWrap Decrypt Append ii ES EE SE Ee EG eee 52 Table 44 AES KeyWrap Decrypt Finish iis EE EE ES Ee ee ee ee ee ee ee ee ee 52 Table 45 AES CMAC algorithm functions ee ee Ee ee ee ee 53 Table 46 AES CMAC Encrypt Init ee Ee ee ee ee ee ee ee ee ee ee ee 55 Table 47 AESCMACctx_stt data structure ie EE Ee ee ee ee ee ee ee ee ee ee ee 55 Table 48 AES CMAC Encrypt Append ii EE e 56 yy DocID14989 Rev 4 7 131
87. ccelerators in the STM32F21x and STM32F41x devices For DES and Triple DES library settings refer to Section 10 STM32 encryption library settings For DES and Triple DES library performance and memory requirements refer to Section 11 Cryptographic library performance and memory requirements DoclD14989 Rev 4 hy UMO586 DES and Triple DES algorithms 3 2 DES library functions Table 1 describes the encryption library s DES functions Table 1 DES algorithm functions DDD ECB or CBC Function name DES_DDD_Encrypt_Init Description Initialization for DES Encryption in DDD mode DES DDD Encrypt Append DES Encryption in DDD mode DES DDD Encrypt Finish DES Encryption Finalization of DDD mode DES DDD Decrypt Init Initialization for DES Decryption in DDD mode DES DDD Decrypt Append DES Decryption in DDD mode DES DDD Decrypt Finish DES Decryption Finalization in DDD mode DDD represents the mode of operation of the DES algorithm it is either ECB or CBC For example if you want to use ECB mode as a DES algorithm you can use the following functions Table 2 DES ECB algorithm functions Function name ECB _ Encrypt_Init Description Initialization for DES Encryption in ECB mode ECB _Encrypt_Append DES Encryption in ECB mode ECB_ Encrypt_Finish ECB_ Decrypt_Init DES Encryption Finalization of ECB mode
88. cify the type of DRBG to use Table 73 RNGstate_stt struct reference uint32_t mFlag Used to check if the random state has been mFlag 4 DoclD14989 Rev 4 77 131 RNG algorithm UMO586 6 2 2 Note 78 131 RNGinit function Table 74 RNGinit Function name RNGinit int32_t RNGinit const RNGinitInput_stt P_pInputData int32_t P_DRBGtype RNGstate_stt P_pRandomState Prototype Behavior Initialize the random engine in P_pInputData Pointer to an initialized RNGinitInput_stt structure with the parameters needed to initialize a DRBG In case P_DRBGtype C_HW_RNG it can be NULL Parameter out P_pRandomState The state of the random engine that will be initialized in P_DRBGtype Specify the type of DRBG to use Possible choices are C_DRBG_AES128 NIST DRBG based on AES 128 C HW RNG Hardware RNG if device supports it RNG_SUCCESS Operation Successful RNG ERR BAD ENTROPY SIZE Wrong size for P_pEntropyInput It must be greater than CRL DRBG AES128 ENTROPY MIN LEN and less than CRL DRBG AES ENTROPY MAX LEN RNG ERR BAD PERS STRING SIZE Wrong size for P pPersStr It must be less than CRL DRBG AES MAX PERS STR LEN Return value 1 This function reguires that P plnputData pmEntropyData points to a valid buffer containing entropy data P_pInputData gt mEntropyDataSize specifies the size of the entropy data it should be gr
89. e It is listed here because in the case of GCM the amount is significant Table 130 Code size for authenticated encryption algorithms optimized for speed Code size E Context size Algorithm mode byte Constant data size byte byte AES 128 192 256 CCM 6502 6040 332 AES 128 192 256 GCM 6488 6040 2360 DoclD14989 Rev 4 123 131 Cryptographic library performance and memory requirements UMO586 11 2 2 Hardware enhanced For each version of algorithm with hardware acceleration Table 131 shows the clock cycles required for each operation Table 131 Clock cycles for authenticated encryption algorithms amp HW acceleration Block of Block of Algorithm mode Operation Init Key Init Message header 16 Payload 16 bytes bytes Encryption 10 374 2417 1314 1 468 AES 128 GCM Decryption 10 374 2 454 1314 1 492 Encryption 10314 2 434 1314 1 469 AES 192 GCM Decryption 10314 2 482 1314 1 492 Encryption 10 302 2 437 1315 1 468 AES 256 GCM Decryption 10 299 2479 1315 1 492 Encryption 0 1 543 136 260 AES 128 CCM Decryption 0 1 356 136 239 Encryption 0 1573 136 260 AES 192 CCM Decryption 0 1 386 136 239 Encryption 0 1 564 136 260 AES 256 CCM Decryption 0 1 380 136 239 Table 132 shows the required sizes for the algorithms The Context size is the amount of RAM memory required to store a context of the Mode It is listed here because in the case
90. e P_pAESKWctx gt mFlags as CCM is implemented with an interleaved operation and the AES engine is used one block at a time 4 NIST defines the IV equal to OxAGAGAGAGAGAGAGAG In this implementation is a required input and can assume any value but its size is limited to 8 byte AESKWctx_stt data structure The AESKWctx_stt data structure is aliased to the AESAAActx_stt data structure ky DoclD14989 Rev 4 49 131 AES algorithm UMO586 4 4 2 Note 4 4 3 50 131 AES_KeyWrap_Encrypt_Append function Table 40 AES_KeyWrap_Encrypt_Append Function name Prototype AES KeyWrap Encrypt Append int32 t AES KeyWrap Encrypt Append AESKWctx stt P_pAESKWctx const uint8 t P pInputBuffer int32 t P inputSize uint8 t P pOutputBuffer int32 t P pOutputSize Behavior AES KeyWrap Wrapping function Parameter in out P_pAESKWctx AES KeyWrap already initialized context in P_pInputBuffer Input buffer containing the Key to be wrapped in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes Return value AES_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES ERR BAD OPERATION Append not allowed AES ERR BAD INPUT SIZE P inputSize must
91. e passed as part of the ciphertext In this implementations the tag should be not be passed to AES_CCM_Decrypt_Append Instead a pointer to the TAG must be set in P_pAESCCMctx pmTag and this will be checked by AES_CCM_Decrypt_Finish 9 If hardware support is enabled DMA will not be used even ifE SK USE DMA is set inside P pAESCCMctx gt mFlags as CCM is implemented with an interleaved operation and the AES engine is used one block at a time ky DoclD14989 Rev 4 65 131 AES algorithm UMO586 4 6 6 AES_CCM_Decrypt_Append function Table 60 AES_CCM_Decrypt_Append Function name AES CCM Decrypt Append int32 t AES CCM Decrypt Append AESCCMctx stt P pAESCCMctx const uint8 t P pInputBuffer Prototype int32 t P_inputSize uint8 t P pOutputBuffer int32 t P pOutputSize Behavior AES CCM Decryption function in out P pAESCCMctx AES CCM already initialized context in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes Parameter AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES ERR BAD OPERATION Append not allowed 1 This function can be called multiple times provided that P inputSize is
92. e required Digest uint8 t amBuffer 64 Internal Buffer with the data to be hashed uint32 t amCount 2 Internal Keeps the count of processed bits uint32 t amState 8 Internal Keeps the internal state HashFlags et mFlags Enumeration of allowed flags in a context for Symmetric Key operations Table 83 HashFlags et mFlags Field name Description E HASH DEFAULT User Flag No flag specified E HASH DONT PERFORM User Flag Forces init to not reperform key processing in HMAC KEY SCHEDULE mode _ User Flag if MD5 SHA 1 has an HW engine specifies if DMA or E_HASH_USE_DMA Eos CPU transfers data If DMA only one call to append is allowed E HASH OPERATION Internal Flag checks the Finish function has been already called COMPLETED Internal Flag it is set when the last append has been called Used where the append is called with an InputSize not multiple of the block size which means that is the last input E HASH NO MORE APPEND ALLOWED 4 DoclD14989 Rev 4 85 131 HASH algorithm UMO586 7 2 2 Note 86 131 HHH_Append function Table 84 HHH_Append Function name HHH_Append int32_t HHH_Append HHHctx_stt P_pHHHctx Prototype const uint8 t P pInputBuffer int32 t P_inputSize Behavior Process input data and update a HHHctx stt in out P_pHHHctx HHH context that will be updated Parameter in
93. eater than CRL_DRBG_AES128_ENTROPY_MIN_LEN and less than CRL_DRBG_AES_ENTROPY_MAX_LEN P_pInputData gt pmNonce points to a valid Nonce or be set to NULL P_pInputData gt mNonce Size specifies the size of the Nonce or be set to zero P_pInputData gt pmPersData points to a valid Personalization String or be set to NULL P_pInputData gt mPersDataSize specifies size of Personalization String or be set to zero 2 Section 4 of href http csrc nist gov publications nistpubs 800 90A SP800 90A pdf gt NIST SP 800 90A lt a gt explains the meaning of Nonce Personalization String and Entropy data RNGstate_stt struct reference Structure that contains the by RNG state Table 75 RNGstate_stt struct reference Field name Description uint8_t pmEntropyData Entropy data input int32_t mEntropyDataSize Size of the entropy data input uint8_t pmNonce Nonce data uint32_t mNonceSize Size of the Nonce int8_t pmPersData Personalization String uint32_t mPersDataSize Size of personalization string DoclD14989 Rev 4 Ly UMO586 RNG algorithm 6 2 3 RNGfree function Table 76 RNGfree Function name RNGfree int32_t RNGfree Prototype RNGstate_stt P_pRandomState Behavior Free a random engine state structure Parameter in out P pRandomState The state of the random engine that will be removed Return value RNG_SUCCESS Operation Successful RNG_ERR_BA
94. ed by estoppel or otherwise to any intellectual property rights is granted under this document If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property contained therein UNLESS OTHERWISE SET FORTH IN ST S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY WITH RESPECT TO THE USE AND OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND THEIR EQUIVALENTS UNDER THE LAWS OF ANY JURISDICTION OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT ST PRODUCTS ARE NOT AUTHORIZED FOR USE IN WEAPONS NOR ARE ST PRODUCTS DESIGNED OR AUTHORIZED FOR USE IN A SAFETY CRITICAL APPLICATIONS SUCH AS LIFE SUPPORTING ACTIVE IMPLANTED DEVICES OR SYSTEMS WITH PRODUCT FUNCTIONAL SAFETY REQUIREMENTS B AERONAUTIC APPLICATIONS C AUTOMOTIVE APPLICATIONS OR ENVIRONMENTS AND OR D AEROSPACE APPLICATIONS OR ENVIRONMENTS WHERE ST PRODUCTS ARE NOT DESIGNED FOR SUCH USE THE PURCHASER SHALL USE PRODUCTS AT PURCHASER S SOLE RISK EVEN IF ST HAS BEEN INFORMED IN WRITING OF SUCH USAGE UNLESS A PRODUCT IS EXPRESSLY DESIGNATED BY ST AS BEING INTENDED FO
95. ed to be a multiple of 4 In this case P pPrivateKey will contain one or more leading zeros 9 2 14 ECCscalarMul function Table 113 ECCscalarMul function Function name ECCscalarMul int32 t ECCscalarMul const ECpoint stt P_pECbasePnt const ECCprivKey stt P pECCprivKey Prototype ECpoint stt P pECresultPnt const EC stt P pECctx membuf stt P pMemBuf Behavior Computes the point scalar multiplication kP k P in P pECbasePnt The point that will be multiplied in P pECCprivKey Structure containing the scalar value of the multiplication out P pECresultPnt The output point result of the multiplication in P pECctx Structure describing the curve parameters P pMemBuf Pointer to the membuf stt structure that currently stores the Ellitpic Curve Private Key internal value ECC SUCCESS Operation Successful ECC ERR BAD PARAMETER One of the inputs NULL MATH ERR BIGNUM OVERFLOW The P pCopyPoint was not initialized with Return value the correctP pECctx ECC ERR BAD CONTEXT P_pECctx gt pminternalEC NULL ECC WARN POINT AT INFINITY The retumed point is the O point for the Elliptic Curve Parameter I I al I 4 DoclD14989 Rev 4 107 131 ECC algorithm UMO586 9 2 15 ECCsetPointGenerator function Table 114 ECCsetPointGenerator function Function name ECCsetPointGenerator int32_t ECCsetPointGenerator ECpo
96. er organization n scs EE EE Se ete 15 DES DDD flowchart ss ss da ED pi ED PADAGDAG DD BR a RA BANGA 18 TDES TTT flowchart ee Ge Gee ee ee ee a ee ee ee 25 AES AAA flowchart ee ee a aa ttt ee ee ee ee ee ee 33 AES GEM flowchiatt as a sup nanan ee ee Ee ara A cae G 40 AES KeyWrap flowchart EE 000 cee tees 48 AES CMAC flowchart 0 0000 Ee a eee 54 AES CCM flowcharts ii ai ee se ee tet ee aia eee 60 ARCA lee as oso a PA WEW NAA add RE KANG 69 RNG flowchart casa use spa DADA ee weed pa DD dete ted ea 76 Hash HHH flowchart ie se ee Ee ete ee ee ee 84 RSA iii wee AAA A A A RETA ge O E ee ig 92 ECC SOn ilowchart voca a neta ba ese Ee A deen tee De ea sa E Ran 98 ECC ide ei AE a A ER OD ns 99 ECC key generator flowchart aaau aea 100 DocID14989 Rev 4 Ly UMO586 Terminology Terminology Encryption is a branch of cryptographic science It is the transformation that converts data to illegible data with the view of making it secure The following block diagram see Figure 1 shows a commonly used encryption system structure Figure 1 Block diagram of a common cipher Cipher key Plaintext o o Ciphertext MS32844V1 The following terms are used throughout this document Cipher a suite of transformations that converts plaintext to ciphertext and ciphertext to plaintext using the cipher key transformation from plaintext to ciphertext is called enciphering or encryption
97. eter R or the parameter S must be set in P_pValue Pointer to an uint8_t array containing the signature value in P_valueSize Size of the signature value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER One of the input parameters is invalid MATH_ERR_BIGNUM_OVERFLOW signature value passed is too big for the Signature structure ECDSAgetSignature function Table 118 ECDSAgetSignature function Function name Prototype Behavior ECDSAgetSignature int32 t ECDSAgetSignature const ECDSAsignature stt P pSignature ECDSAsignValues et P Rors uint8 t P pValue int32 t P pValueSize Get the values of the parameters one at a time of an ECDSAsignature stt DoclD14989 Rev 4 109 131 ECC algorithm UMO586 Table 118 ECDSAgetSignature function continued Function name Parameter ECDSAgetSignature in P_pSignature The ECDSA signature from which retrieve the value in P_RorS Flag selects if the parameter R or the parameter S must be returned out P_pValue Pointer to an uint8_t array that will contain the value out P pValueSize Pointer to integer that contains the size of returned value Return value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER One of the input parameters is invalid 1 The R or S size depends on the size of the Order N of the elliptic curve Specifically if P_p
98. flags et mFlags const uint8 t pmKey Pointer to original Key buffer int32 t mKeySize ARC4 key length in bytes This must be set by the caller prior to calling Init int8_t mX Internal members This describe one of two index variables of the ARC4 state Internal members This describe one of two index variables of the int8_t mY ARC4 state uint8_t amState 256 Internal members This describe the 256 bytes State Matrix 5 2 3 ARC4 Encrypt Finish function Table 66 ARC4_Encrypt_Finish Function name ARC4_Encrypt_Finish int32 t ARC4 Encrypt Finish ARC4ctx stt P pARC4ctx Return value 4 Prototype uint8 t P pOutputBuffer int32 t P pOutputSize Behavior ARCA Finalization in out P pARC4ctx ARC4 context amater out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes ARC4_SUCCESS Operation Successful ARC4_ERR_BAD_PARAMETER At least one parameter is a NULL pointer DoclD14989 Rev 4 71 131 ARCA algorithm UMO586 5 2 4 ARC4 Decrypt Init function Table 67 ARC4 Decrypt Init Function name ARC4 Decrypt Init int32 t ARC4 Decrypt Init ARC4ctx stt P_pARC4ctx Prototype const uint8 t P_pKey const uint8 t P pIv Behavior Initialization for ARC4 algorithm in out P pARC4ctx ARC4 context Par
99. for each Development Toolchain in the EWARM and MDK ARM subfolders a EWARM Contains eight STM32 crytographic libraries compiled with IAR toolchain 6 5 30 with high speed optimization M4_CryptoHW_2_0_6 a STM32 Cryptographic Library for STM32F41x families M4 CryptoFW RngHW 2 0 6 a STM32 Cryptographic Library Firmware with Hardware RNG pheripheral for STM32F4xx families M4 CryptoFW 2 0 6 a STM32 Cryptographic Library Firmware for STM32F40x families M3 CryptoHW 2 0 6 a STM32 Cryptographic Library for STM32F21x families M3 CryptoFW RngHW 2 0 6 a STM32 Cryptographic Library Firmware with Hardware RNG pheripheral for STM32F20x families M3 CryptoFW 2 0 6 a STM32 Cryptographic Library Firmware for STM32F 10x and STM32F3xx M3 CryptoFW Lixx 2 0 6 a STM32 Cryptographic Library Firmware for STM32L 1xx families MO CryptoFW 2 0 6 a STM32 Cryptographic Library Firmware for STM32F0xx families MDK ARM Contains eight STM32 crytographic libraries compiled with Keil toolchain 4 70 with optimization level 3 O 3 M4 CryptoHW 2 0 6 lib STM32 Cryptographic Library for STM32F41x families M4 CryptoFW RngHW 2 0 6 lib STM32 Cryptographic Library Firmware with Hardware RNG pheripheral for STM32F4xx families M4 CryptoFW 2 0 6 lib STM32 Cryptographic Library Firmware for STM32F40x families M3_CryptoHW_2_0_6 lib STM32 Cryptographic Library for STM32F21x families M3_CryptoFW_RngHW_2_0_6 lib STM32 Cryptographic Library Firmware
100. h level functions operations INCLUDE ENCRYPTION Includes the Encryption functionalities Remove it if only Encryption Da decryption is needed Decryption capability INCLUDE DECRYPTION Includes the Decryption functionalities Remove it if only encryption is needed Symmetric Key Algorithms INCLUDE_DES Permits DES functions in the library INCLUDE_AES128 Permits TripleDES TDES functions in the library Permits AES functions with key size of 128 bits in the library if its NOT defined then aes128 c is not needed INCLUDE_AES192 Permits AES functions with key size of 192 bits in the library If its NOT defined then aes192 c is not needed INCLUDE_AES256 INCLUDE_ARC4 INCLUDE_ECB Permits AES functions with key size of 256 bits in the library If it s NOT defined then aes256 c is not needed Enables the ARC4 algorithm Enables AES high level functions for ECB mode are included in the library INCLUDE_CBC Enables AES high level functions for CBC mode in the library Symmetric Key INCLUDE_CTR Enables AES high level functions for CTR mode in the library Modes ol INCLUDE_GCM Enables AES high level functions for GCM mode in the library operations INCLUDE_KEY_WRAP Enables AES KWRAP function in the library INCLUDE_CCM Enables AES CCM function in the library INCLUDE_CMAC Enables AES CMAC function in the library Ly DocID14989 Rev 4
101. in P_pECctx Structure describing the curve parameters This must contain the values of the generator in out P_pMemBuf Pointer to the membuf_stt structure that will be used to store the internal values required by computation I ECC_SUCCESS Key Pair generated Successfully ERR_MEMORY_FAIL There s not enough memory ECC_ERR_BAD_PARAMETER One of input parameters is not valid RNG_ERR_UNINIT_STATE Random engine not initialized ECC ERR MISSING EC PARAMETER P_pECctx must contain a p n Gx Gy MATH ERR BIGNUM OVERFLOW P pPubKey was not properly initialized Return value Note P pPrivKey and P pPubKey must be already initialized with respectively ECCinitPrivKey and ECCinitPoint P pECctx must contain the value of the curve s generator 4 DoclD14989 Rev 4 111 131 ECC algorithm UMO586 9 2 23 Note 112 131 ECDSAsign function Table 122 ECDSAsign function Function name Prototype ECDSAsign int32_t ECDSAsign const uint8_t P_pDigest int32_t P_digestSize const ECDSAsignature_stt P_pSignature const ECDSAsignCtx_stt P_pSignCtx membuf_stt P_pMemBuf Behavior ECDSA Signature Generation Parameter in P_pDigest The message digest that will be signed in P_digestSize The size in bytes of the P_pDigest out P_pSignature Pointer to an initialized signature structure that will be contain the result of the operaion
102. int function Table 107 ECCcopyPoint function Function name ECCcopyPoint int32 t ECCcopyPoint Prototype const ECpoint stt P pOriginalPoint ECpoint stt P pCopyPoint Behavior Copy an Elliptic Curve Point in P pOriginalPoint The point that will be copied P t gn out P pCopyPoint The output copy of P_OriginalPoint ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER An input is invalid i e NULL or not initialized Return value with ECCinitPoint MATH_ERR_BIGNUM_OVERFLOW P_pCopyPoint not initialized with correct P_pECctx Note Both points must be already initialized with ECCinitPoint 9 2 10 ECCinitPrivKey function Table 108 ECCinitPrivKey function Function name ECCinitPrivKey int32 t ECCinitPrivKey ECCprivKey stt P_ppECCprivKey const Rratowpe EC stt P pECctx membuf stt P pMemBuf Behavior Initialize an ECC private key out P_ppECCprivKey Private key that will be initialized Parameters in P pECctx EC_stt containing the Elliptic Curve Parameters in out P_pMemBuf Pointer to membuf_stt structure that will be used to store the Ellitpic Curve Private Key internal value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER P_pECctx NULL Return value T PAN y ECC ERR BAD CONTEXT Some values inside P pECctx are invalid ERR MEMORY FAIL Not enough memory
103. int_stt P_pPoint const EC_stt P_pECctx Prototype Behavior Writes the Elliptic Curve Generator point into a ECpoint_stt out P_pPoint The point that will be set equal to the generator point Parameter in P_pECctx Structure describing the curve parameters it must contain the generator point ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER One of the inputs NULL ECC_ERR_BAD_CONTEXT Some values inside P_pECctx are invalid it doesn t contain the Generator MATH_ERR_BIGNUM_OVERFLOW The P_pPoint was not initialized with the correct P_pECctx Return value Note P_pPoint must be already initialized with ECCinitPoint 9 2 16 ECDSAinitSign function Table 115 ECDSAinitSign function Function name ECDSAinitSign int32_t ECDSAinitSign ECDSAsignature_stt P_ppSignature Prototype yp const EC stt P pECctx membuf stt P pMemBuf Behavior Initialize an ECDSA signature structure out P_ppSignature Pointer to pointer to the ECDSA structure that will be allocated and initialized Parameter in P pECctx The EC stt containing the Elliptic Curve Parameters P pMemBuf Pointer to the membuf stt structure that will be used to store the ECDSA signatures internal values ECC SUCCESS Operation Successful ECC ERR BAD PARAMETER Invalid Parameter Return value ECC ERR BAD CONTEXT Some values inside P pECctx or P_pMemBuf are invalid
104. inter DES ERR BAD INPUT SIZE the P inputSize is not a multiple of CRL DES BLOCK or less than 8 DMA BAD ADDRESS Input or output buffer addresses are not word aligned DMA ERR TRANSFER Error occurred in the DMA transfer DES ERR BAD OPERATION Append not allowed 1 DDD is ECB or CBC Note This function can be called multiple times provided that P_inputSize is a multiple of 8 3 2 3 DES_DDD_Encrypt_Finish function Table 7 DES_DDD_Encrypt_Finish Function name DES DDD Encrypt Finish int32 t DES DDD Encrypt Finish DESDDDctx_stt P_pDESDDDctx Prototype uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior DES Encryption Finalization of DDD mode in out P pDESDDDctx DES DDD already initialized context out P_pOutputBuffer Output buffer Parameter out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes Return value DES SUCCESS Operation Successful DES ERR BAD PARAMETER At least one parameter is a NULL pointer 1 DDD is ECB or CBC Note This function won t write output data thus it can be skipped lt is kept for API compatibility 4 DoclD14989 Rev 4 21 131 DES and Triple DES algorithms UMO586 3 2 4 Note 22 131 DES DDD Decrypt Init function Table 8 DES DDD Decrypt Init Function name DES DDD Decrypt Init int32 t DES DDD Decrypt Init DESDDDctx
105. ion for AES CCM Decryption in out P pAESCCMctx AES CCM context Parameter in P_pKey Buffer with the Key in P_pNonce Buffer with the Nonce AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values Note 1 P_pAESCCMctx mKeySize see AESCCMctx_stt must be set with the size of the key prior to calling this function Otherwise the following predefined values can be used CRL_AES128_KEY CRL_AES192_KEY CRL_AES256_KEY 2 P pAESCCMctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 3 P_pAESCCMctx mNonceSize must be set with the size of the CCM Nonce Possible values are 7 8 9 10 11 12 13 4 P_pAESCCMectx pm Tag must be set with a pointer to the authentication TAG that will be checked during AES_CCM_Decrypt_Finish 5 P_pAESCCMctx mTagSize must be set with the size of authentication TAG that will be checked by the AES_CCM_Decrypt_Finish Possible values are values are 4 6 8 10 12 14 16 6 P_pAESCCMctx mAssDataSize must be set with the size of the Associated Data i e Header or any data that will be authenticated but not encrypted 7 P_pAESCCMctx mPayloadSize must be set with the size of the Payload i e Data that will be authenticated and encrypted 8 CCM standard expects the authentication TAG to b
106. ion of ECB mode TDES_ECB_Decrypt_Init Initialization for TDES Decryption in ECB mode TDES_ECB_Decrypt_Append TDES Decryption in ECB mode TDES_ECB_Decrypt_Finish TDES Decryption Finalization in ECB mode 2 DoclD14989 Rev 4 UMO586 DES and Triple DES algorithms Figure 6 TDES TTT flowchart Encryption Begin TDES Encryption Initialization API TDES_TTT_Encrypt Init y error_status TDES_ERR_BAD_CONTEXT used only with CBC TDES_SUCCESS TDES_ERR_BAD_PARAMETER TDES Encryption API TDES_TTT_Encrypt_Append error status TDES ERR BAD PARAMETER TDES ERR BAD INPUT SIZE TDES ERR BAD OPERATION DMA BAD ADDRESS DMA ERR TRANSFER TDES SUCCESS TDES Encryption Finalization API TDES_TTT_ Encrypt_Finish error status TDES ERR BAD PARAMETER TDES SUCCESS 4 gt Decryption TDES Decryption Initialization API TDES_TTT_Decrypt _Init y error_status TDES_ERR_BAD_CONTEXT used only with CBC TDES_ERR_BAD_PARAMETER TDES_SUCCESS TDES Decryptio n API TDES_TTT_ Decrypt_Append error status gt TDES ERR BAD PARAMETER TDES ERR BAD INPUT SIZE TDES ERR BAD OPERATION DMA BAD ADDRESS DMA ERR TRANSFER TDES SUCCESS TDES Decryption Finalization API TDES TTT Decrypt Finish End error status gt TDES_ERR_BAD_PARAMETER TDES_SUCCESS
107. is not used so the value of P_plv is not checked or used Note P_pARC4ctx mKeySize see ARC4ctx stt must be set with the size of the key prior to calling this function 5 2 2 ARC4_Encrypt_Append function Table 64 ARC4_Encrypt_Append Function name Prototype ARC4_Encrypt_Append int32_t ARC4 Encrypt Append ARC4ctx_stt P_pARC4ctx const uint8_t P_pInputBuffer int32_t P_inputSize uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior ARC4 Encryption Parameter in out P pARC4ctx ARC4 already initialized context in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes Return value ARC4_SUCCESS Operation Successful ARC4_ERR_BAD_PARAMETER At least one parameter is a NULL pointer ARC4_ERR_BAD_OPERATION Append can t be called after a final Note This function can be called multiple times 70 131 2 DoclD14989 Rev 4 UMO586 ARCA algorithm ARC4ctx_stt data structure Structure describing an ARC4 content Table 65 ARC4ctx_stt data structure uint32 t mContextId Field name Description Unique ID of this AES GCM Context Not used in current implementation SKflags et mFlags 32 bit mFlags used to perform keyschedule see SK
108. keyGen Generate an ECC key pair ECDSAsign ECDSA Signature Generation ECCgetPointFlag Reads the flag member of an Elliptic Curve Point structure ECCsetPointFlag Set the flag member of an Elliptic Curve Point structure ECCsetPointGenerator Writes the Elliptic Curve Generator point into a ECpoint_stt The next flowcharts describe the ECC algorithms 2 DoclD14989 Rev 4 97 131 ECC algorithm UMO586 Figure 16 ECC Sign flowchart ECC_ERR_BAD_PARAMETER ECC SUCCESS ECC_ERR_BAD_PRIVATE_KEY lt error status gt HASH Initialization API y HASH_Init Initialization of the Signature API ECDSAinitSign X error_status error status HASH ERR BAD PARAMETER ba ECC ERR BAD PARAMETER HASH SUCCESS ECC SUCCESS ECC_ERR_BAD_CONTEXT ERR_MEMORY_FAIL v v HASH Data Process API Signature Generation API HASH Append ECDSAsign lt error status gt error_status gt ERR_MEMORY_FAIL A HASH_ERR_BAD_PARAMETER ECC SUCCESS ECC_ERR_BAD_PARAMETER HASH_ERR_BAD_OPERATION RNG_ERR_UNINIT_STATE DMA_BAD_ADDRESS ECC_ERR_MISSING_EC_PARAMI Te QLi ay only if HASH MD5 or SHA1 MATH ERR BIGNUM OVERFLO DMA ERR TRANSFER ECC ERR BAD CONTEXT if HASH SH v HASH_SUCCESS HASH Finalization API Export Signature Value API Finish ECDSAgetSignature Xx error status gt lt lt error status D 1 ECC ERR BAD PARAMETER HASH ERR BAD PA
109. lled after Return value HMAC_HHH_Finish has been called DMA_BAD_ADDRESS Input or output buffer addresses are not word aligned used only in sha1 and md5 DMA_ERR_TRANSFER Errors in DMA transfer used only in sha1 and md5 Note 1 HHH is MD5 SHA1 SHA224 or SHA256 2 In DMA mode P_pHMAC_MD5ctx gt mFlags amp E HASH USE DMA E HASH USE DMA the Append function can be called one time only otherwise it will return HASH_ERR_BAD_OPERATION 3 In DMA mode P_pHMAC_SHA1ctx gt mFlags amp E HASH USE DMA E HASH USE DMA the Append function can be called one time only otherwise it will return HASH_ERR_BAD_OPERATION 4 This function can be called multiple times with no restrictions on the value of P_inputSize 88 131 DoclD14989 Rev 4 hy UMO586 HASH algorithm 7 2 6 HMAC_HHH_Finish function Table 89 HMAC_HHH_Finish Function name HMAC_HHH_Finish int32_t HHH Finish HMAC HHHctx stt P pHMAC HHHctx Prototype uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior HMAC HHH Finish function produce the output HMAC HHH tag in out P_pHMAC_HHHctx HMAC HHH context Parameter out P_pOutputBuffer Buffer that will contain the HMAC tag out P_pOutputSize Size of the data written to P_pOutputBuffer HASH_SUCCESS Operation Successful HASH_ERR_BAD_PARAMETER At least one parameter is a NULL Return value pointer HASH_ERR_BAD_CONTEXT P_pHHHctx was
110. ly with SHA1 and MD5 DMA_ERR_TRANSFER used only with SHA1 and MD5 HASH_SUCCESS HMAC_HHH output tag API HMAC_HHH_Finish 4 84 131 DoclD14989 Rev 4 error_status gt HASH ERR BAD PARAMETER HASH ERR BAD CONTEXT HASH SUCCESS MS30076V1 2 UMO586 HASH algorithm 7 2 1 HHH Init function Table 81 HHH Init Function name HHH Init Prototype int32 t HHH Init HHHctx stt P_pHHHctx Behavior Initialize a new HHH context Parameter in out P_pHHHctx The context that will be initialized HASH SUCCESS Operation Successful Retum val Sum vaue HASH ERR BAD PARAMETER Parameter P pHHHctx is invalid Note 1 HHH is MD5 SHA1 SHA224 or SHA256 2 P_pHHHctx mFlags must be set prior to calling this function Default value is E HASH DEFAULT See HashFlags et for details 3 P_pHHHctx mTagSize must be set with the size of the required message digest that will be generated by the HHH Finish Possible values are values are from 1 to CRL HHH SIZE HASHctx_stt struct reference Structure for HASH context Table 82 HASHctx_stt struct reference Field name Description uint32 t mContextId Unique ID of this context Not used in current implementation 32 bit mFlags used to perform keyschedule see HashFlags et Haghrlags et mrtags mFlags choose between hw sw hw dma and future use int32_t mTagSize Size of th
111. m 5 2 6 ARC4 Decrypt Finish function Table 69 describes ARC4 Decrypt Finish function Table 69 ARC4 Decrypt Finish Function name ARC4 Decrypt Finish int32 t ARC4 Decrypt Finish ARC4ctx stt P_pARC4ctx Prototype uint8_t P pOutputBuffer int32 t P pOutputSize Behavior ARCA Finalization in out P pARC4ctx ARCA already initialized context Baramotor out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes Return value ARC4_SUCCESS Operation Successful ARC4 ERR BAD PARAMETER At least one parameter is a NULL pointer Note This function won t write output data thus it can be skipped It is kept for API compatibility 4 DoclD14989 Rev 4 73 131 ARCA algorithm UMO586 5 3 74 131 ARC4 example include crypto h const uint8_t InputMessage 32 0x00 uint32 t InputLength sizeof InputMessage Key to be used for ARC4 encryption decryption uint8_t Key 5 0x01 0x02 0x03 0x04 0x05 Buffer to store the output data uint8_t OutputMessage ARC4 LENGTH Size of the output data uint32_t OutputMessageLength 0 int main void ARC4ctx_stt ARC4ctx uint32_t error_status ARC4_SUCCESS int32_t outputLength 0 Set flag field to default value ARC4ctx mFlags E_SK_DEFAULT Set key length in the context
112. n name AES CMAC Encrypt Finish int32 t AES CMAC Encrypt Finish AESCMACctx stt P pAESCMACctx Prototype uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior AES Finalization of CMAC Mode in out P pAESCMACctx AES CMAC already initialized context Parameter out P_pOutputBuffer Output buffer out P_pOutputSize Size of written output data in uint8 t Return value AES_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values see note 1 This function requires P pAESCMACctx mTagSize to contain valid value between 1 and 16 56 131 2 DoclD14989 Rev 4 UMO586 AES algorithm 4 5 4 AES CMAC Decrypt Init function Table 50 AES CMAC Decrypt Init Function name AES CMAC Decrypt Init int32 t AES CMAC Decrypt Init Prototype j AESCMACctx_stt P_pAESCMACctx Behavior Initialization for AES CMAC for Authentication TAG Verification Parameter in out P pAESCMACctx AES CMAC context AES_SUCCESS Operation Successful Ren value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values see the note below Note 1 P_pAESCMACctx pmKey see AESCMACctx_stt must be set with a pointer to the AES key before calling this function 2 P_pAESCMACctx mKeySi
113. nate of generator point int32_t mGysize Size of y coordinate of generator point void pminternalEC Pointer to internal structure for handling the parameters 4 DoclD14989 Rev 4 101 131 ECC algorithm UMO586 9 2 2 9 2 3 102 131 ECCfreeEC function Table 99 ECCfreeEC function Function name ECCfreeEC Prototype int32_t ECCfreeEC EC_stt P_pECctx membuf_stt P_pMemBuf Behavior De initialize an EC_stt context in out P_pECctx Pointer to the EC_stt structure containing the curve parameters to be freed Parameter in out P_pMemBuf Pointer to the membuf_stt structure that holds the Ellitpic Curve internal values Return value ECC_SUCCESS Operation Successful ECC_ERR_BAD_PARAMETER P_pECctx NULL ECC ERR BAD CONTEXT Some values inside P_pECctx are invalid ECCinitPoint function Table 100 ECCinitPoint function Function name ECCinitPoint int32_t ECCinitPoint ECpoint_stt P_ppECPnt const EC_stt Prototype P_pECctx membuf_stt P_pMemBuf Behavior Initialize an ECC point out P_ppECPnt The point that will be initialized in P_pECctx The EC_stt containing the Elliptic Curve Parameters Parameter in out P pMemBuf Pointer to the membuf stt structure that will be used to store the Ellitpic Curve Point internal values Return value ECC SUCCESS Operation Successful ECC E
114. nd this TAG will be verified int32_t mTagSize Size of the Tag to return Must be set by the caller prior to calling Init int32 t mAADsize Additional authenticated data size For internal use int32 t mPayloadSize poly t mPartialAuth uint32 t amExpKey CRL AES MAX EXPKEY SI ZE Payload size For internal use Partial authentication value For internal use where poly_t typedef uint32_t poly_t 4 Definition of the way a polynomial of maximum degree 127 is represented AES Expanded key For internal use table8x16_t mPrecomputedValues CRL_GFMUL 2 Precomputation of polynomial according to Shoup s 8 bit table requires 4096 bytes of key dependent data and 512 bytes of constant data For internal use where table8x16_t typedef poly t table8x16_t 8 16 Definition of the type used for the precomputed table 2 DoclD14989 Rev 4 UMO586 AES algorithm 4 3 2 AES_GCM_Header_Append function Table 32 AES_GCM_Header_Append Function name AES_GCM_Header_Append int32 t AES GCM Header Append AESGCMctx_stt P_pAESGCMctx Prototype i const uint8_t P_pInputBuffer int32_t P_inputSize Behavior AES GCM Header processing function in out P_pAESGCMctx AES GCM already initialized context Parameter in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes Return value AE
115. not multiple of 16 is allowed 4 In CTR mode This is a wrapper for AES_CTR_Encrypt_Append as the Counter Mode is equal in encryption and decryption DoclD14989 Rev 4 37 131 AES algorithm UMO586 4 2 6 AES_AAA Decrypt Finish function Table 28 AES_AAA Decrypt_Finish Function name AES AAA Decrypt Finish int32 t AES AAA Decrypt Finish AESAAACtx_stt P pAESAAACtx uint8_t P_pOutputBuffer int32 t P_pOutputSize Prototype Behavior AES Decryption Finalization of AAA Mode in out P pAESAAActx AES AAA context out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes Parameter EE GE AES SUCCESS Operation Successful AES ERR BAD PARAMETER At least one parameter is a NULL pointer 1 AAA is ECB CBC or CTR Note 1 In CTR mode This is a wrapper for AES_CTR_Encrypt_Final as the Counter Mode is equal in encryption and decryption 2 This function won t write output data thus it can be skipped It is kept for API compatibility 2 38 131 DoclD14989 Rev 4 UMO586 AES algorithm 4 3 4 AES GCM library functions Table 29 describes the AES GCM library Table 29 AES GCM algorithm functions Function name AES_GCM_Encrypt_Init Description Initialization for AES GCM encryption AES_GCM_Header_Append Header processing function AES_
116. number This algorithm can run with the STM32F1 STM32L1 STM32F20x STM32F05x STM32F40x STM32F37x and the STM32F30x series using a software algorithm implementation This algorithm can also run using the random number generator peripheral in STM32F21x and STM32F41x For RNG library settings refer to Section 10 STM32 encryption library settings For RNG library performance and memory requirements refer to Section 11 Cryptographic library performance and memory requirements RNG library functions Table 70 describes the RNG library functions Table 70 RNG algorithm functions Function name Description RNGreseed Reseed the random engine RNGinit Initialize the random engine RNGfree Free a random engine state structure RNGgenBytes Generation of pseudorandom octets to a buffer RNGgenWords Generation of a random uint32 t array The next flowchart describes the RNG algorithm DoclD14989 Rev 4 75 131 RNG algorithm UMO586 Figure 13 RNG flowchart Random Engine Initialization API RNGinit RNG_ERR_BAD_ENTROPY_SIZE RNG_ERR_BAD_PERS_STRING_SIZE RNG_ERR_BAD_ADD_INPUT_SIZE RNG SUCCESS RNG ERR BAD ENTROPY SIZE RNG SUCCESS Reseed the random engine Random Generation API RNGreseed RNGgenBytes or RNGgenWords A ERR BAD PARAMETER RNG ERR UNINIT STATE RNG SUCCESS Other RNG generation Ressources free API RNGfree RNG_SUCCESS The RNGreseed could be called an
117. oclD14989 Rev 4 UMO586 AES algorithm 4 6 4 AES CCM library functions Table 53 describes the AES CCM library Table 53 AES CCM algorithm functions Function name AES_CMAC_Encrypt_Init Description Initialization for AES CCM encryption AES_CCM_Header_Append Header Processing Function AES_CCM_Encrypt_Append AES CCM encryption function AES_CCM_Encrypt_Finish AES CCM Finalization during encryption this will create the Authentication TAG AES_CCM_Decrypt_Init Initialization for AES CCM decryption AES_CCM_Decrypt_Append AES CCM decryption function AES_CCM_Decrypt_Finish AES CCM Finalization during decryption the authentication TAG will be checked The next flowchart describes the AES_CCM algorithm DoclD14989 Rev 4 59 131 AES algorithm UMO586 Figure 11 AES_CCM flowchart Encryption Decryption N Begin Begin AES CCM Encryption Initialization API AES CCM Decryption Initialization API AES CCM Encrypt Init AES CCM Decrypt Init y y error_status error_status AES ERR BAD CONTEXT AES SUCCESS ES ERR BAD PARAMETER AES_SUCCESS SAES JERR BAD CONTEXT AES_ERR_BAD_PARAMETER AES CCM Header processing API AES CCM Decryption API AES_CCM_Header_Append AES_CCM_Decrypt_Append error status AES ERR BAD PARAMETER AES SUCCESS AES ERR BAD OPERATION AES SUCCESS AES_ERR_BAD_PARAM
118. ode size byte Constant data size byte DES TDES ECB CBC 1 984 0 AES 128 192 256 ECB CBC CTR 2 868 0 AES 128 192 256 CMAC 2 244 0 122 131 DoclD14989 Rev 4 hy UMO586 Cryptographic library performance and memory requirements 11 2 Authenticated encryption algorithms performance results 11 2 1 Software optimized for speed Below are the required clock cycles for each mode and key length Table 129 Clock cycles for authenticated encryption algorithms optimized for speed Block of Block of Algorithm mode Operation Init key Init message header 16 payload 16 bytes bytes Encryption 12570 3 368 1314 3 043 AES 128 GCM Decryption 12570 3410 1314 3071 Encryption 12 762 3 692 1314 3 318 AES 192 GCM Decryption 12 762 3795 1314 3 345 Encryption 13245 4 092 1315 3 607 AES 256 GCM Decryption 13 248 4 120 1315 3 634 Encryption 606 4 167 1 585 3 158 AES 128 CCM Decryption 621 4 070 1 585 3 136 Encryption 600 4875 1 871 3 724 AES 192 CCM Decryption 609 4727 1871 3 699 Encryption 807 5 509 2157 4289 AES 256 CCM Decryption 819 5 245 2157 4270 To process a message of 16 bytes of header and 32 bytes of payload with AES 128 in GCM mode and software optimized for speed would require 12 570 3 368 1314 x 1 3043x 2 23 338 clock cycles The required sizes for the algorithms are shown below The Context size is the amount of RAM memory required to store a context of the Mod
119. of GCM the amount is significant Table 132 Code size for authenticated encryption algorithm amp HW acceleration 124 131 E Code size a Context size Algorithm mode byte Constant data size byte byte AES 128 192 256 GCM 3 538 880 2360 AES 128 192 256 CCM 3 886 0 332 DocID14989 Rev 4 ky UMO586 Cryptographic library performance and memory requirements 11 3 AES key wrap results 11 3 1 Software optimized for speed Table 133 shows the results of AES Key Wrap Unwrap using all the three AES supported key sizes for software optimized for speed Table 133 AES Key Wrap Unwrap in software Algorithm Mode Wrapping 128 bits Wrapping 192 bits Wrapping 256 bits Key wrap 23 976 27 537 31 083 AES 128 KW Key unwrap 23 364 27 456 31 485 Key wrap 38 484 43 761 AES 192 KW Key unwrap 38 685 44 334 Key wrap 56 511 AES 256 KW Key unwrap 56 976 Table 134 Code size for AES key wrap unwrap in software Algorithm Code size byte Constant data size byte AES 128 KW 7274 6 040 AES 192 KW 7 274 6 040 AES 256 KW 7 274 6 040 1 Note that Key Wrap needs to allocate a memory whose size is equal to the input size plus 8 bytes 11 3 2 Hardware enhanced Table 135 AES key wrap unwrap with HW acceleration Algorithm Mode Wrapping 128 bits Wrapping 192 bits Wrapping 256 bits Key wrap 6 462 6 489 6 492 AES 128 K
120. of Authentication or error codes AES ERR BAD PARAMETER At least one parameter is a NULL pointer AUTHENTICATION SUCCESSFUL Unwrapped key produced by AES KeyWrap Decrypt Append is valid AUTHENTICATION FAILED Unwrapped key produced by AES KeyWrap Decrypt Append is not valid 2 DoclD14989 Rev 4 UMO586 AES algorithm 4 5 AES CMAC library functions Table 45 describes the AES CMAC library Table 45 AES CMAC algorithm functions Function name Description Initialization for AES CMAC for Authentication TAG AES CMAC Encrypt Init A Generation AES CMAC Encrypt Append AES Encryption in CMAC Mode AES CMAC Encrypt Finish AES Finalization of CMAC Mode Initialization for AES CMAC for Authentication TAG AES_CMAC_Decrypt_Init p Verification AES_CMAC_Decrypt_Append AES c Data Processing AES_CMAC_Decrypt_Finish AES Finalization of CMAC Mode The next flowchart describes the AES_CMAC algorithm 2 DoclD14989 Rev 4 53 131 AES algorithm UMO586 Figure 10 AES_CMAC flowchart Encryption Begin AES CMAC Encryption Initialization API AES_CMAC_ Encrypt Init error_status AES ERR BAD CONTEXT AES SUCCESS AES ERR BAD PARAMETER AES CMAC Encryption API AES CMAC Encrypt Append error status AES ERR BAD PARAMETER AES ERR BAD INPUT SIZE AES ERR BAD OPERATION AES SUCCESS AES CMAC Encryption Finalization API AES
121. on and decryption as the data stream is simply XORed with the generated key sequence The algorithm is serial as it requires successive exchanges of state entries based on the key sequence The STM32 cryptographic library includes functions required to support ARC4 a module to perform encryption and decryption using the following modes This algorithm can run with the STM32F1 STM32L1 STM32F20x STM32F05x STM32F40x STM32F37x and the STM32F30x series using a software algorithm implementation For ARC4 library settings refer to Section 10 STM32 encryption library settings For ARCA library performance and memory requirements refer to Section 11 Cryptographic library performance and memory requirements ARCA library functions Table 62 describes the ARC library AES functions Table 62 ARC4 algorithm functions Function name Description ARCA Encrypt Init Initialization for ARC4 algorithm ARC4 Encrypt Append ARC4 encryption ARC4_Encrypt_Finish ARC4 finalization ARC4 Decrypt Init Initialization for ARC4 algorithm ARC4_Decrypt_Append ARC4 decryption ARC4 Decrypt Finish ARC4 finalization The next flowchart describes the ARC4 algorithm DoclD14989 Rev 4 ky UMO586 ARCA algorithm Figure 12 ARC4 flowchart Encryption Begin ARC4 Encryption Initialization API ARC4 Encrypt Init error status ARC4 ERR BAD CONTEXT ARC4 ERR BAD PARAMETER kaa ARC4 Encryption AP
122. ontext in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P_pOutputSize Size Pointer to integer that will contain the size of written output data expressed in bytes TDES SUCCESS Operation Successful TDES ERR BAD PARAMETER At least one parameter is a NULL pointer TDES ERR BAD INPUT SIZE the P inputSize is not a multiple of Return value CRL DES BLOCK or less than 8 DMA BAD ADDRESS Input or output buffer addresses are not word aligned DMA ERR TRANSFER Error occurred in the DMA transfer TDES ERR BAD OPERATION Append not allowed Parameter 1 TTT is ECB or CBC Note This function can be called multiple times provided that P inputSize is a multiple of 8 3 3 6 TDES TTT Decrypt Finish function Table 19 TDES TTT Decrypt Finish Function name TDES TTT Decrypt Finish int32 t TDES ECB Decrypt Finish TDESTTTctx stt P_pTDESECBctx Prototype uint8 t P pOutputBuffer int32 t P pOutputSize Behavior TDES Decryption Finalization of TTT Mode in out P_pTDESTTTctx DES TTT already initialized context Parameter out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer that will contain the size of written output data expressed in bytes TDES_SUCCESS Operation Successful TDES ERR BAD PARAMETER At least one parameter is
123. out P_pAESKWctx AES Key Wrap context Parameter in P_pKey Buffer with the Key KEK in P_plv Buffer with the 64 bits IV AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values Note 1 P pAESKWctx mkKeySize see AESKWctx_stt must be set with the size of the key prior to calling this function Otherwise the following predefined values can be used CRL_AES128KEY CRL_AES192_KEY CRL_AES256_KEY 2 P_pAESKWctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 3 If hardware support is enabled DMA will not be used even ifE SK USE DMA is set inside P_pAESKWctx gt mFlags as CCM is implemented with an interleaved operation and the AES engine is used one block at a time 4 NIST defines the IV equal to OxAGAGAGAGAGAGAGAG In this implementation is a required input and can assume any value but its size is limited to 8 bytes ky DoclD14989 Rev 4 51 131 AES algorithm UMO586 4 4 5 Note 4 4 6 52 131 AES_KeyWrap_Decrypt_Append function Table 43 AES KeyWrap Decrypt Append Function name Prototype AES KeyWrap Decrypt Append int32 t AES KeyWrap Decrypt Append AESKWctx_stt P_pAESKWctx const uint8_t P_pInputBuffer int32_t P_inputSize int8_t P_pOutputBuffer int32_t
124. phic library performance and memory requirements ECC library functions Table 96 ECC algorithm functions Function name Description ECCinitEC Initialize the elliptic curve parameters into a EC_stt structure ECCfreeEC De initialize an EC_stt context ECCinitPoint Initialize an ECC point ECCfreePoint Free Elliptic curve point ECCsetPointCoordinate Set the value of one of coordinate of an ECC point ECCgetPointCoordinate Get the value of one of coordinate of an ECC point ECCcopyPoint Copy an Elliptic Curve Point ECCinitPrivKey Initialize an ECC private key ECCfreePrivKey Free an ECC Private Key ECCsetPrivKeyValue Set the value of an ECC private key object from a byte array ECCgetPrivKeyValue Get the private key value from an ECC private key object ECCscalarMul Computes the point scalar multiplication kP k P ECDSAinitSign Initialize an ECDSA signature structure ECDSAfreeSign Free an ECDSA signature structure GEDERAELEI qndtare Set the value of the parameters one at a time of an ECDSAsignature_stt ECDSAget Signature Get the values of the parameters one at a time of an ECDSAsignature_stt ECDSAverify ECDSA signature verification with a digest input 2 DoclD14989 Rev 4 UMO586 ECC algorithm Table 96 ECC algorithm functions continued Function name Description ECCvalidatePubKey Checks the validity of a public key ECC
125. rameter is a NULL pointer AES ERR BAD INPUT SIZE P inputSize lt O P inputSize Yo 16 0 amp amp P pAESCMACctx gt mFlags amp E SK FINAL APPEND E SK FINAL APPEND AES ERR BAD OPERATION Append not allowed This function can be called multiple times with P inputSize multiple of 16 bytes The last call allows any positive value for P inputSize but flag E SK FINAL APPEND must be set inside P pAESCMACctx mFlags i e with a simple P pAESCMACctx gt mFlags E SK FINAL APPEND AES CMAC Decrypt Finish function Table 52 AES CMAC Decrypt Finish Function name AES CMAC Decrypt Finish int32 t AES CMAC Decrypt Finish AESCMACctx_stt P_pAESCMACctx Prototype uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior AES Finalization of CMAC Mode in out P pAESCMACctx AES CMAC already initialized context Parameter out P_pOutputBuffer Output buffer out P pOutputSize Size of written output data in uint8 t Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values see note AUTHENTICATION_SUCCESSFUL if the TAG is verified AUTHENTICATION_FAILED if the TAG is not verified This function requires P_pAESGCMctx gt pmTag to be set to a valid pointer to the tag to be checked P_pAESCMACctx gt mTagSize to contain a valid value between 1 and 16 D
126. re knowing that the hash has been generated by SHA 256 retval RSA_PKCS1v15_Sign amp privKey digest E_SHA256 signature if retval RSA_SUCCESS return ERROR Set pubKey pubKey pubKey pubKey values of public key mExponentSize sizeof public exponent pmExponent public_exponent mModulusSize sizeof modulus pmModulus modulus Verify the signature knowing that the hash has been generated by SHA 256 retval RSA_PKCS1v15_Verify amp pubKey digest E_SHA256 signature if retval SIGNATURE_VALID return ERROR else return OK 4 DoclD14989 Rev 4 95 131 ECC algorithm UMO586 9 9 1 9 2 96 131 ECC algorithm Description This section describes Elliptic Curve Cryptography ECC primitives an implementation of ECC Cryptography using Montgomery Multiplication ECC operations are defined for curves over GF p field Scalar multiplication is the ECC operation that it is used in ECDSA Elliptic Curve Digital Signature Algorithm and in ECDH Elliptic Curve Diffie Hellman protocol It is also used to generate a public key sign a message and verify signatures This mode can run in STM32F1 STM32L1 and STM32F2 series using a software algorithm implementation For ECC library settings refer to Section 10 STM32 encryption library settings For ECC library performance and memory requirements refer to Section 11 Cryptogra
127. t There are two structures that pass keys to the functions e RSAprivKey_stt for the private key e RSApubKey_stt for the public key The values of the byte arrays pointed to by the above structures as well as the signature must be byte arrays where the byte at index 0 represents the most significant byte of the integer modulus signature or exponent All members of the above functions should be filled by the user before calls to the following RSA functions e RSA PKCS1v15 Sign e RSA PKCS1v15 Verify Note that the configuration switch RSA_WINDOW_SIZE can speedup operations with the private key at the expense of RAM memory Please refer to Section 10 STM32 encryption library settings for more detail These modes can run in STM32F1 STM32L1 STM32F2 STM32F05x STM32F4 and STM32F3 series using a software algorithm implementation For RSA library performance and memory requirements refer to Section 11 Cryptographic library performance and memory requirements RSA library functions Table 90 RSA algorithm functions Function name Description RSA_PKCS1v15_Sign PKCS 1v1 5 RSA Signature Generation Function RSA_PKCS1v15_Verify PKCS 1v1 5 RSA Signature Verification Function RSASP1 PKCS 1v1 5 RSA function for Signature Generation RSAVP1 PKCS 1v1 5 RSA function for Signature Verification The flowchart below describes the RSA algorithm DoclD14989 Rev 4 91 131 RSA algorithm UMO586 Figure 15 RSA flo
128. t one parameter is a NULL pointer AES_ERR_BAD_OPERATION Append not allowed Parameter 1 This function can be called multiple times provided that P_inputSize is a multiple of 16 A single final call with P_inputSize not multiple of 16 is allowed 4 DoclD14989 Rev 4 63 131 AES algorithm UMO586 4 6 4 AES CCM E ncrypt Finish function Table 58 AES CCM Encrypt Finish Function name AES CCM Encrypt Finish int32 t AES CCM Encrypt Finish AESCCMctx stt P pAESCCMctx Prototype uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior AES CCM Finalization during encryption this will create the Authentication TAG in out P pAESCCMctx AES CCM already initialized context Parameter out P_pOutputBuffer Output Authentication TAG out P pOutputSize Size of returned TAG Return value AES_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer Note This function requires P pAESCCMctx gt mTagSize to contain a valid value in the set 4 6 8 10 12 14 64 131 16 2 DoclD14989 Rev 4 UMO586 AES algorithm 4 6 5 AES CCM Decrypt Init function Table 59 AES CCM Decrypt Init Function name AES CCM Decrypt Init int32 t AES CCM Decrypt Init AESCCMctx stt P pAESCCMctx Prototype const uint8_t P_pKey const uint8_t P_pNonce Behavior Initializat
129. t when the last append has been called Used where E_SK_NO_MORE_APPEND the append is called with an InputSize not multiple of the block size which means that is the last input E SK NO MORE HEAD ER _APPEND_ALLOWED Internal Flag only for authenticated encryption modes It is set when the last header append has been called Used where the header append is called with an InputSize not multiple of the block size which means that is the last input E_SK_APPEND_DONE Internal Flag not used in this algorithm 2 DoclD14989 Rev 4 UMO586 DES and Triple DES algorithms 3 2 2 DES_DDD_Encrypt_Append function Table 6 DES DDD Encrypt Append Function name Prototype DES DDD Encrypt Append int32 t DES DDD Encrypt Append DESDDDctx_stt P_pDESDDDctx const uint8_t P_pInputBuffer int32_t P_inputSize uint8_t P_pOutputBuffer int32_t P_pOutputSize Behavior DES Encryption in DDD mode Parameter in P_pDESDDDctx DES DDD already initialized context in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P pOutputSize Size Pointer to integer that will contain the size of written output data expressed in bytes Return value DES SUCCESS Operation Successful DES ERR BAD PARAMETER At least one parameter is a NULL po
130. t with the size of the key prior to calling this function Otherwise the following predefined values can be used CRL_AES128_KEY CRL_AES192_KEY CRL_AES256_KEY 3 P_pAESCMACctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 4 P_pAESCMACctx mTagSize must be set with the size of authentication TAG that will be generated by the AES CMAC Encrypt Finish 5 If hardware support is enabled DMA will not be used even ifE SK USE DMA is set inside P_pAESCMACctx gt mFlags as CCM is implemented with an interleaved operation and the AES engine is used one block at a time AESCMACctx_stt data structure Table 47 AESCMACctx_stt data structure Field name Description uint32_t mContextId Unique ID of this AES GCM Context Not used in this implementation 32 bit mFlags used to perform keyschedule see SKflags_et mFlags SKflags_et milage choose between hw sw hw dma and future use const uint8_t pmKey Pointer to original Key buffer const uint8 t pmIv Pointer to original initialization vector buffer int32 t mIvSize Initialization vector size bytes Must be set by caller prior to calling Init uint32 t amIv 4 This is the current IV value int32 t mKeySize AES Key length in bytes Must be set by the caller prior to calling Init uint32 t amExpKey CRL AES Key length in bytes This must be set by the caller prior to calling AES MAX EXPKEY SIZE Init
131. textId Unique ID of this context Not used in current implementation Table 14 TDESTTTctx stt data structure SKflags et mFlags 32 bit mFlags used to perform keyschedule see SKflags et mFlags const uint8 t pmKey Pointer to original Key buffer const uint8_t pmIv Pointer to original Initialization Vector buffer int32_t mIvSize Size of the Initialization Vector in bytes uint32 t amIv 2 Temporary result IV uint32 t amExpKey 96 Expanded TDES key 26 131 2 DoclD14989 Rev 4 UMO586 DES and Triple DES algorithms 3 3 2 TDES_TTT_Encrypt_Append function Table 15 TDES_TTT_Encrypt_Append Function name TDES TTT Encrypt Append int32 t TDES TTT Encrypt Append TDESTTTctx_stt P_pTDESTTTctx const uint8_t P_pInputBuffer Prototype int32 t P inputSize uint8 t P pOutputBuffer int32 t P pOutputSize Behavior TDES Encryption in TTT mode in P_pTDESTTTctx TDES TTT already initialized context in P_pInputBuffer Input buffer Parameter in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P pOutputSize Size Pointer to integer that will contain the size of written output data expressed in bytes TDES_SUCCESS Operation Successful TDES ERR BAD PARAMETER At least one parameter is a NULL pointer TDES ERR BAD INPUT SIZE the P inputSize
132. ties This folder contains the abstraction layer that allows interaction with the human interface resources buttons LEDs LCD and COM ports USARTs available on STMicroelectronics evaluation boards All examples provided in this package are independant of external hardware DoclD14989 Rev 4 15 131 DES and Triple DES algorithms UMO586 3 3 1 16 131 DES and Triple DES algorithms Description The data encryption standard DES is a symmetric cipher algorithm that can process data blocks of 64 bits under the control of a 64 bit key The DES core algorithm uses 56 bits for enciphering and deciphering and 8 bits for parity so the DES cipher key size is 56 bits The DES cipher key size has become insufficient to guarantee algorithm security thus the Triple DES TDES has been devised to expand the key from 56 bits to 168 bits 56 x 3 while keeping the same algorithm core The Triple DES is a suite of three DES in series making three DES encryptions with three different keys The STM32 cryptographic library includes the functions required to support DES and Triple DES modules to perform encryption and decryption using the following modes e ECB Electronic Codebook Mode e CBC Cipher Block Chaining These modes can run with the STM32F1 STM32L1 STM32F20x STM32F05x STM32F40x STM32F37x and the STM32F30x series using a software algorithm implementation You can optimize the performance by using pure hardware a
133. tion 624 673 1 628 AES 128 CTR Decryption 621 689 1 628 Encryption 636 639 1575 AES 128 CMAC Decryption 618 525 1575 Encryption 621 676 1911 AES 192 CTR Decryption 618 691 1911 Encryption 632 719 1 859 AES 192 CMAC Decryption 616 608 1 859 Encryption 828 730 2 180 AES 256 CTR Decryption 825 746 2 180 Encryption 840 758 2 141 AES 256 CMAC Decryption 816 649 2 141 Encryption 0 6 059 25 ARC4 Decryption 0 6 059 25 1 Block of data represent 8 bytes for DES and TDES 16 for AES 1 for ARC4 DoclD14989 Rev 4 119 131 Cryptographic library performance and memory requirements UMO586 120 131 Table 126 Code size required by symmetric key encryption algo Algorithm mode Code size byte Constant data size byte DES TDES ECB CBC 3 842 6 040 AES 128 192 256 ECB CBC 8 068 6 040 AES 128 192 256 CTR 4 896 6 040 AES 128 192 256 CMAC 5 796 6 040 ARC4 686 0 DoclD14989 Rev 4 2 UMO586 Cryptographic library performance and memory requirements 11 1 2 Hardware enhanced Table 127 shows the performance calculated for symmetric key encryption algorithms with hardware acceleration The code size required by these algorithms is shown in Table 128 All AES modes except CMAC are shown as associated because the hardware supports all of them so removing one would not significantly decrease the code size Table 127 Symmetric key encrypt algo performance with HW acceler
134. ts e For other modes CCM GCM CMAC KEY WRAP run using software algorithm implementation For AES library settings refer to Section 10 STM32 encryption library settings For AES library performances and memory requirements refer to Section 11 Cryptographic library performance and memory requirements AES library functions ECB CBC and CTR Table 20 describes the AES functions of the encryption library Table 20 AES algorithm functions AAA ECB CBC or CTR Function name Description AES AAA Encrypt_Init Loads the key and ivec performs key schedule AES AAA Encrypt Append Launches cryptographic operation can be called several times AES AAA Encrypt Finish AES encryption finalization of AAA mode AES AAA Decrypt Init Loads the key and ivec eventually performs key schedule AES AAA Decrypt Append Launches cryptographic operation can be called several times AES AAA Decrypt Finish AES decryption finalization of AAA mode DoclD14989 Rev 4 31 131 AES algorithm UMO586 32 131 AAA represents the mode of operations of the AES algorithm The following modes of operation can be used for AES algorithm e ECB e CBC CTR Figure 7 describes the AES_AAA algorithm For example if you want to use ECB mode for an AES algorithm you can use the following functions Table 21 AES ECB algorithm functions Function name Description ES_ECB_Encrypt_Init Loads the key and ivec performs key schedule
135. tx Prototype uint8 t P pOutputBuffer int32 t P pOutputSize Behavior AES GCM Finalization during encryption this will create the Authentication TAG in out P_pAESGCMctx AES GCM already initialized context Parameter out P_pOutputBuffer Output Authentication TAG out P_pOutputSize Size of returned TAG Return value AES_SUCCESS Operation Successful AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values See note 1 This function requires P_pAESGCMctx mTagSize to contain a valid value between 1 and 16 2 DoclD14989 Rev 4 UMO586 AES algorithm 4 3 5 AES GCM Decrypt Init function Table 35 AES GCM Decrypt Init Function name AES GCM Decrypt Init int32 t AES GCM Decrypt Init AESGCMctx_stt P_pAESGCMctx Prototype i const uint8_t P_pKey const uint8_t P_plv Behavior Initialization for AES GCM Decryption in out P_pAESGCMctx AES GCM context Parameter in P_pKey Buffer with the Key in P_plv Buffer with the IV AES_SUCCESS Operation Successful Return value AES_ERR_BAD_PARAMETER At least one parameter is a NULL pointer AES_ERR_BAD_CONTEXT Context not initialized with valid values Note 1 P_pAESGCMctx mKeySize see AESGCMctx_stt must be set with the size of the key prior to calling this function Otherwise the
136. ue ID of this context Not used in current implementation SKflags_et mFlags 32 bit mFlags used to perform keyschedule see SKflags et mFlags const uint8 t pmkey Pointer to original key buffer const uint8 t pmIv Pointer to original initialization vector buffer int32 t mIvSize Size of the initialization vector in bytes uint32 t amIv 2 Temporary result IV uint32 t amExpKey 32 Expanded DES key SKflags et mFlags Enumeration of allowed flags in a context for symmetric key operations 4 DoclD14989 Rev 4 19 131 DES and Triple DES algorithms UMO586 20 131 Table 5 SKflags_et mFlags _ALLOWED Field name Description E_SK_DEFAULT User Flag No flag specified This is the default value for this flag f f User Flag Forces the initialization to not perform key schedule E_SK_DONT_PERFORM_K a 3 EY SCHEDULE The classic example is where the same key is used on a new message a i In this case redoing key scheduling is a waste of computation User Flag Used when there is a HW engine for DES It specifies E SK USE DMA whether DMA or CPU should transfer data It is common to always use the DMA except when DMA is very busy or input data is very small E SK FINAL APPEND User Flag Must be set in some modes before final Append call occurs ee Internal Flag Checks that the Finish function has been called Internal Flag Se
137. ult CRL AES BLOCK prior to calling this function AESAAActx_stt data structure Structure type for public key Table 23 AESAAActx stt data structure Field name Description uint32 t mContextId Unique ID of this context Not used in current version SKflags et mFlags 32 bit mflags performs keyschedule see SKflags et mFlags const uint8 t pmKey Pointer to original Key buffer const uint8 t pmIv Pointer to original Initialization Vector buffer int32 t mIvSize Size of the Initialization Vector in bytes uint32 t amlv 4 Temporary result IV uint32 t mKeySize Key length in bytes uint32_t ee ed Expanded DES key CRL AES MAX EXPKEY SIZE DoclD14989 Rev 4 ky UMO586 AES algorithm 4 2 2 AES_AAA Encrypt_Append function Table 24 AES_AAA Encrypt_Append Function name AES AAA Encrypt Append int32 t AES AAA Encrypt Append AESAAActx stt P_pAESAAActx const uint8 t P pInputBuffer int32 t P inputSize uint8 t P pOutputBuffer int32 t P pOutputSize Behavior AES Encryption in AAA Mode in P_pAESAAActx AES AAA already initialized context in P_pInputBuffer Input buffer in P_inputSize Size of input data expressed in bytes out P_pOutputBuffer Output buffer out P_pOutputSize Pointer to integer containing size of written output data expressed in bytes AES SUCCESS Operation Successful AES ERR BAD PARAMETER At least one parameter
138. values inside P pECctx are invalid ERR MEMORY FAIL Not enough memory Return value Note 1 Not every parameter needs to be loaded It depends on the operation Every operation requires at least a and p and n Set Generator requires Gx and Gy Verification of the validity of a public key requires b 2 P_pMemBuf must be initialized before calling this function See membuf stt 3 This function keeps some values stored in membuf_stt pmBuf so on exiting membuf sttmUsed won t be set to zero The caller can use the same P pMemBuf also for other functions The memory is freed when ECCfreeEC is called EC stt data structure Structure used to store the parameters of the elliptic curve actually selected Elliptic Curve equation over GF p y 2 x 3 ax b mod p Structure that keeps the Elliptic Curve Parameters Table 98 EC_stt data structure Field name Description const uint8_t pmA Pointer to parameter a int32_t mAsize Size of parameter a const uint8_t pmB Pointer to parameter b int32_t mBsize Size of parameter b const uint8_t pmP Pointer to parameter p int32_t mPsize Size of parameter p const uint8_t pmN Pointer to parameter n int32_t mNsize Size of parameter n const uint8_t pmGx Pointer to x coordinate of generator point int32_t mGxsize Size of x coordinate of generator point const uint8 t7 pmGy Pointer to y coordi
139. wchart HASH Initialization API HASH Init error_status HASH_ERR_BAD_PARAMETER HASH_SUCCESS HASH Data Process API HASH Append error status gt HASH_ERR_BAD_PARAMETER HASH_ERR_BAD_OPERATION DMA_BAD_ADDRESS only if HASH MD5 or SHA1 DMA_ERR_TRANSFER only if HASH MD5 or SHA1 HASH Finalization API HASH Finish error status Lg HASH ERR BAD PARAMETER HASH ERR BAD CONTEXT HASH SUCCESS RSA PKCS 1 Signature Verification API RSA PKCS1v15 Verify error status RSA ERR BAD PARAMETER RSA ERR UNSUPPORTED HASH RSA ERR BAD KEY ERR MEMORY FAIL RSA SUCCESS HASH Initialization API HASH Init RSA ERR MODULUS TOO SHORT Note HASH can be MD5 SHA1 SHA224 or SHA256 92 131 DoclD14989 Rev 4 y error_status HASH_ERR_BAD_PARAMETER HASH_SUCCESS HASH Data Process API HASH Append error status HASH ERR BAD PARAMETER HASH ERR BAD OPERATION DMA BAD ADDRESS only if HASH MD5 or SHA1 DMA_ERR_TRANSFER only if HASH MD5 or SHA1 HASH Finalization API HASH Finish error status HASH SUCCESS HASH ERR BAD PARAMETER HASH SUCCESS HASH_ERR_BAD_CONTEXT RSA PKCS 1 Signature Generation API RSA_PKCS1v15_ Sign error status SIGNATURE INVALID RSA ERR BAD PARAMETER RSA ERR UNSUPPORTED HASH ERR MEM
140. we 75 6 2 1 RNGreseed function EE EE eee ee 71 6 2 2 RNGinit function EE EE EE EE ee 78 6 2 3 RNGfree function EE EE EE EE EE ee 79 6 2 4 RNGgenBytes function EE EE SE eae 79 6 2 5 RNGgenWords function 80 6 3 RNG example se EE a RE ER EE BR EE a RES EE RE Ee 81 7 HASH algorithm si sies SP REDEN KAPANALIGAN stewed 82 7 1 Description ORR a ON EE N A 82 7 2 HASH library functions sans ao GE RR ms ia 82 7 2 1 HAH Init fUNG ON Casa ia pele a a DA EO EE 85 7 2 2 HHH Append function 2 00 ee cee eee 86 7 2 3 HHH Finish function se EE EE EE Se ee a a ee a ee ee 87 7 2 4 HMAC HHH Init function 0 Se eee ee ees 87 7 2 5 HMAC HHH Append function 00 ceeeeee 88 7 2 6 HMAC HHH Finish function o 89 7 3 HASH SHA1 example 2 2 22 EE SE SE SE SE ee ee eee 90 8 RSA algorithm scada rr AA 91 8 1 Description eee 91 8 2 RSA library functions so ma EER ia KG pio ta eve E ED aa 91 8 2 1 RSA PKCS1v15 Sign function 93 8 2 2 RSA PKCS1v15 Verify function EE EE EE EE Ee ee ee 94 8 3 RSA Signature generation verification example 95 4 131 DoclD14989 Rev 4 ky UMO586 Contents 9 ECC algorithm EE EE ER EE EE RE EE EE 96 9 1 Description eee 96 9 2 ECC library functions cada tea eh E A a 96 9 2 1 ECCinitEC function EE EE EE Se ee ee ee ee ee 101 9 2 2 ECCfreeEC function EE EE ooo 102 9 2 3 ECCinitPoint function
141. with Hardware RNG pheripheral for STM32F20x families M3_CryptoFW_2_0_6 lib STM32 Cryptographic Library Firmware for STM32F10x and STM32F3xx M3_CryptoFW_L1xx_2_0_6 lib STM32 Cryptographic Library Firmware for STM32L1xx families MO_CryptoFW_2_0_6 lib STM32 Cryptographic Library Firmware for STM32F0xx families inc contains all header files used by STM32 cryptographic library The remaining folders contain standard drivers for STM32 standard peripherals DoclD14989 Rev 4 hy UMO586 STM32 cryptographic library package presentation 2 2 2 2 2 3 Note Project This folder contains dedicated subfolders of STM32_Cryptographic_Examples that contain sets of examples by algorithms as presented in Figure 4 We provide a project template for EWARM MDK ARM tool chain for each STM32 series STM32F0xx STM32F2xx STM324xx STM3210 STM32F30x STM32F37x and STM32L1xx Figure 4 Project folder organization W STM32_Cryptographic_Lib_VX Y Z di _htmresc d Libraries d Project W STM32_Cryptographic _Examples Ji AES J AES128_CTR J AES192 CBC Ly AES256_ECB Je ARCA de Ecc Ji HASH Ji RAND y RSA TDES DES W STM32F0xx_Cryptographic_Templates Wi STM32F2xx_Cryptographic_Template W STM32F4xx_Cryptographic_Templates W STM32F10x_Cryptographic_Template Y STM32F30x Cryptographic Templates W STM32F37x_Cryptographic_Templates di STM32L1xx_Cryptographic_Templates Ji Utilities N STM32 EVAL y main c readme tet Utili
142. y time it depends on the user need RNG_ERR_BAD_PARAMETER RNG_ERR_UNINIT_STATE MS30075V1 2 76 131 DoclD14989 Rev 4 UMO586 RNG algorithm 6 2 1 RNGreseed function Table 71 RNGreseed Prototype Function name RNGreseed int32_t RNGreseed const RNGreInput_stt P pInputData RNGstate_stt P pRandomState Behavior Reseed the random engine Parameter in P_pInputData Pointer to a client in initialized RNGrelnput_stt structure containing the required parameters for a DRBG reseed in out P pRandomState The RNG status that will be reseeded Return value RNG_SUCCESS Operation Successful RNG ERR BAD ADD INPUT SIZE Wrong size for P_pAddInput It must be less than CRL DRBG AES MAX ADD INPUT LEN RNG ERR BAD ENTROPY SIZE Wrong size for P entropySize RNGrelnput stt struct reference Structure used by RNGinit to initialize a DRBG Table 72 RNGrelnput_stt struct reference Field name Description uint8 t pmEntropyData The entropy data input int32_t mEntropyDataSize Size of entropy data input uint8_t pmAddInput Additional input int32_t mAddInputSize Size of additional input RNGstate_stt struct reference Structure that contains the by RNG state uint8_t Field name Description mRNGstate CRL_DRBG_AES128_ Underlying DRBG context It is initialized by RNGinit STATE_SIZE int32_t mDRBGtype Spe
143. y the HMAC_HHH_Finish Possible values are from 1 to CRL_HHH_SIZE ky DoclD14989 Rev 4 87 131 HASH algorithm UMO586 HMACctx_stt struct reference Structure for HMAC context Table 87 HMACctx_stt struct reference Field name Description uint32 t mContextId Unique ID of this context Not used in current implementation 32 bit mFlags used to perform keyschedule see dashrlags et mFlags pashFlags et mFlags int32 t mTagSize Size of the required Digest const uint8 t pmKey Pointer for the HMAC key int32_t mKeySize Size in uint8_t bytes of the HMAC key uint8 t amKey64 Internal The HMAC key HASHctx_stt Internal Hash Context please refer to HASHctx_stt struct reference mHASHctx_st 7 2 5 HMAC_HHH_Append function Table 88 HMAC_HHH_Append Function name HMAC_HHH_Append int32 t HMAC HHH Append HMAC HHHctx stt P pHMAC HHHctx Prototype i const uint8_t P_pInputBuffer int32_t P_inputSize Behavior HMAC HHH Update function process input data and update a HMAC_HHHctx_stt in out P_pHMAC_HHHctx The HMAC HHH context that will be updated Parameter in P_pInputBuffer The data that will be processed using HMAC HHH in P_inputSize Size of input data expressed in bytes HASH_SUCCESS Operation Successful HASH_ERR_BAD_PARAMETER At least one parameter is a NULL pointer HASH_ERR_BAD_OPERATION HMAC_HHH_Append can t be ca
144. ze Behavior Generation of a random uint32 t array in out P pRandomState The random engine current state in P pAddinput Optional Additional Input can be NULL Parameter in Pp E j pan out P_pWordBuf The buffer where the uint32_t array will be stored in P_BufSize The number of uint32_t to generate Return value RNG_SUCCESS Operation Successful RNG_ERR_BAD_PARAMETER P_pRandomState NULL or P_pOutput NULL 88 P OutLen gt O RNG_ERR_UNINIT_STATE Random engine nat initialized RNG_ERR_RESEED_NEEDED Returned only if it s defined CRL_RANDOM_REQUIRE_RESEED If the count of number of requests between reseed has reached its limit Reseed is necessary 2 DoclD14989 Rev 4 UMO586 RNG algorithm 6 3 4 RNG example A simple random generation with C_SW_DRBG_AES128 is shown below include crypt h int32_t main Structure that will keep the random state RNGstate_stt RNGstate Structure for the parmeters of initialization RNGinitInput_stt RNGinit_st String of entropy uint8_t entropy_data 32 0x9d 0x20 Oxla 0x18 0x9b 0x6d Oxla 0xa7 0x0e 0x79 0x57 0 x6f 0x36 0xb6 Oxaa 0x88 0x55 Oxfd 0x4a 0x7 0x97 0xe9 0x71 0x69 0xb6 0x60 0x88 0x78 0xe1 0x9c 0x8b 0xa5 Nonce uint8_t nonce 4 0 1 2 3 array to keep the returned random bytes uint8_t randombytes 16 int32_t retval Initialize the RNGinit
145. ze 0 ECparams pmGy NULL ECparams mGysize 0 Call the Elliptic Curve initialization function retval ECCinitEC amp ECparams if retval 0 printf Error ECCinitEC returned d n retval return 1 Initialize the point that will contain the generator point retval ECCinitPoint amp G amp ECparams if retval 0 printf Error ECCinitPoint returned d n retval return 1 Set the coordinates of the generator point inside G rertval ECCsetPointGenerator G amp ECparams if retval 0 printf Error ECCsetPointGenerator returned d n retval return 1 Init the point the will keep the result of the scalar multiplication wif retval ECCinitPoint amp PubKey amp ECparams if retval 0 printf Error ECCinitPoint returned d n retval 4 DoclD14989 Rev 4 113 131 ECC algorithm UMO586 return 1 Initialize the private key object retval ECCinitPrivKey amp privkey amp ECparams if retval 0 printf Error ECCinitPrivKey returned d n retval return 1 Set the private key object retval ECCsetPrivKeyValue privkey ecc_160_privkey sizeof ecc 160 privkey if retval 0 printf Error ECCsetPrivKeyValue returned d n retval return 1 All ECCscalarMul parameters are initalized and set proceed retval ECCscalarMul G privkey PubKey amp E
146. ze must be set with the size of the key prior to calling this function Otherwise the following predefined values can be used CRL AES128 KEY CRL AES192 KEY CRL AES256 KEY 3 P_pAESCMACctx mFlags must be set prior to calling this function Default value is E SK DEFAULT See SKflags et for details 4 P_pAESCMACctx pmTag must be set with a pointer to the authentication TAG that will be checked during AES_CMAC_Decrypt_Finish 5 P_pAESCMACctx mTagSize must be set with the size of authentication TAG that will be generated by the AES_CMAC_Encrypt_Finish 6 If hardware support is enabled DMA will not be used even if E SK USE DMA is set inside P pAESCMACctx gt mFlags as CCM is implemented with an interleaved operation and the AES engine is used one block at a time DoclD14989 Rev 4 57 131 AES algorithm UMO586 4 5 5 Note 4 5 6 Note 58 131 AES_CMAC_Decrypt_Append function Table 51 AES_CMAC_Decrypt_Append Function name AES_CMAC_Decrypt_Append int32_t AES CMAC Decrypt Append AESCMACctx_stt P_pAESCMACctx Prototype const uint8 t P pInputBuffer int32 t P_inputSize Behavior AES CMAC Data Processing in out P pAESCMACctx AES CMAC already initialized context Parameter in P_pInputBuffer Input buffer in P inputSize Size of input data in uint8_t octets Return value AES SUCCESS Operation Successful AES ERR BAD PARAMETER At least one pa

UM0586 User manual - STMicroelectronics

Contents

Download Pdf Manuals

Related Search

Related Contents