[ceph.git] / ceph / src / seastar / dpdk / doc / guides / cryptodevs / dpaa2_sec.rst

..  SPDX-License-Identifier: BSD-3-Clause
    Copyright 2016 NXP


NXP DPAA2 CAAM (DPAA2_SEC)
==========================

The DPAA2_SEC PMD provides poll mode crypto driver support for NXP DPAA2 CAAM
hardware accelerator.

Architecture
------------

SEC is the SOC's security engine, which serves as NXP's latest cryptographic
acceleration and offloading hardware. It combines functions previously
implemented in separate modules to create a modular and scalable acceleration
and assurance engine. It also implements block encryption algorithms, stream
cipher algorithms, hashing algorithms, public key algorithms, run-time
integrity checking, and a hardware random number generator. SEC performs
higher-level cryptographic operations than previous NXP cryptographic
accelerators. This provides significant improvement to system level performance.

DPAA2_SEC is one of the hardware resource in DPAA2 Architecture. More information
on DPAA2 Architecture is described in :ref:`dpaa2_overview`.

DPAA2_SEC PMD is one of DPAA2 drivers which interacts with Management Complex (MC)
portal to access the hardware object - DPSECI. The MC provides access to create,
discover, connect, configure and destroy dpseci objects in DPAA2_SEC PMD.

DPAA2_SEC PMD also uses some of the other hardware resources like buffer pools,
queues, queue portals to store and to enqueue/dequeue data to the hardware SEC.

DPSECI objects are detected by PMD using a resource container called DPRC (like
in :ref:`dpaa2_overview`).

For example:

.. code-block:: console

    DPRC.1 (bus)
      |
      +--+--------+-------+-------+-------+---------+
         |        |       |       |       |         |
       DPMCP.1  DPIO.1  DPBP.1  DPNI.1  DPMAC.1  DPSECI.1
       DPMCP.2  DPIO.2          DPNI.2  DPMAC.2  DPSECI.2
       DPMCP.3

Implementation
--------------

SEC provides platform assurance by working with SecMon, which is a companion
logic block that tracks the security state of the SOC. SEC is programmed by
means of descriptors (not to be confused with frame descriptors (FDs)) that
indicate the operations to be performed and link to the message and
associated data. SEC incorporates two DMA engines to fetch the descriptors,
read the message data, and write the results of the operations. The DMA
engine provides a scatter/gather capability so that SEC can read and write
data scattered in memory. SEC may be configured by means of software for
dynamic changes in byte ordering. The default configuration for this version
of SEC is little-endian mode.

A block diagram similar to dpaa2 NIC is shown below to show where DPAA2_SEC
fits in the DPAA2 Bus model

.. code-block:: console


                                       +----------------+
                                       | DPDK DPAA2_SEC |
                                       |     PMD        |
                                       +----------------+       +------------+
                                       |  MC SEC object |.......|  Mempool   |
                    . . . . . . . . .  |   (DPSECI)     |       |  (DPBP)    |
                   .                   +---+---+--------+       +-----+------+
                  .                        ^   |                      .
                 .                         |   |<enqueue,             .
                .                          |   | dequeue>             .
               .                           |   |                      .
              .                        +---+---V----+                 .
             .      . . . . . . . . . .| DPIO driver|                 .
            .      .                   |  (DPIO)    |                 .
           .      .                    +-----+------+                 .
          .      .                     |  QBMAN     |                 .
         .      .                      |  Driver    |                 .
    +----+------+-------+              +-----+----- |                 .
    |   dpaa2 bus       |                    |                        .
    |   VFIO fslmc-bus  |....................|.........................
    |                   |                    |
    |     /bus/fslmc    |                    |
    +-------------------+                    |
                                             |
    ========================== HARDWARE =====|=======================
                                           DPIO
                                             |
                                           DPSECI---DPBP
    =========================================|========================


Features
--------

The DPAA2_SEC PMD has support for:

Cipher algorithms:

* ``RTE_CRYPTO_CIPHER_3DES_CBC``
* ``RTE_CRYPTO_CIPHER_AES128_CBC``
* ``RTE_CRYPTO_CIPHER_AES192_CBC``
* ``RTE_CRYPTO_CIPHER_AES256_CBC``
* ``RTE_CRYPTO_CIPHER_AES128_CTR``
* ``RTE_CRYPTO_CIPHER_AES192_CTR``
* ``RTE_CRYPTO_CIPHER_AES256_CTR``

Hash algorithms:

* ``RTE_CRYPTO_AUTH_SHA1_HMAC``
* ``RTE_CRYPTO_AUTH_SHA224_HMAC``
* ``RTE_CRYPTO_AUTH_SHA256_HMAC``
* ``RTE_CRYPTO_AUTH_SHA384_HMAC``
* ``RTE_CRYPTO_AUTH_SHA512_HMAC``
* ``RTE_CRYPTO_AUTH_MD5_HMAC``

AEAD algorithms:

* ``RTE_CRYPTO_AEAD_AES_GCM``

Supported DPAA2 SoCs
--------------------

* LS2160A
* LS2084A/LS2044A
* LS2088A/LS2048A
* LS1088A/LS1048A

Whitelisting & Blacklisting
---------------------------

For blacklisting a DPAA2 SEC device, following commands can be used.

 .. code-block:: console

    <dpdk app> <EAL args> -b "fslmc:dpseci.x" -- ...

Where x is the device object id as configured in resource container.

Limitations
-----------

* Hash followed by Cipher mode is not supported
* Only supports the session-oriented API implementation (session-less APIs are not supported).

Prerequisites
-------------

DPAA2_SEC driver has similar pre-requisites as described in :ref:`dpaa2_overview`.
The following dependencies are not part of DPDK and must be installed separately:

See :doc:`../platform/dpaa2` for setup information

Currently supported by DPDK:

- NXP SDK **19.03+**.
- MC Firmware version **10.14.0** and higher.
- Supported architectures:  **arm64 LE**.

- Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.

Pre-Installation Configuration
------------------------------

Config File Options
~~~~~~~~~~~~~~~~~~~

Basic DPAA2 config file options are described in :ref:`dpaa2_overview`.
In addition to those, the following options can be modified in the ``config`` file
to enable DPAA2_SEC PMD.

Please note that enabling debugging options may affect system performance.

* ``CONFIG_RTE_LIBRTE_PMD_DPAA2_SEC`` (default ``n``)
  By default it is only enabled in defconfig_arm64-dpaa2-* config.
  Toggle compilation of the ``librte_pmd_dpaa2_sec`` driver.

Installations
-------------
To compile the DPAA2_SEC PMD for Linux arm64 gcc target, run the
following ``make`` command:

.. code-block:: console

   cd <DPDK-source-directory>
   make config T=arm64-dpaa2-linux-gcc install

Enabling logs
-------------

For enabling logs, use the following EAL parameter:

.. code-block:: console

   ./your_crypto_application <EAL args> --log-level=pmd.crypto.dpaa2:<level>

Using ``crypto.dpaa2`` as log matching criteria, all Crypto PMD logs can be
enabled which are lower than logging ``level``.
Commit	Line	Data
9f95a23c TL	1	.. SPDX-License-Identifier: BSD-3-Clause
	2	Copyright 2016 NXP
	3
11fdf7f2 TL	4
	5
	6	NXP DPAA2 CAAM (DPAA2_SEC)
	7	==========================
	8
	9	The DPAA2_SEC PMD provides poll mode crypto driver support for NXP DPAA2 CAAM
	10	hardware accelerator.
	11
	12	Architecture
	13	------------
	14
	15	SEC is the SOC's security engine, which serves as NXP's latest cryptographic
	16	acceleration and offloading hardware. It combines functions previously
	17	implemented in separate modules to create a modular and scalable acceleration
	18	and assurance engine. It also implements block encryption algorithms, stream
	19	cipher algorithms, hashing algorithms, public key algorithms, run-time
	20	integrity checking, and a hardware random number generator. SEC performs
	21	higher-level cryptographic operations than previous NXP cryptographic
	22	accelerators. This provides significant improvement to system level performance.
	23
	24	DPAA2_SEC is one of the hardware resource in DPAA2 Architecture. More information
	25	on DPAA2 Architecture is described in :ref:`dpaa2_overview`.
	26
	27	DPAA2_SEC PMD is one of DPAA2 drivers which interacts with Management Complex (MC)
	28	portal to access the hardware object - DPSECI. The MC provides access to create,
	29	discover, connect, configure and destroy dpseci objects in DPAA2_SEC PMD.
	30
	31	DPAA2_SEC PMD also uses some of the other hardware resources like buffer pools,
	32	queues, queue portals to store and to enqueue/dequeue data to the hardware SEC.
	33
	34	DPSECI objects are detected by PMD using a resource container called DPRC (like
	35	in :ref:`dpaa2_overview`).
	36
	37	For example:
	38
	39	.. code-block:: console
	40
	41	DPRC.1 (bus)
	42	\|
	43	+--+--------+-------+-------+-------+---------+
	44	\| \| \| \| \| \|
	45	DPMCP.1 DPIO.1 DPBP.1 DPNI.1 DPMAC.1 DPSECI.1
	46	DPMCP.2 DPIO.2 DPNI.2 DPMAC.2 DPSECI.2
	47	DPMCP.3
	48
	49	Implementation
	50	--------------
	51
	52	SEC provides platform assurance by working with SecMon, which is a companion
	53	logic block that tracks the security state of the SOC. SEC is programmed by
	54	means of descriptors (not to be confused with frame descriptors (FDs)) that
	55	indicate the operations to be performed and link to the message and
	56	associated data. SEC incorporates two DMA engines to fetch the descriptors,
	57	read the message data, and write the results of the operations. The DMA
	58	engine provides a scatter/gather capability so that SEC can read and write
	59	data scattered in memory. SEC may be configured by means of software for
	60	dynamic changes in byte ordering. The default configuration for this version
	61	of SEC is little-endian mode.
	62
	63	A block diagram similar to dpaa2 NIC is shown below to show where DPAA2_SEC
	64	fits in the DPAA2 Bus model
	65
	66	.. code-block:: console
	67
68
69	+----------------+
70	\| DPDK DPAA2_SEC \|
71	\| PMD \|
72	+----------------+ +------------+
73	\| MC SEC object \|.......\| Mempool \|
74	. . . . . . . . . \| (DPSECI) \| \| (DPBP) \|
75	. +---+---+--------+ +-----+------+
76	. ^ \| .
77	. \| \|<enqueue, .
78	. \| \| dequeue> .
79	. \| \| .
80	. +---+---V----+ .
81	. . . . . . . . . . .\| DPIO driver\| .
82	. . \| (DPIO) \| .
83	. . +-----+------+ .
84	. . \| QBMAN \| .
85	. . \| Driver \| .
86	+----+------+-------+ +-----+----- \| .
87	\| dpaa2 bus \| \| .
88	\| VFIO fslmc-bus \|....................\|.........................
89	\| \| \|
90	\| /bus/fslmc \| \|
91	+-------------------+ \|
92	\|
93	========================== HARDWARE =====\|=======================
94	DPIO
95	\|
96	DPSECI---DPBP
97	=========================================\|========================
98
99
100
101	Features
102	--------
103
9f95a23c	104	The DPAA2_SEC PMD has support for:
11fdf7f2 TL	105
	106	Cipher algorithms:
	107
	108	* ``RTE_CRYPTO_CIPHER_3DES_CBC``
	109	* ``RTE_CRYPTO_CIPHER_AES128_CBC``
	110	* ``RTE_CRYPTO_CIPHER_AES192_CBC``
	111	* ``RTE_CRYPTO_CIPHER_AES256_CBC``
9f95a23c TL	112	* ``RTE_CRYPTO_CIPHER_AES128_CTR``
	113	* ``RTE_CRYPTO_CIPHER_AES192_CTR``
	114	* ``RTE_CRYPTO_CIPHER_AES256_CTR``
11fdf7f2 TL	115
	116	Hash algorithms:
	117
	118	* ``RTE_CRYPTO_AUTH_SHA1_HMAC``
	119	* ``RTE_CRYPTO_AUTH_SHA224_HMAC``
	120	* ``RTE_CRYPTO_AUTH_SHA256_HMAC``
	121	* ``RTE_CRYPTO_AUTH_SHA384_HMAC``
	122	* ``RTE_CRYPTO_AUTH_SHA512_HMAC``
	123	* ``RTE_CRYPTO_AUTH_MD5_HMAC``
	124
9f95a23c TL	125	AEAD algorithms:
	126
	127	* ``RTE_CRYPTO_AEAD_AES_GCM``
	128
11fdf7f2 TL	129	Supported DPAA2 SoCs
	130	--------------------
	131
9f95a23c	132	* LS2160A
11fdf7f2 TL	133	* LS2084A/LS2044A
	134	* LS2088A/LS2048A
	135	* LS1088A/LS1048A
	136
9f95a23c TL	137	Whitelisting & Blacklisting
	138	---------------------------
	139
	140	For blacklisting a DPAA2 SEC device, following commands can be used.
	141
	142	.. code-block:: console
	143
	144	<dpdk app> <EAL args> -b "fslmc:dpseci.x" -- ...
	145
	146	Where x is the device object id as configured in resource container.
	147
11fdf7f2 TL	148	Limitations
	149	-----------
	150
11fdf7f2 TL	151	* Hash followed by Cipher mode is not supported
	152	* Only supports the session-oriented API implementation (session-less APIs are not supported).
	153
	154	Prerequisites
	155	-------------
	156
	157	DPAA2_SEC driver has similar pre-requisites as described in :ref:`dpaa2_overview`.
	158	The following dependencies are not part of DPDK and must be installed separately:
	159
9f95a23c	160	See :doc:`../platform/dpaa2` for setup information
11fdf7f2 TL	161
	162	Currently supported by DPDK:
	163
9f95a23c TL	164	- NXP SDK 19.03+.
	165	- MC Firmware version 10.14.0 and higher.
	166	- Supported architectures: arm64 LE.
11fdf7f2	167
9f95a23c	168	- Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
11fdf7f2 TL	169
	170	Pre-Installation Configuration
	171	------------------------------
	172
	173	Config File Options
	174	~~~~~~~~~~~~~~~~~~~
	175
	176	Basic DPAA2 config file options are described in :ref:`dpaa2_overview`.
	177	In addition to those, the following options can be modified in the ``config`` file
	178	to enable DPAA2_SEC PMD.
	179
	180	Please note that enabling debugging options may affect system performance.
	181
	182	* ``CONFIG_RTE_LIBRTE_PMD_DPAA2_SEC`` (default ``n``)
	183	By default it is only enabled in defconfig_arm64-dpaa2-* config.
	184	Toggle compilation of the ``librte_pmd_dpaa2_sec`` driver.
	185
11fdf7f2 TL	186	Installations
	187	-------------
	188	To compile the DPAA2_SEC PMD for Linux arm64 gcc target, run the
	189	following ``make`` command:
	190
	191	.. code-block:: console
	192
	193	cd <DPDK-source-directory>
9f95a23c TL	194	make config T=arm64-dpaa2-linux-gcc install
	195
	196	Enabling logs
	197	-------------
	198
	199	For enabling logs, use the following EAL parameter:
	200
	201	.. code-block:: console
	202
	203	./your_crypto_application <EAL args> --log-level=pmd.crypto.dpaa2:<level>
	204
	205	Using ``crypto.dpaa2`` as log matching criteria, all Crypto PMD logs can be
	206	enabled which are lower than logging ``level``.