src/plugins/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 there are enough Cryptodev resources for all workers, the node graph is reconfigured by adding and changing the default next nodes.
  11
  12 The following nodes are added:
  13 * dpdk-crypto-input : polling input node, 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 When building DPDK with VPP, Cryptodev support is always enabled.
  27
  28 Additionally, on x86_64 platforms, DPDK is built with SW crypto support.
  29
  30
  31 ### Crypto Resources allocation
  32
  33 VPP allocates crypto resources based on a best effort approach:
  34 * first allocate Hardware crypto resources, then Software.
  35 * if there are not enough crypto resources for all workers, the graph node is not modifed and the default VPP IPsec implementation based in OpenSSL is used. The following message is displayed:
  36
  37       0: dpdk_ipsec_init: not enough Cryptodevs, default to OpenSSL IPsec
  38
  39
  40 ### Configuration example
  41
  42 To enable DPDK Cryptodev the user just need to provide cryptodevs int the
  43 startup.conf.
  44
  45 Example startup.conf:
  46
  47 ```
  48 dpdk {
  49     socket-mem 1024,1024
  50     num-mbufs 131072
  51     dev 0000:81:00.0
  52     dev 0000:81:00.1
  53     enable-cryptodev
  54     dev 0000:85:01.0
  55     dev 0000:85:01.1
  56     vdev cryptodev_aesni_mb_pmd,socket_id=1
  57     vdev cryptodev_aesni_mb_pmd,socket_id=1
  58 }
  59 ```
  60
  61 In the above configuration:
  62 * 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.
  63 * Two AESNI-MB Software Cryptodev PMDs are created in NUMA node 1.
  64
  65 For further details refer to [DPDK Crypto Device Driver documentation](http://dpdk.org/doc/guides/cryptodevs/index.html)
  66
  67 ### Operational data
  68
  69 The following CLI command displays the Cryptodev/Worker mapping:
  70
  71     show crypto device mapping [verbose]
  72
  73
  74 ### nasm
  75
  76 Building the DPDK Crypto Libraries requires the open source project nasm (The Netwide
  77 Assembler) to be installed. Recommended version of nasm is 2.12.02. Minimum supported
  78 version of nasm is 2.11.06. Use the following command to determine the current nasm version:
  79
  80     nasm -v
  81
  82 CentOS 7.3 and earlier and Fedora 21 and earlier use unsupported versions
  83 of nasm. Use the following set of commands to build a supported version:
  84
  85     wget http://www.nasm.us/pub/nasm/releasebuilds/2.12.02/nasm-2.12.02.tar.bz2
  86     tar -xjvf nasm-2.12.02.tar.bz2
  87     cd nasm-2.12.02/
  88     ./configure
  89     make
  90     sudo make install