PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference
Crypto (Cryptography)
PDL API Reference

## General Description

Note
  IP Supported: CRYPTO

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. You can also include cy_pdl.h to get access to all functions and declarations in the PDL.

The Crypto driver supports these standards: DES, TDES, AES (128, 192, 256 bits), CMAC-AES, SHA, HMAC, PRNG, TRNG, CRC, RSA, ECP, and ECDSA.

# Configuration Considerations

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_Core_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.

# Definitions

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.

# More Information

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.

## API Reference
| Direct Crypto Core Access
| Use the low-level API for direct access to the Crypto hardware.
| Common Data Structures
| Common Enumerated Types
| Common macro defines