 |
MTB CAT1 Peripheral driver library
|
|
MTB CAT1 Peripheral driver library
|
The Crypto driver provides a public API to perform cryptographic and hash operations, as well as generate both true and pseudo random numbers.
It uses a hardware IP block to accelerate operations.
The functions and other declarations used in this driver are in cy_crypto.h, cy_crypto_core.h, and cy_crypto_server.h. You can also include cy_pdl.h to get access to all functions and declarations in the PDL.
The driver implements two usage models:
Mixing these usage models will result in undefined behaviour.
The Crypto driver supports these standards: DES, TDES, AES (128, 192, 256 bits), CMAC-AES, SHA, HMAC, PRNG, TRNG, CRC, RSA, ECP, and ECDSA.
User can enable/disable cryptographic functionality based on the project requirements. To do so, create a configuration header file to configure cryptographic functionalities and define a macro CY_CRYPTO_USER_CONFIG_FILE with configuration header file name and add to project environment. If CY_CRYPTO_USER_CONFIG_FILE macro is not defined in project environment, firmware will enable all available cryptographic functionalities.
Firmware sets up a cryptographic operation by passing in the required data as parameters in the function calls.
All Crypto functions require a context. A context is a data structure that the driver uses for its operations. Firmware declares a context (allocates memory) but does not write or read the values in that context. In effect, the context is a scratch pad you provide to the driver. The driver uses the context to store and manipulate data during cryptographic operations.
Several methods require an additional context unique to the particular cryptographic technique. The Crypto driver header files declare all the required structures for both configuration and context.
Some encryption techniques require additional initialization specific to the technique. If there is an Init function, you must call it before using any other function for that technique, and re-initialize after you use a different encryption technique.
For example, use Cy_Crypto_Aes_Init to configure an AES encryption operation with the encryption key, and key length. Provide pointers to two context structures. You can then call the AES Run functions. If you use DES after that, you must re-initialize the AES encryption before using it again.
| Term | Definition |
|---|---|
| Plaintext | An unencrypted message |
| Ciphertext | An encrypted message |
| Block Cipher | An encryption function for fixed-size blocks of data. This function takes a fixed-size key and a block of plaintext data from the message and encrypts it to generate ciphertext. Block ciphers are reversible. The function performed on a block of encrypted data will decrypt that data. |
| Block Cipher Mode | A mode of encrypting a message using block ciphers for messages of an arbitrary length. The message is padded so that its length is an integer multiple of the block size. ECB (Electronic Code Book), CBC (Cipher Block Chaining), and CFB (Cipher Feedback) are all modes of using block ciphers to create an encrypted message of an arbitrary length. |
| Data Encryption Standard (DES) | The DES standard specifies a symmetric-key algorithm for encryption of electronic data. It uses a 56-bit key. The block size is 64-bits. |
| Triple DES (3DES or TDES) | The TDES standard specifies a symmetric-key block cipher that applies the Data Encryption Standard (DES) cipher algorithm three times to each data block. It uses three 56-bit keys. The block size is 64-bits. |
| Advanced Encryption Standard (AES) | The AES standard specifies the Rijndael algorithm, a symmetric block cipher that can process 128-bit data blocks, using cipher keys with 128-, 192-, and 256-bit lengths. Rijndael was designed to handle additional block sizes and key lengths. However, they are not adopted in this standard. AES is also used for message authentication. |
| Secure Hash Algorithm (SHA) | A cryptographic hash function. This function takes a message of an arbitrary length and reduces it to a fixed-length residue or message digest after performing a series of mathematically defined operations that practically guarantee that any change in the message will change the hash value. It is used for message authentication by transmitting a message with a hash value appended to it and recalculating the message hash value using the same algorithm at the recipient's end. If the hashes differ, then the message is corrupted. For more information see Secure Hash standard description. |
| Message Authentication Code (MAC) | MACs are used to verify that a received message has not been altered. This is done by first computing a MAC value at the sender's end and appending it to the transmitted message. When the message is received, the MAC is computed again and checked against the MAC value transmitted with the message. If they do not match, the message has been altered. Either a Hash algorithm (such as SHA) or a block cipher (such as AES) can be used to produce the MAC value. Keyed MAC schemes use a Secret Key along with the message, thus the Key value must be known to be able to compute the MAC value. |
| Cipher-based Message Authentication Code (CMAC) | A block cipher-based message authentication code algorithm. It computes the MAC value using the AES block cipher algorithm. For more information see Recommendation for Block Cipher Modes of Operation. |
| Hash Message Authentication Code (HMAC) | A specific type of message authentication code (MAC) that involves a cryptographic hash function and a secret cryptographic key. It computes the MAC value using a Hash algorithm. For more information see The Keyed-Hash Message Authentication Code standard |
| Pseudo Random Number Generator (PRNG) | A Linear Feedback Shift Registers-based algorithm for generating a sequence of numbers starting from a non-zero seed. |
| True Random Number Generator (TRNG) | A block that generates a number that is statistically random and based on some physical random variation. The number cannot be duplicated by running the process again. |
| Symmetric Key Cryptography | Uses a common, known key to encrypt and decrypt messages (a shared secret between sender and receiver). An efficient method used for encrypting and decrypting messages after the authenticity of the other party has been established. DES (now obsolete), 3DES, and AES (currently used) are well-known symmetric cryptography methods. |
| Asymmetric Key Cryptography | Also referred to as Public Key encryption. To receive a message, you publish a very large public key (up to 4096 bits currently). The public key is described by the pair (n, e) where n is a product of two randomly chosen primes p and q. The exponent e is a random integer 1 < e < Q where Q = (p-1) (q-1). The private key d is uniquely defined by the integer 1 < d < Q so that ed congruent with 1 (mod Q ). To send a message to the publisher of the public key, you encrypt the message with the public key. This message can now be decrypted only with the private key. The message is now sent over any channel to the recipient who can decrypt it with the private (secret) key. The same process is used to send messages to the sender of the original message. The asymmetric cryptography relies on the mathematical impracticality (usually related to the processing power available at any given time) of factoring the keys. |
RSASSA-PKCS1-v1_5 described here, page 31: https://www.rfc-editor.org/rfc/pdfrfc/rfc8017.txt.pdf
See the "Cryptographic Function Block" chapter of the Technical Reference Manual.
| Version | Changes | Reason for Change |
|---|---|---|
| 2.100 | Added SHA3, HKDF, AES multistage support for modes ECB, CBC, CFB CTR added | |
| 2.90 | Updated internal APIs and bug fixes. | Fixed GCM initialization and coverity bugs. |
| 2.80 | Added AES GCM support. | Driver enhancement. |
| 2.70 | Added TRNG enhancements to support health monitor check. | Driver enhancement and new feature addition. |
| 2.60 |
| Driver enhancement and new feature addition. |
| 2.50 | Fixed the Cy_Crypto_Core_ECC_VerifyHash() and an internal function behaviour to support 0 hash message. Resolved MISRA 2012 standard defects. | Defect fixing and MISRA 2012 compliance. |
| 2.40 | Resolve MISRA 2012 standard defects. | MISRA 2012 compliance. |
| 2.30.4 | Updated code snippets for client-server usage model. | Documentation enhancement. |
| 2.30.3 | Minor documentation updates. | Documentation enhancement. |
| 2.30.2 | Code formatting cleanup, updated copyright date. | PDL project update. |
| 2.30.1 | Added a C++ namespace guards. | Make a driver code to be compatible with C++. |
| 2.30 |
| Integration with mbedOS/mbedTLS, restructured the implementation of AES and SHA for the Crypto ALT interface. |
| 2.20 |
| ECC support added. Integration with mbedOS/mbedTLS, restructured the implementation of SHA and CRC for the Crypto ALT interface. |
| 2.11b | The same as production 2.10; only the newly-added Elliptic Curve point multiplication functionality (NIST P256) is pre-production. Open source under Apache version 2.0 license. | |
| 2.11 | Based on pre-production 2.10, except the newly-added Elliptic Curve point multiplication functionality (NIST P256). Does not incorporate the production level documentation. Open source under Apache version 2.0 license. | ECC support. |
| 2.10b | The same as production 2.10. Open source under Apache version 2.0 license. | |
| 2.10 | Flattened the organization of the driver source code into the single source directory and the single include directory. | Driver library directory-structure simplification. |
| Removed files with the default driver configuration. Added API functions to start different server functionality:
| ||
| Added the register access layer. Use register access macros instead of direct register access using dereferenced pointers. | Makes register access device-independent, so that the PDL does not need to be recompiled for each supported part number. | |
| Added precompiled libraries for the IAR toolchain. | IAR toolchain support in ModusToolbox. | |
| 2.0b | The same as production 2.0. Open source under Apache version 2.0 license. | |
| 2.0 | Clarified what parameters must be 4-byte aligned for the functions: Cy_Crypto_Aes_Cmac_Run, Cy_Crypto_Sha_Run, Cy_Crypto_Hmac_Run, Cy_Crypto_Str_MemCmp, Cy_Crypto_Trng_Generate, Cy_Crypto_Des_Run, Cy_Crypto_Tdes_Run, Cy_Crypto_Rsa_Proc | Documentation update and clarification. |
| Changed crypto IP power control. Enhanced Vector Unit functionality for RSA crypto algorithm. Added support of the single-core devices. | New device support. | |
| 1.0 | Initial version |
API Reference | |
| Client-Server Model | |
| Use the client-server API to isolate the Crypto hardware from non-secure application access. | |
| Direct Crypto Core Access | |
| Use the low-level API for direct access to the Crypto hardware. | |
| Common Data Structures | |
| Common Enumerated Types | |