New upstream version 17.08

[deb_dpdk.git] / doc / guides / sample_app_ug / l2_forward_crypto.rst

diff --git a/doc/guides/sample_app_ug/l2_forward_crypto.rst b/doc/guides/sample_app_ug/l2_forward_crypto.rst
index d6df36b..158f4b4 100644 (file)
--- a/doc/guides/sample_app_ug/l2_forward_crypto.rst
+++ b/doc/guides/sample_app_ug/l2_forward_crypto.rst
@@ -46,7 +46,7 @@ for each packet that is received on a RX_PORT and performs L2 forwarding.
 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
 
@@ -84,12 +84,16 @@ The application requires a number of command line options:
 .. 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] /
+    [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY/AEAD] /
     [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_key KEY] /
-    [--cipher_key_random_size SIZE] [--iv IV] [--iv_random_size SIZE] /
+    [--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] [--cryptodev_mask MASK]
+    [--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,
 
@@ -109,7 +113,9 @@ 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)
 
@@ -127,15 +133,15 @@ where,
 
     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)
 
@@ -147,6 +153,32 @@ where,
 
     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.
@@ -162,6 +194,8 @@ where,
 
     (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.
@@ -172,8 +206,8 @@ To run the application in linuxapp environment with 2 lcores, 2 ports and 2 cryp
 
 .. 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/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 \
@@ -331,8 +365,14 @@ This session is created and is later attached to the crypto operation:
                    uint8_t cdev_id)
    {
            struct rte_crypto_sym_xform *first_xform;
+           struct rte_cryptodev_sym_session *session;
+           uint8_t socket_id = rte_cryptodev_socket_id(cdev_id);
+           struct rte_mempool *sess_mp = session_pool_socket[socket_id];
+
 
-           if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) {
+           if (options->xform_chain == L2FWD_CRYPTO_AEAD) {
+                   first_xform = &options->aead_xform;
+           } else 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) {
@@ -344,8 +384,16 @@ This session is created and is later attached to the crypto operation:
                    first_xform = &options->auth_xform;
            }
 
-           /* Setup Cipher Parameters */
-           return rte_cryptodev_sym_session_create(cdev_id, first_xform);
+           session = rte_cryptodev_sym_session_create(sess_mp);
+
+           if (session == NULL)
+                   return NULL;
+
+          if (rte_cryptodev_sym_session_init(cdev_id, session,
+                                first_xform, sess_mp) < 0)
+                   return NULL;
+
+          return session;
    }
 
    ...