UM0586 User manual. STM32 Cryptographic Library. Introduction

Transcription

1 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: 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 ARC4 DES, TripleDES. Supported modes are: ECB (Electronic Codebook Mode) CBC (Cipher-Block Chaining) HASH functions with HMAC support: MD5 SHA-1 SHA-224 SHA-256 Random engine based on DRBG-AES-128 RSA signature functions with PKCS#1v1.5 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 DocID14989 Rev 4 1/131

2 Contents UM0586 Contents 1 Terminology STM32 cryptographic library package presentation Architecture Package organization Libraries Project Utilities DES and Triple-DES algorithms Description DES library functions DES_DDD_Encrypt_Init function DES_DDD_Encrypt_Append function DES_DDD_Encrypt_Finish function DES_DDD_Decrypt_Init function DES_DDD_Decrypt_Append function DES_DDD_Decrypt_Finish function TDES library functions TDES_TTT_Encrypt_Init function TDES_TTT_Encrypt_Append function TDES_TTT_Encrypt_Finish function TDES_TTT_Decrypt_Init function TDES_TTT_Decrypt_Append function TDES_TTT_Decrypt_Finish function DES with ECB mode example AES algorithm Description AES library functions (ECB, CBC and CTR) AES_AAA_Encrypt_Init function AES_AAA_Encrypt_Append function AES_AAA_Encrypt_Finish function AES_AAA_Decrypt_Init function /131 DocID14989 Rev 4

3 Contents AES_AAA_Decrypt_Append function AES_AAA_Decrypt_Finish function AES GCM library functions AES_GCM_Encrypt_Init function AES_GCM_Header_Append function AES_GCM_Encrypt_Append function AES_GCM_Encrypt_Finish function AES_GCM_Decrypt_Init function AES_GCM_Decrypt_Append function AES_GCM_Decrypt_Finish function AES KeyWrap library functions AES_KeyWrap_Encrypt_Init function AES_KeyWrap_Encrypt_Append function AES_KeyWrap_Encrypt_Finish function AES_KeyWrap_Decrypt_Init function AES_KeyWrap_Decrypt_Append function AES_KeyWrap_Decrypt_Finish function AES CMAC library functions AES_CMAC_Encrypt_Init function AES_CMAC_Encrypt_Append function AES_CMAC_Encrypt_Finish function AES_CMAC_Decrypt_Init function AES_CMAC_Decrypt_Append function AES_CMAC_Decrypt_Finish function AES CCM library functions AES_CCM_Encrypt_Init function AES_CCM_Header_Append function AES_CCM_Encrypt_Append function AES_CCM_Encrypt_Finish function AES_CCM_Decrypt_Init function AES_CCM_Decrypt_Append function AES_CCM_Decrypt_Finish function AES CBC enciphering and deciphering example ARC4 algorithm Description DocID14989 Rev 4 3/131

4 Contents UM ARC4 library functions ARC4_Encrypt_Init function ARC4_Encrypt_Append function ARC4_Encrypt_Finish function ARC4_Decrypt_Init function ARC4_Decrypt_Append function ARC4_Decrypt_Finish function ARC4 example RNG algorithm Description RNG library functions RNGreseed function RNGinit function RNGfree function RNGgenBytes function RNGgenWords function RNG example HASH algorithm Description HASH library functions HHH_Init function HHH_Append function HHH_Finish function HMAC_HHH_Init function HMAC_HHH_Append function HMAC_HHH_Finish function HASH SHA1 example RSA algorithm Description RSA library functions RSA_PKCS1v15_Sign function RSA_PKCS1v15_Verify function RSA Signature generation/verification example /131 DocID14989 Rev 4

5 Contents 9 ECC algorithm Description ECC library functions ECCinitEC function ECCfreeEC function ECCinitPoint function ECCfreePoint function ECCsetPointCoordinate function ECCgetPointCoordinate function ECCgetPointFlag function ECCsetPointFlag function ECCcopyPoint function ECCinitPrivKey function ECCfreePrivKey function ECCsetPrivKeyValue function ECCgetPrivKeyValue function ECCscalarMul function ECCsetPointGenerator function ECDSAinitSign function ECDSAfreeSign function ECDSAsetSignature function ECDSAgetSignature function ECDSAverify function ECCvalidatePubKey function ECCkeyGen function ECDSAsign function ECC example STM32 encryption library settings Configuration parameters STM32_CryptoLibraryVersion Cryptographic library performance and memory requirements Symmetric key algorithms performance results Software optimized for speed Hardware enhanced DocID14989 Rev 4 5/131

6 Contents UM Authenticated encryption algorithms performance results Software optimized for speed Hardware enhanced AES key wrap results Software optimized for speed Hardware enhanced HASH and HMAC algorithm results Software optimized for speed Hardware enhanced RSA results ECC results Revision history /131 DocID14989 Rev 4

7 List of tables List of tables Table 1. DES algorithm functions (DDD = ECB or CBC) Table 2. DES ECB algorithm functions Table 3. DES_DDD_Encrypt_Init Table 4. DESDDDctx_stt data structure Table 5. SKflags_et mflags Table 6. DES_DDD_Encrypt_Append Table 7. DES_DDD_Encrypt_Finish Table 8. DES_DDD_Decrypt_Init Table 9. DES_DDD_Decrypt_Append Table 10. DES_DDD_Decrypt_Finish Table 11. TDES algorithm functions (TTT = ECB or CBC) Table 12. TDES ECB algorithm functions Table 13. TDES_TTT_Encrypt_Init Table 14. TDESTTTctx_stt data structure Table 15. TDES_TTT_Encrypt_Append Table 16. TDES_TTT_Encrypt_Finish Table 17. TDES_TTT_Decrypt_Init Table 18. TDES_TTT_Decrypt_Append Table 19. TDES_TTT_Decrypt_Finish Table 20. AES algorithm functions (AAA = ECB, CBC or CTR) Table 21. AES ECB algorithm functions Table 22. AES_AAA_Encrypt_Init Table 23. AESAAActx_stt data structure Table 24. AES_AAA_Encrypt_Append Table 25. AES_AAA_Encrypt_Finish Table 26. AES_AAA_Decrypt_Init Table 27. AES_AAA_Decrypt_Append Table 28. AES_AAA_Decrypt_Finish Table 29. AES GCM algorithm functions Table 30. AES_GCM_Encrypt_Init Table 31. AESGCMctx_stt data structure Table 32. AES_GCM_Header_Append Table 33. AES_GCM_Encrypt_Append Table 34. AES_GCM_Encrypt_Finish Table 35. AES_GCM_Decrypt_Init Table 36. AES_GCM_Decrypt_Append Table 37. AES_GCM_Decrypt_Finish Table 38. AES KeyWrap algorithm functions Table 39. AES_KeyWrap_Encrypt_Init Table 40. AES_KeyWrap_Encrypt_Append Table 41. AES_KeyWrap_Encrypt_Finish Table 42. AES_KeyWrap_Decrypt_Init Table 43. AES_KeyWrap_Decrypt_Append Table 44. AES_KeyWrap_Decrypt_Finish Table 45. AES CMAC algorithm functions Table 46. AES_CMAC_Encrypt_Init Table 47. AESCMACctx_stt data structure Table 48. AES_CMAC_Encrypt_Append DocID14989 Rev 4 7/131

8 List of tables UM0586 Table 49. AES_CMAC_Encrypt_Finish Table 50. AES_CMAC_Decrypt_Init Table 51. AES_CMAC_Decrypt_Append Table 52. AES_CMAC_Decrypt_Finish Table 53. AES CCM algorithm functions Table 54. AES_CCM_Encrypt_Init Table 55. AESCCMctx_stt data structure Table 56. AES_CCM_Header_Append Table 57. AES_CCM_Encrypt_Append Table 58. AES_CCM_Encrypt_Finish Table 59. AES_CCM_Decrypt_Init Table 60. AES_CCM_Decrypt_Append Table 61. AES_CCM_Decrypt_Finish Table 62. ARC4 algorithm functions Table 63. ARC4_Encrypt_Init Table 64. ARC4_Encrypt_Append Table 65. ARC4ctx_stt data structure Table 66. ARC4_Encrypt_Finish Table 67. ARC4_Decrypt_Init Table 68. ARC4_Decrypt_Append Table 69. ARC4_Decrypt_Finish Table 70. RNG algorithm functions Table 71. RNGreseed Table 72. RNGreInput_stt struct reference Table 73. RNGstate_stt struct reference Table 74. RNGinit Table 75. RNGstate_stt struct reference Table 76. RNGfree Table 77. RNGgenBytes Table 78. RNGgenWords Table 79. HASH algorithm functions (HHH = MD5, SHA1, SHA224 or SHA256) Table 80. HASH SHA1 algorithm functions Table 81. HHH_Init Table 82. HASHctx_stt struct reference Table 83. HashFlags_et mflags Table 84. HHH_Append Table 85. HHH_Finish Table 86. HMAC_HHH_Init Table 87. HMACctx_stt struct reference Table 88. HMAC_HHH_Append Table 89. HMAC_HHH_Finish Table 90. RSA algorithm functions Table 91. RSA_PKCS1v15_Sign function Table 92. RSAprivKey_stt data structure Table 93. membuf_stt data structure Table 94. RSA_PKCS1v15_Verify function Table 95. RSApubKey_stt data structure Table 96. ECC algorithm functions Table 97. ECCinitEC function Table 98. EC_stt data structure Table 99. ECCfreeEC function Table 100. ECCinitPoint function /131 DocID14989 Rev 4

9 List of tables Table 101. ECpoint_stt data structure Table 102. ECCfreePoint function Table 103. ECCsetPointCoordinate function Table 104. ECCgetPointCoordinate function Table 105. ECCgetPointFlag function Table 106. ECCsetPointFlag function Table 107. ECCcopyPoint function Table 108. ECCinitPrivKey function Table 109. ECCprivKey_stt data structure Table 110. ECCfreePrivKey function Table 111. ECCsetPrivKeyValue function Table 112. ECCgetPrivKeyValue function Table 113. ECCscalarMul function Table 114. ECCsetPointGenerator function Table 115. ECDSAinitSign function Table 116. ECDSAfreeSign function Table 117. ECDSAsetSignature function Table 118. ECDSAgetSignature function Table 119. ECDSAverify function Table 120. ECCvalidatePubKey function Table 121. ECCkeyGen function Table 122. ECDSAsign function Table 123. Library build options Table 124. STM32_CryptoLibraryVersion Table 125. Performance of symmetric key encryption algo. optimized for speed Table 126. Code size required by symmetric key encryption algo Table 127. Symmetric key encrypt. algo. performance with HW acceleration Table 128. Code size for symmetric key encryption algo. with HW acceleration Table 129. Clock cycles for authenticated encryption algorithms optimized for speed Table 130. Code size for authenticated encryption algorithms optimized for speed Table 131. Clock cycles for authenticated encryption algorithms & HW acceleration Table 132. Code size for authenticated encryption algorithm & HW acceleration Table 133. AES Key Wrap/Unwrap in software Table 134. Code size for AES key wrap/unwrap in software Table 135. AES key wrap/unwrap with HW acceleration Table 136. Code size for AES key wrap/unwrap with HW acceleration Table 137. Clock cycles for HASH and HMAC algorithms optimized for speed Table 138. Clock cycles for HASH and HMAC algorithms with SW acceleration Table 139. Clock cycles required by HASH/HMAC algorithms with HW acceleration Table 140. Code size required by HASH/HMAC algorithms Table 141. RSA performance with optimization for speed Table 142. Code size required by RSA algorithms Table 143. Number of cycles for ECC operations with for speed optimization Table 144. Code size for ECC operations with speed optimization Table 145. Document revision history DocID14989 Rev 4 9/131

10 List of figures UM0586 List of figures Figure 1. Block diagram of a common cipher Figure 2. STM32 cryptographic library architecture Figure 3. STM32 cryptographic library package organization Figure 4. Project folder organization Figure 5. DES DDD(*) flowchart Figure 6. TDES TTT(*) flowchart Figure 7. AES AAA(*) flowchart Figure 8. AES GCM flowchart Figure 9. AES_KeyWrap flowchart Figure 10. AES_CMAC flowchart Figure 11. AES_CCM flowchart Figure 12. ARC4 flowchart Figure 13. RNG flowchart Figure 14. Hash HHH flowchart Figure 15. RSA flowchart Figure 16. ECC Sign flowchart Figure 17. ECC Verify flowchart Figure 18. ECC key generator flowchart /131 DocID14989 Rev 4

11 Terminology 1 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 Cipher 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 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. In the case of an encryption, it is the input of the cipher, In the 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. DocID14989 Rev 4 11/131

12 STM32 cryptographic library package presentation UM STM32 cryptographic library package presentation 2.1 Architecture The library is built around a modular programming model ensuring: independencies between the components building the main application easy porting on a large product range 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 (1),(2) ) AES HASH Others Components CTR CCM SHA-1 MD5 Common Hardware abstraction layer (HAL) Note: Note: Note: 1. For algorithms that are not supported by the HW Cryptographic peripheral, only the firmware version will be available when enabling HW acceleration. 2. HW acceleration is only available for STM32F21x and STM32F41x devices. For other devices, all cryptographic algorithms are implemented in firmware. 3. CRC peripheral is used. The HAL controls the STM32 device registers and features based on two main libraries: CMSIS layer: Core Peripheral Access Layer. STM32xx Device Peripheral Access Layer. STM32 standard peripheral driver. 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 DocID14989 Rev 4

13 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. Application layer: The application layer consists of a set of examples covering all available algorithms with template projects for the most common development tools. 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 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. DocID14989 Rev 4 13/131

14 STM32 cryptographic library package presentation UM Libraries This folder contains two subfolders, CMSIS files and STM32 cryptographic library, followed by drivers for STM32 Standard Peripheral. CMSIS subfolder: contains STM32F0xx, STM32F2xx, STM32F4xx, STM32F10x, STM32F30x, STM32F37x and STM32L1xx CMSIS files STM32_Cryptographic_library: contains two subfolders: binary and inc binary: contains five STM32 cryptographic libraries for each Development Toolchain, in the EWARM and MDK-ARM subfolders: a) EWARM: Contains eight STM32 crytographic libraries compiled with IAR toolchain 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 STM32F10x and STM32F3xx. M3_CryptoFW_L1xx_2_0_6.a: STM32 Cryptographic Library Firmware for STM32L1xx families. M0_CryptoFW_2_0_6.a: STM32 Cryptographic Library Firmware for STM32F0xx families. b) 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 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. M0_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. 14/131 DocID14989 Rev 4

15 STM32 cryptographic library package presentation 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 Utilities Note: 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. DocID14989 Rev 4 15/131

16 DES and Triple-DES algorithms UM DES and Triple-DES algorithms 3.1 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 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: ECB (Electronic Codebook Mode) 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 accelerators 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. 16/131 DocID14989 Rev 4

17 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 DES_DDD_Encrypt_Append DES_DDD_Encrypt_Finish DES_DDD_Decrypt_Init DES_DDD_Decrypt_Append DES_DDD_Decrypt_Finish Description Initialization for DES Encryption in DDD mode DES Encryption in DDD mode DES Encryption Finalization of DDD mode Initialization for DES Decryption in DDD mode DES Decryption in DDD mode 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 DES_ECB_Encrypt_Init DES_ECB_Encrypt_Append DES_ECB_Encrypt_Finish DES_ECB_Decrypt_Init DES_ECB_Decrypt_Append DES_ECB_Decrypt_Finish Description Initialization for DES Encryption in ECB mode DES Encryption in ECB mode DES Encryption Finalization of ECB mode Initialization for DES Decryption in ECB mode DES Decryption in ECB mode DES Decryption Finalization in ECB mode Figure 5 describes the DES algorithm. DocID14989 Rev 4 17/131

18 DES and Triple-DES algorithms UM0586 Figure 5. DES DDD(*) flowchart Encryption Decryption Begin Begin DES Encryption Initialization API DES_DDD _Encrypt _Init DES De cryption Initialization API DES_DDD _De crypt _Init DES_SUCCESS - DES_ERR_BAD_CONTEXT (used only with CBC) - DES_ERR_BAD_PARAMETER DES_SUCCESS - DES_ERR_BAD_CONTEXT (used only with CBC) - DES_ERR_BAD_PARAMETER DES Encryption API DES_DDD_Encrypt_Append DES De cryption API DES _ DDD _Decrypt_ Append DES_SUCCESS - DES_ERR_BAD_PARAMETER - DES_ERR_BAD_INPUT_SIZE - DES_ERR_BAD_OPERATION - DMA_BAD_ADDRESS - DMA_ERR_TRANSFER DES_SUCCESS - DES_ERR_BAD_PARAMETER - DES_ERR_BAD_INPUT_SIZE - DES_ERR_BAD_OPERATION - DMA_BAD_ADDRESS - DMA_ERR_TRANSFER DES Encryptio n Finalization API DES _ DDD _ Encrypt _ Finish DES De cryption Finalization API DES_ DDD_ Decrypt_ Finish DES_SUCCESS DES_ERR_BAD_PARAMETER DES_SUCCESS DES_ERR_BAD_PARAMETER End End MS30067V1 18/131 DocID14989 Rev 4

19 DES and Triple-DES algorithms DES_DDD_Encrypt_Init function Function name DES_DDD_Encrypt_Init (1) Table 3. DES_DDD_Encrypt_Init int32_t DES_DDD_Encrypt_Init ( DESDDDctx_stt * P_pDESDDDctx, const uint8_t * P_pKey, const uint8_t * P_pIv ) Initialization for DES Encryption in DDD mode [in, out] *P_pDESDDDctx: DES DDD context [in] *P_pKey: Buffer with the Key [in] *P_pIv: Buffer with the IV (2) 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_pIv 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.mIvSize 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 uint32_t mcontextid SKflags_et mflags const uint8_t * pmkey const uint8_t * pmiv int32_t mivsize uint32_t amiv[2] uint32_t amexpkey[32] Description Unique ID of this context. Not used in current implementation 32 bit mflags, used to perform keyschedule see SKflags_et mflags Pointer to original key buffer Pointer to original initialization vector buffer Size of the initialization vector in bytes Temporary result/iv Expanded DES key SKflags_et mflags Enumeration of allowed flags in a context for symmetric key operations. DocID14989 Rev 4 19/131

20 DES and Triple-DES algorithms UM0586 Table 5. SKflags_et mflags Field name E_SK_DEFAULT E_SK_DONT_PERFORM_K EY_SCHEDULE E_SK_USE_DMA E_SK_FINAL_APPEND E_SK_OPERATION_COMP LETED E_SK_NO_MORE_APPEND _ALLOWED E_SK_NO_MORE_HEADER _APPEND_ALLOWED E_SK_APPEND_DONE Description User Flag: No flag specified. This is the default value for this flag User Flag: Forces the initialization to not perform key schedule. The classic example is where the same key is used on a new message. In this case redoing key scheduling is a waste of computation. User Flag: Used when there is a HW engine for DES. It specifies 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. User Flag: Must be set in some modes before final Append call occurs. Internal Flag: Checks that the Finish function has been called. Internal Flag: 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. 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. Internal Flag: not used in this algorithm 20/131 DocID14989 Rev 4

21 DES and Triple-DES algorithms DES_DDD_Encrypt_Append function Table 6. DES_DDD_Encrypt_Append Function name DES_DDD_Encrypt_Append (1) 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) DES Encryption in DDD mode [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 DES_SUCCESS: Operation Successful DES_ERR_BAD_PARAMETER: At least one parameter is a NULL pointer 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 DES_DDD_Encrypt_Finish function Table 7. DES_DDD_Encrypt_Finish Function name DES_DDD_Encrypt_Finish (1) int32_t DES_DDD_Encrypt_Finish ( DESDDDctx_stt * P_pDESDDDctx, uint8_t * P_pOutputBuffer, int32_t * P_pOutputSize ) DES Encryption Finalization of DDD mode [in,out] *P_pDESDDDctx: DES DDD, already initialized, context [out] *P_pOutputBuffer: Output buffer [out] *P_pOutputSize: Pointer to integer that will contain the size of written output data, expressed in bytes 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.it is kept for API compatibility. DocID14989 Rev 4 21/131

22 DES and Triple-DES algorithms UM DES_DDD_Decrypt_Init function Function name DES_DDD_Decrypt_Init (1) Table 8. DES_DDD_Decrypt_Init int32_t DES_DDD_Decrypt_Init ( DESDDDctx_stt * P_pDESDDDctx, const uint8_t * P_pKey, const uint8_t * P_pIv ) Initialization for DES Decryption in DDD Mode [in,out] *P_pDESDDDctx: DES DDD context [in] *P_pKey: Buffer with the Key [in] *P_pIv: Buffer with the IV (2) 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_pIv 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 before calling this function. Default value is E_SK_DEFAULT. See SKflags_et for details. 2. P_pDESCBCctx.mIvSize must be set with the size of the IV (default CRL_DES_BLOCK) prior to calling this function. 22/131 DocID14989 Rev 4

23 DES and Triple-DES algorithms DES_DDD_Decrypt_Append function Table 9. DES_DDD_Decrypt_Append Function name DES_DDD_Decrypt_Append (1) 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 ) DES Decryption in DDD mode [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 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 DES_DDD_Decrypt_Finish function Table 10. DES_DDD_Decrypt_Finish Function name DES_DDD_Decrypt_Finish (1) int32_t DES_ECB_Decrypt_Finish ( DESDDDctx_stt * P_pDESECBctx, uint8_t * P_pOutputBuffer, int32_t * P_pOutputSize ) DES Decryption Finalization of DDD Mode [in,out] *P_pDESDDDctx: DES DDD, already initialized, context [out] *P_pOutputBuffer: Output buffer [out] *P_pOutputSize: Pointer to integer that will contain the size of written output data, expressed in bytes 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.it is kept for API compatibility. DocID14989 Rev 4 23/131

24 DES and Triple-DES algorithms UM TDES library functions Table 11 describes the encryption library s TDES functions.below Table 11. TDES algorithm functions (TTT = ECB or CBC) Function name TDES_TTT_Encrypt_Init TDES_TTT_Encrypt_Append TDES_TTT_Encrypt_Finish TDES_TTT_Decrypt_Init TDES_TTT_Decrypt_Append TDES_TTT_Decrypt_Finish Description Initialization for TDES Encryption in TTT mode TDES Encryption in TTT mode TDES Encryption Finalization of TTT mode Initialization for TDES Decryption in TTT mode TDES Decryption in TTT mode 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: ECB 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 TDES_ECB_Encrypt_Init TDES_ECB_Encrypt_Append TDES_ECB_Encrypt_Finish TDES_ECB_Decrypt_Init TDES_ECB_Decrypt_Append TDES_ECB_Decrypt_Finish Description Initialization for TDES Encryption in ECB mode TDES Encryption in ECB mode TDES Encryption Finalization of ECB mode Initialization for TDES Decryption in ECB mode TDES Decryption in ECB mode TDES Decryption Finalization in ECB mode 24/131 DocID14989 Rev 4

25 DES and Triple-DES algorithms Figure 6. TDES TTT(*) flowchart Encryption Decryption Begin Begin TDES Encryption Initialization API TDES_TTT_Encrypt_Init TDES Decryption Initialization API TDES_TTT_ De crypt _Init TDES_SUCCESS - TDES_ERR_BAD_CONTEXT (used only with CBC) - TDES_ERR_BAD_PARAMETER TDES_SUCCESS - TDES_ERR_BAD_CONTEXT (used only with CBC) - TDES_ERR_BAD_PARAMETER TDES Encryption API TDES_TTT_Encrypt_Append TDES Decryption API TDES_TTT_ Decrypt_ Append TDES_SUCCESS - TDES_ERR_BAD_PARAMETER - TDES_ERR_BAD_INPUT_SIZE - TDES_ERR_BAD_OPERATION - DMA_BAD_ADDRESS - DMA_ERR_TRANSFER TDES_SUCCESS - TDES_ERR_BAD_PARAMETER - TDES_ERR_BAD_INPUT_SIZE - TDES_ERR_BAD_OPERATION - DMA_BAD_ADDRESS - DMA_ERR_TRANSFER TDES Encryption Finalization API TDES_TTT_ Encrypt_Finish TDES Decryption Finalization API TDES_TTT_ Decrypt_ Finish TDES_SUCCESS TDES_ERR_BAD_PARAMETER TDES_SUCCESS TDES_ERR_BAD_PARAMETER End End MS30068V1 DocID14989 Rev 4 25/131

26 DES and Triple-DES algorithms UM TDES_TTT_Encrypt_Init function Function name TDES_TTT_Encrypt_Init (1) Table 13. TDES_TTT_Encrypt_Init int32_t TDES_DDD_Encrypt_Init ( TDESTTTctx_stt * P_pTDESTTTctx, const uint8_t * P_pKey, const uint8_t * P_pIv ) Initialization for TDES Encryption in DDD Mode [in,out] *P_pTDESDDDctx: TDES TTT context [in] *P_pKey: Buffer with the Key [in] *P_pIv: Buffer with the IV (2) 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_pIv 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.mIvSize 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. Table 14. TDESTTTctx_stt data structure Field name uint32_t mcontextid SKflags_et mflags const uint8_t * pmkey const uint8_t * pmiv int32_t mivsize uint32_t amiv[2] uint32_t amexpkey[96] Description Unique ID of this context. Not used in current implementation 32 bit mflags, used to perform keyschedule, see SKflags_et mflags Pointer to original Key buffer Pointer to original Initialization Vector buffer Size of the Initialization Vector in bytes Temporary result/iv Expanded TDES key 26/131 DocID14989 Rev 4

27 DES and Triple-DES algorithms TDES_TTT_Encrypt_Append function Table 15. TDES_TTT_Encrypt_Append Function name TDES_TTT_Encrypt_Append (1) int32_t TDES_TTT_Encrypt_Append( TDESTTTctx_stt * P_pTDESTTTctx, const uint8_t * P_pInputBuffer, int32_t P_inputSize, uint8_t * P_pOutputBuffer, int32_t * P_pOutputSize) TDES Encryption in TTT mode [in] *P_pTDESTTTctx: TDES TTT, 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 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 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 TDES_TTT_Encrypt_Finish function Table 16. TDES_TTT_Encrypt_Finish Function name TDES_TTT_Encrypt_Finish (1) int32_t TDES_TTT_Encrypt_Finish ( TDESTTTctx_stt * P_pTDESTTTctx, uint8_t * P_pOutputBuffer, int32_t * P_pOutputSize ) TDES Encryption Finalization of TTT mode [in,out] *P_pTDESTTTctx: TDES TTT, already initialized, context [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 NULL pointer 1. TTT is ECB or CBC Note: This function won't write output data, thus it can be skipped.it is kept for API compatibility. DocID14989 Rev 4 27/131