.. BSD LICENSE
- Copyright(c) 2015 Intel Corporation. All rights reserved.
+ Copyright(c) 2015-2017 Intel Corporation. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-AESN-NI Multi Buffer Crytpo Poll Mode Driver
+AESN-NI Multi Buffer Crypto Poll Mode Driver
============================================
The AESNI MB PMD (**librte_pmd_aesni_mb**) provides poll mode crypto driver
-support for utilising Intel multi buffer library, see the white paper
+support for utilizing Intel multi buffer library, see the white paper
`Fast Multi-buffer IPsec Implementations on Intel® Architecture Processors
<https://www-ssl.intel.com/content/www/us/en/intelligent-systems/intel-technology/fast-multi-buffer-ipsec-implementations-ia-processors-paper.html?wapkw=multi+buffer>`_.
Cipher algorithms:
-* RTE_CRYPTO_SYM_CIPHER_AES128_CBC
-* RTE_CRYPTO_SYM_CIPHER_AES256_CBC
-* RTE_CRYPTO_SYM_CIPHER_AES512_CBC
+* RTE_CRYPTO_CIPHER_AES128_CBC
+* RTE_CRYPTO_CIPHER_AES192_CBC
+* RTE_CRYPTO_CIPHER_AES256_CBC
+* RTE_CRYPTO_CIPHER_AES128_CTR
+* RTE_CRYPTO_CIPHER_AES192_CTR
+* RTE_CRYPTO_CIPHER_AES256_CTR
+* RTE_CRYPTO_CIPHER_AES_DOCSISBPI
Hash algorithms:
-* RTE_CRYPTO_SYM_HASH_SHA1_HMAC
-* RTE_CRYPTO_SYM_HASH_SHA256_HMAC
-* RTE_CRYPTO_SYM_HASH_SHA512_HMAC
+* RTE_CRYPTO_HASH_MD5_HMAC
+* RTE_CRYPTO_HASH_SHA1_HMAC
+* RTE_CRYPTO_HASH_SHA224_HMAC
+* RTE_CRYPTO_HASH_SHA256_HMAC
+* RTE_CRYPTO_HASH_SHA384_HMAC
+* RTE_CRYPTO_HASH_SHA512_HMAC
+* RTE_CRYPTO_HASH_AES_XCBC_HMAC
Limitations
-----------
* Chained mbufs are not supported.
-* Hash only is not supported.
-* Cipher only is not supported.
* Only in-place is currently supported (destination address is the same as source address).
-* Only supports session-oriented API implementation (session-less APIs are not supported).
-* Not performance tuned.
+
Installation
------------
-To build DPDK with the AESNI_MB_PMD the user is required to download the mult-
-buffer library from `here <https://downloadcenter.intel.com/download/22972>`_
-and compile it on their user system before building DPDK. When building the
-multi-buffer library it is necessary to have YASM package installed and also
-requires the overriding of YASM path when building, as a path is hard coded in
-the Makefile of the release package.
+To build DPDK with the AESNI_MB_PMD the user is required to download the multi-buffer
+library from `here <https://github.com/01org/intel-ipsec-mb>`_
+and compile it on their user system before building DPDK.
+The latest version of the library supported by this PMD is v0.47, which
+can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v0.47.zip>`_.
+
+.. code-block:: console
+
+ make
+
+As a reference, the following table shows a mapping between the past DPDK versions
+and the Multi-Buffer library version supported by them:
+
+.. _table_aesni_mb_versions:
+
+.. table:: DPDK and Multi-Buffer library version compatibility
+
+ ============== ============================
+ DPDK version Multi-buffer library version
+ ============== ============================
+ 2.2 - 16.11 0.43 - 0.44
+ 17.02 0.44
+ 17.05 - 17.08 0.45 - 0.47
+ 17.11+ 0.47
+ ============== ============================
+
+
+Initialization
+--------------
+
+In order to enable this virtual crypto PMD, user must:
+
+* Export the environmental variable AESNI_MULTI_BUFFER_LIB_PATH with the path where
+ the library was extracted.
+
+* Build the multi buffer library (explained in Installation section).
+
+* Set CONFIG_RTE_LIBRTE_PMD_AESNI_MB=y in config/common_base.
+
+To use the PMD in an application, user must:
+
+* Call rte_vdev_init("crypto_aesni_mb") within the application.
+
+* Use --vdev="crypto_aesni_mb" in the EAL options, which will call rte_vdev_init() internally.
+
+The following parameters (all optional) can be provided in the previous two calls:
+
+* socket_id: Specify the socket where the memory for the device is going to be allocated
+ (by default, socket_id will be the socket where the core that is creating the PMD is running on).
+
+* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default).
+
+* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default).
+
+Example:
.. code-block:: console
- make YASM=/usr/bin/yasm
+ ./l2fwd-crypto -l 1 -n 4 --vdev="crypto_aesni_mb,socket_id=0,max_nb_sessions=128" \
+ -- -p 1 --cdev SW --chain CIPHER_HASH --cipher_algo "aes-cbc" --auth_algo "sha1-hmac"
+
+Extra notes
+-----------
+
+For AES Counter mode (AES-CTR), the library supports two different sizes for Initialization
+Vector (IV):
+
+* 12 bytes: used mainly for IPSec, as it requires 12 bytes from the user, which internally
+ are appended the counter block (4 bytes), which is set to 1 for the first block
+ (no padding required from the user)
-The environmental variable
-AESNI_MULTI_BUFFER_LIB_PATH must be exported with the path where you extracted
-and built the multi buffer library and finally set
-CONFIG_RTE_LIBRTE_PMD_AESNI_MB=y in config/common_linuxapp.
+* 16 bytes: when passing 16 bytes, the library will take them and use the last 4 bytes
+ as the initial counter block for the first block.
git.droids-corp.org / dpdk.git / blobdiff