doc/guides/cryptodevs/chacha20_poly1305.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2021 Intel Corporation.
   3
   4 Chacha20-poly1305 Crypto Poll Mode Driver
   5 =========================================
   6
   7 The Chacha20-poly1305 PMD provides poll mode crypto driver support for
   8 utilizing `Intel IPSec Multi-buffer library <https://github.com/01org/intel-ipsec-mb>`_.
   9
  10 Features
  11 --------
  12
  13 Chacha20-poly1305 PMD has support for:
  14
  15 AEAD algorithms:
  16
  17 * RTE_CRYPTO_AEAD_CHACHA20_POLY1305
  18
  19
  20 Installation
  21 ------------
  22
  23 To build DPDK with the Chacha20-poly1305 PMD the user is required to download
  24 the multi-buffer library from `here <https://github.com/01org/intel-ipsec-mb>`_
  25 and compile it on their user system before building DPDK.
  26 The latest version of the library supported by this PMD is v1.0, which
  27 can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v1.0.zip>`_.
  28
  29 After downloading the library, the user needs to unpack and compile it
  30 on their system before building DPDK:
  31
  32 .. code-block:: console
  33
  34     make
  35     make install
  36
  37 The library requires NASM to be built. Depending on the library version, it might
  38 require a minimum NASM version (e.g. v0.54 requires at least NASM 2.14).
  39
  40 NASM is packaged for different OS. However, on some OS the version is too old,
  41 so a manual installation is required. In that case, NASM can be downloaded from
  42 `NASM website <https://www.nasm.us/pub/nasm/releasebuilds/?C=M;O=D>`_.
  43 Once it is downloaded, extract it and follow these steps:
  44
  45 .. code-block:: console
  46
  47     ./configure
  48     make
  49     make install
  50
  51 .. note::
  52
  53    Compilation of the Multi-Buffer library is broken when GCC < 5.0, if library <= v0.53.
  54    If a lower GCC version than 5.0, the workaround proposed by the following link
  55    should be used: `<https://github.com/intel/intel-ipsec-mb/issues/40>`_.
  56
  57 As a reference, the following table shows a mapping between the past DPDK versions
  58 and the external crypto libraries supported by them:
  59
  60 .. _table_chacha20_poly1305_versions:
  61
  62 .. table:: DPDK and external crypto library version compatibility
  63
  64    =============  ================================
  65    DPDK version   Crypto library version
  66    =============  ================================
  67    21.11+         Multi-buffer library 1.0*
  68    =============  ================================
  69
  70 \* Multi-buffer library 1.0 or newer only works for Meson but not Make build system.
  71
  72 Initialization
  73 --------------
  74
  75 In order to enable this virtual crypto PMD, user must:
  76
  77 * Build the multi buffer library (explained in Installation section).
  78
  79 To use the PMD in an application, user must:
  80
  81 * Call rte_vdev_init("crypto_chacha20_poly1305") within the application.
  82
  83 * Use --vdev="crypto_chacha20_poly1305" in the EAL options, which will call
  84   rte_vdev_init() internally.
  85
  86 The following parameters (all optional) can be provided in the previous two calls:
  87
  88 * socket_id: Specify the socket where the memory for the device is going to be allocated
  89   (by default, socket_id will be the socket where the core that is creating the PMD is running on).
  90
  91 * max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default).
  92
  93 * max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default).
  94
  95 Example:
  96
  97 .. code-block:: console
  98
  99     --vdev="crypto_chacha20_poly1305,socket_id=0,max_nb_sessions=128"