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