src/vnet/devices/dpdk/ipsec/dpdk_crypto_ipsec_doc.md

   1 # VPP IPSec implementation using DPDK Cryptodev API    {#dpdk_crypto_ipsec_doc}
   2
   3 This document is meant to contain all related information about implementation and usability.
   4
   5
   6 ## VPP IPsec with DPDK Cryptodev
   7
   8 DPDK Cryptodev is an asynchronous crypto API that supports both Hardware and Software implementations (for more details refer to [DPDK Cryptography Device Library documentation](http://dpdk.org/doc/guides/prog_guide/cryptodev_lib.html)).
   9
  10 When DPDK support is enabled and there are enough Cryptodev resources for all workers, the node graph is reconfigured by adding and changing default next nodes.
  11
  12 The following nodes are added:
  13 * dpdk-crypto-input : polling input node, basically dequeuing from crypto devices.
  14 * dpdk-esp-encrypt : internal node.
  15 * dpdk-esp-decrypt : internal node.
  16 * dpdk-esp-encrypt-post : internal node.
  17 * dpdk-esp-decrypt-post : internal node.
  18
  19 Set new default next nodes:
  20 * for esp encryption: esp-encrypt -> dpdk-esp-encrypt
  21 * for esp decryption: esp-decrypt -> dpdk-esp-decrypt
  22
  23
  24 ### How to enable VPP IPSec with DPDK Cryptodev support
  25
  26 DPDK Cryptodev is supported in DPDK enabled VPP.
  27 By default, only HW Cryptodev is supported but needs to be explicetly enabled with the following config option:
  28
  29 ```
  30 dpdk {
  31     enable-cryptodev
  32 }
  33 ```
  34
  35 To enable SW Cryptodev support (AESNI-MB-PMD and GCM-PMD), we need the following env option:
  36
  37     vpp_uses_dpdk_cryptodev_sw=yes
  38
  39 A couple of ways to achive this:
  40 * uncomment/add it in the platforms config (ie. build-data/platforms/vpp.mk)
  41 * set the option when building vpp (ie. make vpp_uses_dpdk_cryptodev_sw=yes build-release)
  42
  43 When enabling SW Cryptodev support, it means that you need to pre-build the required crypto libraries needed by those SW Cryptodev PMDs.
  44
  45
  46 ### Crypto Resources allocation
  47
  48 VPP allocates crypto resources based on a best effort approach:
  49 * first allocate Hardware crypto resources, then Software.
  50 * if there are not enough crypto resources for all workers, the graph node is not modifed, therefore the default VPP IPsec implementation based in OpenSSL is used. The following message is displayed:
  51
  52       0: dpdk_ipsec_init: not enough cryptodevs for ipsec
  53
  54
  55 ### Configuration example
  56
  57 To enable DPDK Cryptodev the user just need to provide the startup.conf option
  58 as mentioned previously.
  59
  60 Example startup.conf:
  61
  62 ```
  63 dpdk {
  64     socket-mem 1024,1024
  65     num-mbufs 131072
  66     dev 0000:81:00.0
  67     dev 0000:81:00.1
  68     enable-cryptodev
  69     dev 0000:85:01.0
  70     dev 0000:85:01.1
  71     vdev cryptodev_aesni_mb_pmd,socket_id=1
  72     vdev cryptodev_aesni_mb_pmd,socket_id=1
  73 }
  74 ```
  75
  76 In the above configuration:
  77 * 0000:85:01.0 and 0000:85:01.1 are crypto BDFs and they require the same driver binding as DPDK Ethernet devices but they do not support any extra configuration options.
  78 * Two AESNI-MB Software Cryptodev PMDs are created in NUMA node 1.
  79
  80 For further details refer to [DPDK Crypto Device Driver documentation](http://dpdk.org/doc/guides/cryptodevs/index.html)
  81
  82 ### Operational data
  83
  84 The following CLI command displays the Cryptodev/Worker mapping:
  85
  86     show crypto device mapping [verbose]