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.