doc/guides/cryptodevs/ccp.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright(c) 2018 Advanced Micro Devices, Inc. All rights reserved.
   3
   4 AMD CCP Poll Mode Driver
   5 ========================
   6
   7 This code provides the initial implementation of the ccp poll mode driver.
   8 The CCP poll mode driver library (**librte_crypto_ccp**) implements support for
   9 AMD’s cryptographic co-processor (CCP). The CCP PMD is a virtual crypto
  10 poll mode driver which schedules crypto operations to one or more available
  11 CCP hardware engines on the platform. The CCP PMD provides poll mode crypto
  12 driver support for the following hardware accelerator devices::
  13
  14         AMD Cryptographic Co-processor (0x1456)
  15         AMD Cryptographic Co-processor (0x1468)
  16
  17 Features
  18 --------
  19
  20 CCP crypto PMD has support for:
  21
  22 Cipher algorithms:
  23
  24 * ``RTE_CRYPTO_CIPHER_AES_CBC``
  25 * ``RTE_CRYPTO_CIPHER_AES_ECB``
  26 * ``RTE_CRYPTO_CIPHER_AES_CTR``
  27 * ``RTE_CRYPTO_CIPHER_3DES_CBC``
  28
  29 Hash algorithms:
  30
  31 * ``RTE_CRYPTO_AUTH_SHA1``
  32 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
  33 * ``RTE_CRYPTO_AUTH_SHA224``
  34 * ``RTE_CRYPTO_AUTH_SHA224_HMAC``
  35 * ``RTE_CRYPTO_AUTH_SHA256``
  36 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
  37 * ``RTE_CRYPTO_AUTH_SHA384``
  38 * ``RTE_CRYPTO_AUTH_SHA384_HMAC``
  39 * ``RTE_CRYPTO_AUTH_SHA512``
  40 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
  41 * ``RTE_CRYPTO_AUTH_MD5_HMAC``
  42 * ``RTE_CRYPTO_AUTH_AES_CMAC``
  43 * ``RTE_CRYPTO_AUTH_SHA3_224``
  44 * ``RTE_CRYPTO_AUTH_SHA3_224_HMAC``
  45 * ``RTE_CRYPTO_AUTH_SHA3_256``
  46 * ``RTE_CRYPTO_AUTH_SHA3_256_HMAC``
  47 * ``RTE_CRYPTO_AUTH_SHA3_384``
  48 * ``RTE_CRYPTO_AUTH_SHA3_384_HMAC``
  49 * ``RTE_CRYPTO_AUTH_SHA3_512``
  50 * ``RTE_CRYPTO_AUTH_SHA3_512_HMAC``
  51
  52 AEAD algorithms:
  53
  54 * ``RTE_CRYPTO_AEAD_AES_GCM``
  55
  56 Installation
  57 ------------
  58
  59 To compile ccp PMD, openssl packages have to be installed in the build
  60 environment.
  61
  62 For Ubuntu 16.04 LTS use below to install openssl in the build system:
  63
  64 .. code-block:: console
  65
  66         sudo apt-get install openssl
  67
  68 This code was verified on Ubuntu 16.04.
  69
  70 Initialization
  71 --------------
  72
  73 Bind the CCP devices to DPDK UIO driver module before running the CCP PMD stack.
  74 e.g. for the 0x1456 device::
  75
  76         modprobe uio
  77         insmod igb_uio.ko
  78         echo "1022 1456" > /sys/bus/pci/drivers/igb_uio/new_id
  79
  80 Another way to bind the CCP devices to DPDK UIO driver is by using the ``dpdk-devbind.py`` script.
  81 The following command assumes ``BFD`` as ``0000:09:00.2``::
  82
  83         cd to the top-level DPDK directory
  84         ./usertools/dpdk-devbind.py -b igb_uio 0000:09:00.2
  85
  86 To use the PMD in an application, user must:
  87
  88 * Call rte_vdev_init("crypto_ccp") within the application.
  89
  90 * Use --vdev="crypto_ccp" in the EAL options, which will call rte_vdev_init() internally.
  91
  92 The following parameters (all optional) can be provided in the previous two calls:
  93
  94 * socket_id: Specify the socket where the memory for the device is going to be allocated.
  95   (by default, socket_id will be the socket where the core that is creating the PMD is running on).
  96
  97 * max_nb_queue_pairs: Specify the maximum number of queue pairs in the device.
  98
  99 * max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default).
 100
 101 * ccp_auth_opt: Specify authentication operations to perform on CPU using openssl APIs.
 102
 103 To validate ccp pmd, l2fwd-crypto example can be used with following command:
 104
 105 .. code-block:: console
 106
 107         sudo ./<build_dir>/examples/dpdk-l2fwd-crypto -l 1 -n 4 --vdev "crypto_ccp" -- -p 0x1
 108         --chain CIPHER_HASH --cipher_op ENCRYPT --cipher_algo aes-cbc
 109         --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f
 110         --cipher_iv 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:ff
 111         --auth_op GENERATE --auth_algo sha1-hmac
 112         --auth_key 11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
 113         :11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
 114         :11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
 115
 116 The CCP PMD also supports computing authentication over CPU with cipher offloaded to CCP.
 117 To enable this feature, pass an additional argument as ccp_auth_opt=1 to --vdev parameters as
 118 following:
 119
 120 .. code-block:: console
 121
 122         sudo ./<build_dir>/examples/dpdk-l2fwd-crypto -l 1 -n 4 --vdev "crypto_ccp,ccp_auth_opt=1" -- -p 0x1
 123         --chain CIPHER_HASH --cipher_op ENCRYPT --cipher_algo aes-cbc
 124         --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f
 125         --cipher_iv 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:ff
 126         --auth_op GENERATE --auth_algo sha1-hmac
 127         --auth_key 11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
 128         :11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
 129         :11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
 130
 131 Limitations
 132 -----------
 133
 134 * Chained mbufs are not supported.
 135 * MD5_HMAC is supported only for CPU based authentication.