cy_crypto_common_8h

This file provides common constants and parameters for the Crypto driver.

Copyright 2016-2020 Cypress Semiconductor Corporation SPDX-License-Identifier: Apache-2.0

Version

2.40

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

CY_CRYPTO_DRV_VERSION_MAJOR

Driver major version.

CY_CRYPTO_DRV_VERSION_MINOR

Driver minor version.

CY_CRYPTO_SYNC_BLOCKING

Defines Crypto_Sync blocking execution type parameter.

CY_CRYPTO_SYNC_NON_BLOCKING

Defines Crypto_Sync non-blocking execution type parameter.

CY_CRYPTO_DES_BLOCK_SIZE

Defines the Crypto DES block size (in bytes).

CY_CRYPTO_DES_KEY_SIZE

Defines the Crypto DES key size (in bytes)

CY_CRYPTO_TDES_KEY_SIZE

Defines the Crypto TDES key size (in bytes)

CY_CRYPTO_AES_BLOCK_SIZE

Defines the Crypto AES block size (in bytes)

CY_CRYPTO_AES_128_KEY_SIZE

Defines the Crypto AES_128 key maximum size (in bytes)

CY_CRYPTO_AES_192_KEY_SIZE

Defines the Crypto AES_192 key maximum size (in bytes)

CY_CRYPTO_AES_256_KEY_SIZE

Defines the Crypto AES_256 key maximum size (in bytes)

CY_CRYPTO_AES_MAX_KEY_SIZE

Defines the Crypto AES key maximum size (in bytes)

CY_CRYPTO_AES_MAX_KEY_SIZE_U32

Defines the Crypto AES_256 key maximum size (in four-byte words)

CY_CRYPTO_AES_BLOCK_SIZE_U32

Defines size of the AES block, in four-byte words.

CY_CRYPTO_SHA1_DIGEST_SIZE

Hash size for the SHA1 mode (in bytes)

CY_CRYPTO_SHA224_DIGEST_SIZE

Hash size for the SHA224 mode (in bytes)

CY_CRYPTO_SHA256_DIGEST_SIZE

Hash size for the SHA256 mode (in bytes)

CY_CRYPTO_SHA384_DIGEST_SIZE

Hash size for the SHA384 mode (in bytes)

CY_CRYPTO_SHA512_DIGEST_SIZE

Hash size for the SHA512 mode (in bytes)

CY_CRYPTO_SHA512_224_DIGEST_SIZE

Hash size for the SHA512_224 mode (in bytes)

CY_CRYPTO_SHA512_256_DIGEST_SIZE

Hash size for the SHA512_256 mode (in bytes)

CY_CRYPTO_SHA_MAX_DIGEST_SIZE

The maximal Hash size for the SHA modes (in bytes).

CY_CRYPTO_SHA1_BLOCK_SIZE

Block size for the SHA1 mode (in bytes)

CY_CRYPTO_SHA256_BLOCK_SIZE

Block size for the SHA256 mode (in bytes)

CY_CRYPTO_SHA512_BLOCK_SIZE

Block size for the SHA512 mode (in bytes)

CY_CRYPTO_SHA_MAX_BLOCK_SIZE

Maximal block size for the SHA modes (in bytes)

CY_CRYPTO_RSA1024_MESSAGE_SIZE

Processed message size for the RSA 1024Bit mode (in bytes)

CY_CRYPTO_RSA1536_MESSAGE_SIZE

Processed message size for the RSA 1536Bit mode (in bytes)

CY_CRYPTO_RSA2048_MESSAGE_SIZE

Processed message size for the RSA 2048Bit mode (in bytes)

CY_CRYPTO_RSA3072_MESSAGE_SIZE

Processed message size for the RSA 3072Bit mode (in bytes)

CY_CRYPTO_RSA4096_MESSAGE_SIZE

Processed message size for the RSA 4096Bit mode (in bytes)

CY_CRYPTO_ID

Crypto Driver PDL ID.

Typedefs

typedef void (*cy_crypto_callback_ptr_t)(void)

The Crypto user callback function type.

Callback is called at the end of Crypto calculation.

Enums

enum cy_en_crypto_lib_info_t

cy_en_crypto_lib_info_t: The Crypto library functionality level.

Values:

enumerator CY_CRYPTO_NO_LIBRARY
enumerator CY_CRYPTO_BASE_LIBRARY
enumerator CY_CRYPTO_EXTRA_LIBRARY
enumerator CY_CRYPTO_FULL_LIBRARY
enum cy_en_crypto_aes_key_length_t

cy_en_crypto_aes_key_length_t: The key length options for the AES method.

Values:

enumerator CY_CRYPTO_KEY_AES_128

The AES key size is 128 bits.

enumerator CY_CRYPTO_KEY_AES_192

The AES key size is 192 bits.

enumerator CY_CRYPTO_KEY_AES_256

The AES key size is 256 bits.

enum cy_en_crypto_dir_mode_t

cy_en_crypto_dir_mode_t: Defines the direction of the Crypto methods.

Values:

enumerator CY_CRYPTO_ENCRYPT

The forward mode, plain text will be encrypted into cipher text.

enumerator CY_CRYPTO_DECRYPT

The reverse mode, cipher text will be decrypted into plain text.

enum cy_en_crypto_sha_mode_t

cy_en_crypto_sha_mode_t: Defines modes of SHA method.

Values:

enumerator CY_CRYPTO_MODE_SHA1

Sets the SHA1 mode.

enumerator CY_CRYPTO_MODE_SHA224

Sets the SHA224 mode.

enumerator CY_CRYPTO_MODE_SHA256

Sets the SHA256 mode.

enumerator CY_CRYPTO_MODE_SHA384

Sets the SHA384 mode.

enumerator CY_CRYPTO_MODE_SHA512

Sets the SHA512 mode.

enumerator CY_CRYPTO_MODE_SHA512_256

Sets the SHA512/256 mode.

enumerator CY_CRYPTO_MODE_SHA512_224

Sets the SHA512/224 mode.

enum cy_en_crypto_rsa_ver_result_t

cy_en_crypto_rsa_ver_result_t: Signature verification status.

Values:

enumerator CY_CRYPTO_RSA_VERIFY_SUCCESS

PKCS1-v1.5 verify SUCCESS.

enumerator CY_CRYPTO_RSA_VERIFY_FAIL

PKCS1-v1.5 verify FAILED.

enum cy_en_crypto_status_t

cy_en_crypto_status_t: Errors of the Crypto block.

Values:

enumerator CY_CRYPTO_SUCCESS

Operation completed successfully.

enumerator CY_CRYPTO_HW_ERROR

A hardware error occurred, detailed information is in stc_crypto_hw_error_t.

enumerator CY_CRYPTO_SIZE_NOT_X16

The size of input data is not multiple of 16.

enumerator CY_CRYPTO_DES_WEAK_KEY

The key for the DES method is weak.

enumerator CY_CRYPTO_COMM_FAIL

Communication between the client and server via IPC is broken.

enumerator CY_CRYPTO_SERVER_NOT_STARTED

The Crypto server is not started.

enumerator CY_CRYPTO_SERVER_BUSY

The Crypto server in process state.

enumerator CY_CRYPTO_NOT_INITIALIZED

The Crypto driver is not initialized.

enumerator CY_CRYPTO_HW_NOT_ENABLED

The Crypto hardware is not enabled.

enumerator CY_CRYPTO_NOT_SUPPORTED

The Crypto operation is not supported.

enumerator CY_CRYPTO_BAD_PARAMS

The Crypto operation parameters are incorrect.

enum cy_en_crypto_ecc_curve_id_t

cy_en_crypto_ecc_curve_id_t: List of supported elliptic curve IDs.

Values:

enumerator CY_CRYPTO_ECC_ECP_NONE
enumerator CY_CRYPTO_ECC_ECP_SECP192R1
enumerator CY_CRYPTO_ECC_ECP_SECP224R1
enumerator CY_CRYPTO_ECC_ECP_SECP256R1
enumerator CY_CRYPTO_ECC_ECP_SECP384R1
enumerator CY_CRYPTO_ECC_ECP_SECP521R1
enumerator CY_CRYPTO_ECC_ECP_CURVES_CNT
enum cy_en_crypto_ecc_key_type_t

cy_en_crypto_ecc_key_type_t: An ECC key type.

Values:

enumerator PK_PUBLIC
enumerator PK_PRIVATE
struct cy_stc_crypto_config_t
#include <>

The Crypto configuration structure.

Public Members

uint32_t ipcChannel

Defines the IPC channel used for client-server data exchange.

uint32_t acquireNotifierChannel

Specifies the IPC notifier channel (IPC interrupt structure number) to notify server that data for the operation is prepared.

uint32_t releaseNotifierChannel

Specifies the IPC notifier channel (IPC interrupt structure number) to notify client that operation is complete and data is valid.

cy_stc_sysint_t releaseNotifierConfig

Specifies the release notifier interrupt configuration.

It used for internal purposes and user doesn’t fill it.

cy_crypto_callback_ptr_t userCompleteCallback

User callback function.

If this field is NOT NULL, it called when Crypto operation is complete.

cy_israddress userGetDataHandler

Server-side user IRQ handler function, called when data for the operation is prepared to process.

  • If this field is NULL, server will use own interrupt handler to get data.

  • If this field is not NULL, server will call this interrupt handler. This interrupt handler must call the Cy_Crypto_Server_GetDataHandler to get data to process.

    Note: In the second case user should process data separately and clear interrupt by calling Cy_Crypto_Server_Process. This model is used in the multitasking environment.

cy_israddress userErrorHandler

Server-side user IRQ handler function, called when a Crypto hardware error occurs (interrupt was raised).

  • If this field is NULL - server will use own interrupt handler for error processing.

  • If this field is not NULL - server will call this interrupt handler. This interrupt handler must call the Cy_Crypto_Server_ErrorHandler to clear the interrupt.

cy_stc_sysint_t acquireNotifierConfig

Specifies the prepared data notifier interrupt configuration.

It used for internal purposes and user doesn’t fill it.

cy_stc_sysint_t cryptoErrorIntrConfig

Specifies the hardware error processing interrupt configuration.

It used for internal purposes and user doesn’t fill it.

struct cy_stc_crypto_rsa_pub_key_t
#include <>

All fields for the context structure are internal.

Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

The driver uses this structure to store and manipulate the RSA public key and additional coefficients to accelerate RSA calculation.

RSA key contained from two fields:

  • n - modulus part of the key

  • e - exponent part of the key.

Other fields are accelerating coefficients and can be calculated by Cy_Crypto_Rsa_CalcCoefs.

note

The modulus and exponent values in the cy_stc_crypto_rsa_pub_key_t must also be in little-endian order.
Use Cy_Crypto_InvertEndianness function to convert to or from little-endian order.

struct cy_stc_crypto_hw_error_t
#include <>

Structure for storing a description of a Crypto hardware error.

Public Members

uint32_t errorStatus0

Captures error description information for one of obtained hardware error:

  • for INSTR_OPC_ERROR: - violating the instruction.

  • for INSTR_CC_ERROR : - violating the instruction condition code.

  • for BUS_ERROR : - violating the transfer address.

uint32_t errorStatus1

[31] - “1” - Indicates that hardware error has occured and ERROR_STATUS0 and ERROR_STATUS1 captured valid error-information.

[26..24] - The error source:

  • ”0”: INSTR_OPC_ERROR - an instruction decoder error.

  • ”1”: INSTR_CC_ERROR - an instruction condition code-error.

  • ”2”: BUS_ERROR - a bus master interface AHB-Lite bus-error.

    • [5..4] - violating the transfer, the size attribute

      • ”0”: an 8-bit transfer;

      • ”1”: 16 bits transfer;

      • ”2”: 32-bit transfer.

    • [0] - violating the transfer, read the attribute

  • ”3”: TR_AP_DETECT_ERROR - True Random Generator error.

struct cy_stc_crypto_aes_buffers_t
#include <>

The structure for storing the AES state.

All fields for this structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_aes_state_t
struct cy_stc_crypto_sha_state_t
#include <>

The structure for storing the SHA state.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_ecc_point
#include <>

A point on a ECC curve.

Public Members

void *x

The x co-ordinate.

void *y

The y co-ordinate.

struct cy_stc_crypto_ecc_key
#include <>

An ECC key.

Public Members

cy_en_crypto_ecc_key_type_t type

Type of key, PK_PRIVATE or PK_PUBLIC.

cy_en_crypto_ecc_curve_id_t curveID

See cy_en_crypto_ecc_curve_id_t.

cy_stc_crypto_ecc_point pubkey

The public key.

void *k

The private key.

struct cy_stc_crypto_server_context_t
#include <>

The structure for storing the crypto server context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_t
#include <>

The structure for storing the crypto client context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_des_t
#include <>

The structure for storing the DES context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_aes_t
#include <>

The structure for storing the AES context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_sha_t
#include <>

The structure for storing the SHA context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_prng_t
#include <>

The structure for storing the PRNG context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_trng_t
#include <>

The structure for storing the TRNG context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_str_t
#include <>

The structure for storing the string context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_crc_t
#include <>

The structure for storing the CRC context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_rsa_ver_t
#include <>

The structure for storing the RSA verification context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in the function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_rsa_t
#include <>

The structure for storing the RSA context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_crypto_context_ecc_t
#include <>

The structure for storing the ECC operations context.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.