-.. BSD LICENSE
- Copyright(c) 2016-2017 Intel Corporation. All rights reserved.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Intel Corporation nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2016-2017 Intel Corporation.
.. _l2_fwd_crypto_app:
The destination port is the adjacent port from the enabled portmask, that is,
if the first four ports are enabled (portmask 0xf),
ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other.
-Also, the MAC addresses are affected as follows:
+Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows:
* The source MAC address is replaced by the TX_PORT MAC address
Compiling the Application
-------------------------
-#. Go to the example directory:
+To compile the sample application see :doc:`compiling`.
- .. code-block:: console
-
- export RTE_SDK=/path/to/rte_sdk
- cd ${RTE_SDK}/examples/l2fwd-crypto
-
-#. Set the target (a default target is used if not specified). For example:
-
- .. code-block:: console
-
- export RTE_TARGET=x86_64-native-linuxapp-gcc
-
- *See the DPDK Getting Started Guide* for possible RTE_TARGET values.
-
-#. Build the application:
-
- .. code-block:: console
-
- make
+The application is located in the ``l2fwd-crypt`` sub-directory.
Running the Application
-----------------------
.. code-block:: console
- ./build/l2fwd-crypto [EAL options] -- [-p PORTMASK] [-q NQ] [-s] [-T PERIOD] /
- [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY] /
- [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_key KEY] /
- [--cipher_key_random_size SIZE] [--iv IV] [--iv_random_size SIZE] /
+ ./<build_dir>/examples/dpdk-l2fwd-crypto [EAL options] -- [-p PORTMASK] [-q NQ] [-s] [-T PERIOD] /
+ [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY/AEAD] /
+ [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_dataunit_len SIZE] /
+ [--cipher_key KEY] [--cipher_key_random_size SIZE] [--cipher_iv IV] /
+ [--cipher_iv_random_size SIZE] /
[--auth_algo ALGO] [--auth_op GENERATE/VERIFY] [--auth_key KEY] /
- [--auth_key_random_size SIZE] [--aad AAD] [--aad_random_size SIZE] /
- [--digest size SIZE] [--sessionless]
+ [--auth_key_random_size SIZE] [--auth_iv IV] [--auth_iv_random_size SIZE] /
+ [--aead_algo ALGO] [--aead_op ENCRYPT/DECRYPT] [--aead_key KEY] /
+ [--aead_key_random_size SIZE] [--aead_iv] [--aead_iv_random_size SIZE] /
+ [--aad AAD] [--aad_random_size SIZE] /
+ [--digest size SIZE] [--sessionless] [--cryptodev_mask MASK] /
+ [--mac-updating] [--no-mac-updating]
where,
* chain: select the operation chaining to perform: Cipher->Hash (CIPHER_HASH),
- Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash(HASH_ONLY)
+ Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash (HASH_ONLY)
+
+ or AEAD (AEAD)
(default is Cipher->Hash)
(default is ENCRYPT)
+* cipher_dataunit_len: set the length of the cipher data-unit.
+
* cipher_key: set the ciphering key to be used. Bytes has to be separated with ":"
* cipher_key_random_size: set the size of the ciphering key,
Note that if --cipher_key is used, this will be ignored.
-* iv: set the IV to be used. Bytes has to be separated with ":"
+* cipher_iv: set the cipher IV to be used. Bytes has to be separated with ":"
-* iv_random_size: set the size of the IV, which will be generated randomly.
+* cipher_iv_random_size: set the size of the cipher IV, which will be generated randomly.
- Note that if --iv is used, this will be ignored.
+ Note that if --cipher_iv is used, this will be ignored.
* auth_algo: select the authentication algorithm (default is sha1-hmac)
-* cipher_op: select the authentication operation to perform: GENERATE or VERIFY
+* auth_op: select the authentication operation to perform: GENERATE or VERIFY
(default is GENERATE)
Note that if --auth_key is used, this will be ignored.
+* auth_iv: set the auth IV to be used. Bytes has to be separated with ":"
+
+* auth_iv_random_size: set the size of the auth IV, which will be generated randomly.
+
+ Note that if --auth_iv is used, this will be ignored.
+
+* aead_algo: select the AEAD algorithm (default is aes-gcm)
+
+* aead_op: select the AEAD operation to perform: ENCRYPT or DECRYPT
+
+ (default is ENCRYPT)
+
+* aead_key: set the AEAD key to be used. Bytes has to be separated with ":"
+
+* aead_key_random_size: set the size of the AEAD key,
+
+ which will be generated randomly.
+
+ Note that if --aead_key is used, this will be ignored.
+
+* aead_iv: set the AEAD IV to be used. Bytes has to be separated with ":"
+
+* aead_iv_random_size: set the size of the AEAD IV, which will be generated randomly.
+
+ Note that if --aead_iv is used, this will be ignored.
+
* aad: set the AAD to be used. Bytes has to be separated with ":"
* aad_random_size: set the size of the AAD, which will be generated randomly.
* sessionless: no crypto session will be created.
+* cryptodev_mask: A hexadecimal bitmask of the cryptodevs to be used by the
+ application.
+
+ (default is all cryptodevs).
+
+* [no-]mac-updating: Enable or disable MAC addresses updating (enabled by default).
+
The application requires that crypto devices capable of performing
the specified crypto operation are available on application initialization.
This means that HW crypto device/s must be bound to a DPDK driver or
a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
-To run the application in linuxapp environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
+To run the application in linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
.. code-block:: console
- $ ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "cryptodev_aesni_mb_pmd" \
- --vdev "cryptodev_aesni_mb_pmd" -- -p 0x3 --chain CIPHER_HASH \
+ $ ./<build_dir>/examples/dpdk-l2fwd-crypto -l 0-1 -n 4 --vdev "crypto_aesni_mb0" \
+ --vdev "crypto_aesni_mb1" -- -p 0x3 --chain CIPHER_HASH \
--cipher_op ENCRYPT --cipher_algo aes-cbc \
--cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \
--auth_op GENERATE --auth_algo aes-xcbc-mac \
Refer to the *DPDK Getting Started Guide* for general information on running applications
and the Environment Abstraction Layer (EAL) options.
+.. Note::
+
+ * The ``l2fwd-crypto`` sample application requires IPv4 packets for crypto operation.
+
+ * If multiple Ethernet ports is passed, then equal number of crypto devices are to be passed.
+
+ * All crypto devices shall use the same session.
+
Explanation
-----------
All the packets received in all the ports get transformed by the crypto device/s
(ciphering and/or authentication).
The crypto operation to be performed on the packet is parsed from the command line
-(go to "Running the Application section for all the options).
+(go to "Running the Application" section for all the options).
If no parameter is passed, the default crypto operation is:
The following code checks if the device supports the specified cipher algorithm
(similar for the authentication algorithm):
-.. code-block:: c
-
- /* Check if device supports cipher algo */
- i = 0;
- opt_cipher_algo = options->cipher_xform.cipher.algo;
- cap = &dev_info.capabilities[i];
- while (cap->op != RTE_CRYPTO_OP_TYPE_UNDEFINED) {
- cap_cipher_algo = cap->sym.cipher.algo;
- if (cap->sym.xform_type ==
- RTE_CRYPTO_SYM_XFORM_CIPHER) {
- if (cap_cipher_algo == opt_cipher_algo) {
- if (check_type(options, &dev_info) == 0)
- break;
- }
- }
- cap = &dev_info.capabilities[++i];
- }
+.. literalinclude:: ../../../examples/l2fwd-crypto/main.c
+ :language: c
+ :start-after: Check if device supports cipher algo. 8<
+ :end-before: >8 End of check if device supports cipher algo.
+ :dedent: 2
If a capable crypto device is found, key sizes are checked to see if they are supported
(cipher key and IV for the ciphering):
-.. code-block:: c
-
- /*
- * Check if length of provided cipher key is supported
- * by the algorithm chosen.
- */
- if (options->ckey_param) {
- if (check_supported_size(
- options->cipher_xform.cipher.key.length,
- cap->sym.cipher.key_size.min,
- cap->sym.cipher.key_size.max,
- cap->sym.cipher.key_size.increment)
- != 0) {
- printf("Unsupported cipher key length\n");
- return -1;
- }
- /*
- * Check if length of the cipher key to be randomly generated
- * is supported by the algorithm chosen.
- */
- } else if (options->ckey_random_size != -1) {
- if (check_supported_size(options->ckey_random_size,
- cap->sym.cipher.key_size.min,
- cap->sym.cipher.key_size.max,
- cap->sym.cipher.key_size.increment)
- != 0) {
- printf("Unsupported cipher key length\n");
- return -1;
- }
- options->cipher_xform.cipher.key.length =
- options->ckey_random_size;
- /* No size provided, use minimum size. */
- } else
- options->cipher_xform.cipher.key.length =
- cap->sym.cipher.key_size.min;
+.. literalinclude:: ../../../examples/l2fwd-crypto/main.c
+ :language: c
+ :start-after: Check if capable cipher is supported. 8<
+ :end-before: >8 End of checking if cipher is supported.
+ :dedent: 2
After all the checks, the device is configured and it is added to the
crypto device list.
This session is created and is later attached to the crypto operation:
-.. code-block:: c
-
- static struct rte_cryptodev_sym_session *
- initialize_crypto_session(struct l2fwd_crypto_options *options,
- uint8_t cdev_id)
- {
- struct rte_crypto_sym_xform *first_xform;
-
- if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) {
- first_xform = &options->cipher_xform;
- first_xform->next = &options->auth_xform;
- } else if (options->xform_chain == L2FWD_CRYPTO_HASH_CIPHER) {
- first_xform = &options->auth_xform;
- first_xform->next = &options->cipher_xform;
- } else if (options->xform_chain == L2FWD_CRYPTO_CIPHER_ONLY) {
- first_xform = &options->cipher_xform;
- } else {
- first_xform = &options->auth_xform;
- }
-
- /* Setup Cipher Parameters */
- return rte_cryptodev_sym_session_create(cdev_id, first_xform);
- }
-
- ...
-
- port_cparams[i].session = initialize_crypto_session(options,
- port_cparams[i].dev_id);
+.. literalinclude:: ../../../examples/l2fwd-crypto/main.c
+ :language: c
+ :start-after: Session is created and is later attached to the crypto operation. 8<
+ :end-before: >8 End of creation of session.
Crypto operation creation
~~~~~~~~~~~~~~~~~~~~~~~~~
Given N packets received from a RX PORT, N crypto operations are allocated
and filled:
-.. code-block:: c
-
- if (nb_rx) {
- /*
- * If we can't allocate a crypto_ops, then drop
- * the rest of the burst and dequeue and
- * process the packets to free offload structs
- */
- if (rte_crypto_op_bulk_alloc(
- l2fwd_crypto_op_pool,
- RTE_CRYPTO_OP_TYPE_SYMMETRIC,
- ops_burst, nb_rx) !=
- nb_rx) {
- for (j = 0; j < nb_rx; j++)
- rte_pktmbuf_free(pkts_burst[i]);
-
- nb_rx = 0;
- }
+.. literalinclude:: ../../../examples/l2fwd-crypto/main.c
+ :language: c
+ :start-after: Allocate and fillcrypto operations. 8<
+ :end-before: >8 End of crypto operation allocated and filled.
+ :dedent: 3
After filling the crypto operation (including session attachment),
the mbuf which will be transformed is attached to it::
When the buffer has enough operations (MAX_PKT_BURST), they are enqueued in the device,
which will perform the operation at that moment:
-.. code-block:: c
-
- static int
- l2fwd_crypto_enqueue(struct rte_crypto_op *op,
- struct l2fwd_crypto_params *cparams)
- {
- unsigned lcore_id, len;
- struct lcore_queue_conf *qconf;
-
- lcore_id = rte_lcore_id();
+.. literalinclude:: ../../../examples/l2fwd-crypto/main.c
+ :language: c
+ :start-after: Crypto enqueue. 8<
+ :end-before: >8 End of crypto enqueue.
- qconf = &lcore_queue_conf[lcore_id];
- len = qconf->op_buf[cparams->dev_id].len;
- qconf->op_buf[cparams->dev_id].buffer[len] = op;
- len++;
-
- /* enough ops to be sent */
- if (len == MAX_PKT_BURST) {
- l2fwd_crypto_send_burst(qconf, MAX_PKT_BURST, cparams);
- len = 0;
- }
-
- qconf->op_buf[cparams->dev_id].len = len;
- return 0;
- }
-
- ...
-
- static int
- l2fwd_crypto_send_burst(struct lcore_queue_conf *qconf, unsigned n,
- struct l2fwd_crypto_params *cparams)
- {
- struct rte_crypto_op **op_buffer;
- unsigned ret;
-
- op_buffer = (struct rte_crypto_op **)
- qconf->op_buf[cparams->dev_id].buffer;
-
- ret = rte_cryptodev_enqueue_burst(cparams->dev_id,
- cparams->qp_id, op_buffer, (uint16_t) n);
-
- crypto_statistics[cparams->dev_id].enqueued += ret;
- if (unlikely(ret < n)) {
- crypto_statistics[cparams->dev_id].errors += (n - ret);
- do {
- rte_pktmbuf_free(op_buffer[ret]->sym->m_src);
- rte_crypto_op_free(op_buffer[ret]);
- } while (++ret < n);
- }
-
- return 0;
- }
+.. literalinclude:: ../../../examples/l2fwd-crypto/main.c
+ :language: c
+ :start-after: l2fwd_crypto_send_burst 8<
+ :end-before: >8 End of l2fwd_crypto_send_burst.
After this, the operations are dequeued from the device, and the transformed mbuf
is extracted from the operation. Then, the operation is freed and the mbuf is
forwarded as it is done in the L2 forwarding application.
-.. code-block:: c
-
- /* Dequeue packets from Crypto device */
- do {
- nb_rx = rte_cryptodev_dequeue_burst(
- cparams->dev_id, cparams->qp_id,
- ops_burst, MAX_PKT_BURST);
-
- crypto_statistics[cparams->dev_id].dequeued +=
- nb_rx;
-
- /* Forward crypto'd packets */
- for (j = 0; j < nb_rx; j++) {
- m = ops_burst[j]->sym->m_src;
-
- rte_crypto_op_free(ops_burst[j]);
- l2fwd_simple_forward(m, portid);
- }
- } while (nb_rx == MAX_PKT_BURST);
+.. literalinclude:: ../../../examples/l2fwd-crypto/main.c
+ :language: c
+ :start-after: Dequeue packets from Crypto device. 8<
+ :end-before: >8 End of dequeue packets from crypto device.
+ :dedent: 3
git.droids-corp.org / dpdk.git / blobdiff