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

nxpClEls

Hardware IP

  • The Edge Lock Secure Subsystem (ELS) 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 ELS hardware IP.

    To identify that compatible version, see #NXPCLELS_HW_VERSION.

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

    ELS Base Address

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

Example:

void * ip_css_base = (void *) 0x40022000UL;

Enabling and Disabling the ELS

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

  • #nxpClEls_Enable_Async
  • #nxpClEls_Disable

Buffer Allocation

All input and output buffers of nxpClEls functions must be placed in memory regions that are accessible to the ELS 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 nxpClEls functions, this can be achieved by either polling the ELS hardware status flag or by acting on hardware interrupts. The CLNS implements the support functions #nxpClEls_WaitForOperation and #nxpClEls_LimitedWaitForOperation for the former method. #nxpClEls_WaitForOperation potentially waits an infinite amount of time, while #nxpClEls_LimitedWaitForOperation uses a counter to limit the amount of time spent waiting.

Sha Direct Mode

The ELS hardware IP contains a stand-alone Sha module which can be used in parallel with other ELS operations. ELS operations make use of a ELS-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 nxpClEls functions that store external keys must be CPU word-aligned. From a functional perspective, all other input and output buffers of nxpClEls functions have no alignment requirement, unless explicitly stated otherwise. Using CPU word-aligned buffers may improve operation performance.