MCUX CLNS MCUX Crypto Library Normal Secure |

User Guidance Manual

## General Information

- This documentation describes a version of the Crypto Library Normal Secure (CLNS). To identify your version of the CLNS, see #nxpCl_GetVersion.
- The CLNS is separated into software components, each of which encapsulates a disjoint subset of its functionality with a common purpose. For example, that purpose can be the abstraction of a hardware IP (Intellectual Property) or the implementation of a specific cryptographic algorithm.
  - Each component has a name that begins with the prefix `nxpCl`.
  - The names of all header files, functions and data types belonging to a component named `<component-name>` begin with the prefix `<component-name>_`.
  - The names of all preprocessor macros belonging to a component named `nxpCl<Name>` begin with the prefix `NXPCL<NAME>_`.
- Additionally, there is some component-independent functionality, such as CLNS version information.
  - The names of all header files, functions and data types that are part of component-independent functionality begin with the prefix `nxpCl_`.
  - The names of all preprocessor macros that are part of component-independent functionality begin with the prefix `NXPCL_`.
- The CLNS API consists only of the declarations contained in the API header files. Other functions, macros or types found in other source files should not be used.

- In order to minimize CPU wait cycles during coprocessor activities, some CLNS functions (non-blocking functions) are implemented in a non-blocking way, which means that the underlying operation has not completed at function return.

  It is the caller's responsibility to ensure that the operation has completed before further processing on the operation output data is performed.

  The names of all non-blocking functions end with the suffix `_Async`.

## Release Content

The release consists of three files, the NXP Software Content Register `softwareContentRegister.txt`, the NXP Software License Agreement `LICENSE.htm` and an archive with the file name extension `.zip`. The archive contains the following data:

- The `doc` folder contains Doxygen HTML documentation of the CLNS interfaces and example code. Open `doc/html/index.html` in a browser to view its main page.
- The `examples` folder contains integration example code for each included component.
- The `includes` folder directly contains the header source files that make up the API of the CLNS.
- The `includes/platform` folder contains platform-specific header files that are required for integration of the CLNS.
- The `static_library` folder contains a static library (archive of object code files) that contains the CLNS binaries.
- The `LICENSE.htm` file contains the NXP Software License Agreement.
- The `softwareContentRegister.txt` file contains the NXP Software Content Register. Note that this file is identical to the `softwareContentRegister.txt` delivered alongside the archive.

## Components

### `nxpClCss`

#### Hardware IP

- The Crypto Secure Sequencer (CSS) is a cryptographic coprocessor that can be configured to support a range of symmetric and asymmetric cryptographic operations.

- This release of the CLNS is designed for compatibility with a specific version of the CSS hardware IP.

  To identify that compatible version, see #NXPCLCSS_HW_VERSION.

  To identify your actual version of the CSS hardware IP at run-time, see #nxpClCss_GetHwVersion. For details about the CSS, read the document "Crypto Secure Sequencer – Reference Manual".

  #### CSS Base Address

The base address of the CSS needs to be provided at runtime time using the symbol `ip_css_base`.

Example:

void * ip_css_base = (void *) 0x40022000UL;

#### Enabling and Disabling the CSS

To optimize power utilization, the CSS hardware IP provides a clock gating mechanism to enable and disable itself. Prior to any CSS-based operations invoked via the CLNS, the CSS must be enabled. The CLNS API provides the following support functions to enable/disable the CSS hardware:

- #nxpClCss_Enable_Async
- #nxpClCss_Disable

#### Buffer Allocation

All input and output buffers of `nxpClCss` functions must be placed in memory regions that are accessible to the CSS hardware IP.

#### Usage

##### Non-blocking Functions

It is the caller's responsibility to ensure that the operation of a non-blocking function has completed before further processing on the operation output data is performed. For `nxpClCss` functions, this can be achieved by either polling the CSS hardware status flag or by acting on hardware interrupts. The CLNS implements the support functions #nxpClCss_WaitForOperation and #nxpClCss_LimitedWaitForOperation for the former method. #nxpClCss_WaitForOperation potentially waits an infinite amount of time, while #nxpClCss_LimitedWaitForOperation uses a counter to limit the amount of time spent waiting.

##### Sha Direct Mode

The CSS hardware IP contains a stand-alone Sha module which can be used in parallel with other CSS operations. CSS operations make use of a CSS-internal DMA (Direct Memory Access) module for data handling. The stand-alone Sha module is an exception of this behavior: It is the caller's responsibility to perform the data handling, which can be achieved using the CPU or the system DMA.

##### Alignment

As for all other components, all input and output buffers of `nxpClCss` functions that store external keys must be CPU word-aligned. From a functional perspective, all other input and output buffers of `nxpClCss` functions have no alignment requirement, unless explicitly stated otherwise. Using CPU word-aligned buffers may improve operation performance.