X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcryptodevs%2Faesni_mb.rst;h=49419e3191fd1ea6314c2f00d28a27c6adf03354;hb=5d87df730f4e94e44957f5def95b1dd830c09e47;hp=0f4b920620cebb87d7a8b753f5ad9e7bff50463d;hpb=2fe68f322a9829e3a578ea90b0bf98416af82ba3;p=dpdk.git diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst index 0f4b920620..49419e3191 100644 --- a/doc/guides/cryptodevs/aesni_mb.rst +++ b/doc/guides/cryptodevs/aesni_mb.rst @@ -1,5 +1,5 @@ .. 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 @@ -27,7 +27,7 @@ (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 ============================================ @@ -45,41 +45,104 @@ AESNI MB PMD has support for: 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 `_ -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 `_ +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 ``_. + +.. 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.