 |
PSoC 6 Peripheral Driver Library
|
|
PSoC 6 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.
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). That key is one of the two prime factors of a very large number. The other prime factor is the recipient's private (secret) key. 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 other prime factor held in secret by the recipient). 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. Common, computationally intensive, asymmetric algorithms are RSA and ECC. 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 ). |
RSASSA-PKCS1-v1_5 described here, page 31: http://www.emc.com/collateral/white-papers/h11300-pkcs-1v2-2-rsa-cryptography-standard-wp.pdf
See the "Cryptographic Function Block" chapter of the Technical Reference Manual.
The Crypto driver has the following specific deviations:
| MISRA Rule | Rule Class (Required/Advisory) | Rule Description | Description of Deviation(s) |
|---|---|---|---|
| 8.8 | A | An external object or function shall be declared in one and only one file. | The pointer to the operation context memory can not be public accessible (can not be defined in the header file) but it should be extarnally accessed, because it is used by other Cypress software resources. |
| 11.4 | A | A cast should not be performed between a pointer to object type and a different pointer to object type. | The pointers to the context memory are void to allow handling of different data types for different operations. The cast operation is safe because the configuration is verified before operation is performed. |
| 16.7 | A | A pointer parameter in a function prototype should be declared as pointer to const if the pointer is not used to modify the addressed object. | The objects pointed to by the base addresses of the CRYPTO are not always modified. While a const qualifier can be used in select scenarios, it brings little benefit in adding this to the affected functions. |
| 20.6 | R | The macro offsetof, in library <stddef.h>, shall not be used. | The only HW block register offsets are defined using this macro. |
| Version | Changes | Reason for Change |
|---|---|---|
| 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 | |