1.. BSD LICENSE 2 Copyright(c) 2016-2017 Intel Corporation. All rights reserved. 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 * Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 * Redistributions in binary form must reproduce the above copyright 12 notice, this list of conditions and the following disclaimer in 13 the documentation and/or other materials provided with the 14 distribution. 15 * Neither the name of Intel Corporation nor the names of its 16 contributors may be used to endorse or promote products derived 17 from this software without specific prior written permission. 18 19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31.. _l2_fwd_crypto_app: 32 33L2 Forwarding with Crypto Sample Application 34============================================ 35 36The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example of packet processing using 37the Data Plane Development Kit (DPDK), in conjunction with the Cryptodev library. 38 39Overview 40-------- 41 42The L2 Forwarding with Crypto sample application performs a crypto operation (cipher/hash) 43specified by the user from command line (or using the default values), 44with a crypto device capable of doing that operation, 45for each packet that is received on a RX_PORT and performs L2 forwarding. 46The destination port is the adjacent port from the enabled portmask, that is, 47if the first four ports are enabled (portmask 0xf), 48ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other. 49Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows: 50 51* The source MAC address is replaced by the TX_PORT MAC address 52 53* The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID 54 55Compiling the Application 56------------------------- 57 58#. Go to the example directory: 59 60 .. code-block:: console 61 62 export RTE_SDK=/path/to/rte_sdk 63 cd ${RTE_SDK}/examples/l2fwd-crypto 64 65#. Set the target (a default target is used if not specified). For example: 66 67 .. code-block:: console 68 69 export RTE_TARGET=x86_64-native-linuxapp-gcc 70 71 *See the DPDK Getting Started Guide* for possible RTE_TARGET values. 72 73#. Build the application: 74 75 .. code-block:: console 76 77 make 78 79Running the Application 80----------------------- 81 82The application requires a number of command line options: 83 84.. code-block:: console 85 86 ./build/l2fwd-crypto [EAL options] -- [-p PORTMASK] [-q NQ] [-s] [-T PERIOD] / 87 [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY] / 88 [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_key KEY] / 89 [--cipher_key_random_size SIZE] [--cipher_iv IV] [--cipher_iv_random_size SIZE] / 90 [--auth_algo ALGO] [--auth_op GENERATE/VERIFY] [--auth_key KEY] / 91 [--auth_key_random_size SIZE] [--auth_iv IV] [--auth_iv_random_size SIZE] / 92 [--aad AAD] [--aad_random_size SIZE] / 93 [--digest size SIZE] [--sessionless] [--cryptodev_mask MASK] / 94 [--mac-updating] [--no-mac-updating] 95 96where, 97 98* p PORTMASK: A hexadecimal bitmask of the ports to configure (default is all the ports) 99 100* q NQ: A number of queues (=ports) per lcore (default is 1) 101 102* s: manage all ports from single core 103 104* T PERIOD: statistics will be refreshed each PERIOD seconds 105 106 (0 to disable, 10 default, 86400 maximum) 107 108* cdev_type: select preferred crypto device type: HW, SW or anything (ANY) 109 110 (default is ANY) 111 112* chain: select the operation chaining to perform: Cipher->Hash (CIPHER_HASH), 113 114 Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash (HASH_ONLY) 115 116 or AEAD (AEAD) 117 118 (default is Cipher->Hash) 119 120* cipher_algo: select the ciphering algorithm (default is aes-cbc) 121 122* cipher_op: select the ciphering operation to perform: ENCRYPT or DECRYPT 123 124 (default is ENCRYPT) 125 126* cipher_key: set the ciphering key to be used. Bytes has to be separated with ":" 127 128* cipher_key_random_size: set the size of the ciphering key, 129 130 which will be generated randomly. 131 132 Note that if --cipher_key is used, this will be ignored. 133 134* cipher_iv: set the cipher IV to be used. Bytes has to be separated with ":" 135 136* cipher_iv_random_size: set the size of the cipher IV, which will be generated randomly. 137 138 Note that if --cipher_iv is used, this will be ignored. 139 140* auth_algo: select the authentication algorithm (default is sha1-hmac) 141 142* auth_op: select the authentication operation to perform: GENERATE or VERIFY 143 144 (default is GENERATE) 145 146* auth_key: set the authentication key to be used. Bytes has to be separated with ":" 147 148* auth_key_random_size: set the size of the authentication key, 149 150 which will be generated randomly. 151 152 Note that if --auth_key is used, this will be ignored. 153 154* auth_iv: set the auth IV to be used. Bytes has to be separated with ":" 155 156* auth_iv_random_size: set the size of the auth IV, which will be generated randomly. 157 158 Note that if --auth_iv is used, this will be ignored. 159 160* aead_algo: select the AEAD algorithm (default is aes-gcm) 161 162* aead_op: select the AEAD operation to perform: ENCRYPT or DECRYPT 163 164 (default is ENCRYPT) 165 166* aead_key: set the AEAD key to be used. Bytes has to be separated with ":" 167 168* aead_key_random_size: set the size of the AEAD key, 169 170 which will be generated randomly. 171 172 Note that if --aead_key is used, this will be ignored. 173 174* aead_iv: set the AEAD IV to be used. Bytes has to be separated with ":" 175 176* aead_iv_random_size: set the size of the AEAD IV, which will be generated randomly. 177 178 Note that if --aead_iv is used, this will be ignored. 179 180* aad: set the AAD to be used. Bytes has to be separated with ":" 181 182* aad_random_size: set the size of the AAD, which will be generated randomly. 183 184 Note that if --aad is used, this will be ignored. 185 186* digest_size: set the size of the digest to be generated/verified. 187 188* sessionless: no crypto session will be created. 189 190* cryptodev_mask: A hexadecimal bitmask of the cryptodevs to be used by the 191 application. 192 193 (default is all cryptodevs). 194 195* [no-]mac-updating: Enable or disable MAC addresses updating (enabled by default). 196 197 198The application requires that crypto devices capable of performing 199the specified crypto operation are available on application initialization. 200This means that HW crypto device/s must be bound to a DPDK driver or 201a SW crypto device/s (virtual crypto PMD) must be created (using --vdev). 202 203To run the application in linuxapp environment with 2 lcores, 2 ports and 2 crypto devices, issue the command: 204 205.. code-block:: console 206 207 $ ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "crypto_aesni_mb0" \ 208 --vdev "crypto_aesni_mb1" -- -p 0x3 --chain CIPHER_HASH \ 209 --cipher_op ENCRYPT --cipher_algo aes-cbc \ 210 --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \ 211 --auth_op GENERATE --auth_algo aes-xcbc-mac \ 212 --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f 213 214Refer to the *DPDK Getting Started Guide* for general information on running applications 215and the Environment Abstraction Layer (EAL) options. 216 217Explanation 218----------- 219 220The L2 forward with Crypto application demonstrates the performance of a crypto operation 221on a packet received on a RX PORT before forwarding it to a TX PORT. 222 223The following figure illustrates a sample flow of a packet in the application, 224from reception until transmission. 225 226.. _figure_l2_fwd_encrypt_flow: 227 228.. figure:: img/l2_fwd_encrypt_flow.* 229 230 Encryption flow Through the L2 Forwarding with Crypto Application 231 232 233The following sections provide some explanation of the application. 234 235Crypto operation specification 236~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 237 238All the packets received in all the ports get transformed by the crypto device/s 239(ciphering and/or authentication). 240The crypto operation to be performed on the packet is parsed from the command line 241(go to "Running the Application section for all the options). 242 243If no parameter is passed, the default crypto operation is: 244 245* Encryption with AES-CBC with 128 bit key. 246 247* Authentication with SHA1-HMAC (generation). 248 249* Keys, IV and AAD are generated randomly. 250 251There are two methods to pass keys, IV and ADD from the command line: 252 253* Passing the full key, separated bytes by ":":: 254 255 --cipher_key 00:11:22:33:44 256 257* Passing the size, so key is generated randomly:: 258 259 --cipher_key_random_size 16 260 261**Note**: 262 If full key is passed (first method) and the size is passed as well (second method), 263 the latter will be ignored. 264 265Size of these keys are checked (regardless the method), before starting the app, 266to make sure that it is supported by the crypto devices. 267 268Crypto device initialization 269~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 270 271Once the encryption operation is defined, crypto devices are initialized. 272The crypto devices must be either bound to a DPDK driver (if they are physical devices) 273or created using the EAL option --vdev (if they are virtual devices), 274when running the application. 275 276The initialize_cryptodevs() function performs the device initialization. 277It iterates through the list of the available crypto devices and 278check which ones are capable of performing the operation. 279Each device has a set of capabilities associated with it, 280which are stored in the device info structure, so the function checks if the operation 281is within the structure of each device. 282 283The following code checks if the device supports the specified cipher algorithm 284(similar for the authentication algorithm): 285 286.. code-block:: c 287 288 /* Check if device supports cipher algo */ 289 i = 0; 290 opt_cipher_algo = options->cipher_xform.cipher.algo; 291 cap = &dev_info.capabilities[i]; 292 while (cap->op != RTE_CRYPTO_OP_TYPE_UNDEFINED) { 293 cap_cipher_algo = cap->sym.cipher.algo; 294 if (cap->sym.xform_type == 295 RTE_CRYPTO_SYM_XFORM_CIPHER) { 296 if (cap_cipher_algo == opt_cipher_algo) { 297 if (check_type(options, &dev_info) == 0) 298 break; 299 } 300 } 301 cap = &dev_info.capabilities[++i]; 302 } 303 304If a capable crypto device is found, key sizes are checked to see if they are supported 305(cipher key and IV for the ciphering): 306 307.. code-block:: c 308 309 /* 310 * Check if length of provided cipher key is supported 311 * by the algorithm chosen. 312 */ 313 if (options->ckey_param) { 314 if (check_supported_size( 315 options->cipher_xform.cipher.key.length, 316 cap->sym.cipher.key_size.min, 317 cap->sym.cipher.key_size.max, 318 cap->sym.cipher.key_size.increment) 319 != 0) { 320 printf("Unsupported cipher key length\n"); 321 return -1; 322 } 323 /* 324 * Check if length of the cipher key to be randomly generated 325 * is supported by the algorithm chosen. 326 */ 327 } else if (options->ckey_random_size != -1) { 328 if (check_supported_size(options->ckey_random_size, 329 cap->sym.cipher.key_size.min, 330 cap->sym.cipher.key_size.max, 331 cap->sym.cipher.key_size.increment) 332 != 0) { 333 printf("Unsupported cipher key length\n"); 334 return -1; 335 } 336 options->cipher_xform.cipher.key.length = 337 options->ckey_random_size; 338 /* No size provided, use minimum size. */ 339 } else 340 options->cipher_xform.cipher.key.length = 341 cap->sym.cipher.key_size.min; 342 343After all the checks, the device is configured and it is added to the 344crypto device list. 345 346**Note**: 347 The number of crypto devices that supports the specified crypto operation 348 must be at least the number of ports to be used. 349 350Session creation 351~~~~~~~~~~~~~~~~ 352 353The crypto operation has a crypto session associated to it, which contains 354information such as the transform chain to perform (e.g. ciphering then hashing), 355pointers to the keys, lengths... etc. 356 357This session is created and is later attached to the crypto operation: 358 359.. code-block:: c 360 361 static struct rte_cryptodev_sym_session * 362 initialize_crypto_session(struct l2fwd_crypto_options *options, 363 uint8_t cdev_id) 364 { 365 struct rte_crypto_sym_xform *first_xform; 366 367 if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) { 368 first_xform = &options->cipher_xform; 369 first_xform->next = &options->auth_xform; 370 } else if (options->xform_chain == L2FWD_CRYPTO_HASH_CIPHER) { 371 first_xform = &options->auth_xform; 372 first_xform->next = &options->cipher_xform; 373 } else if (options->xform_chain == L2FWD_CRYPTO_CIPHER_ONLY) { 374 first_xform = &options->cipher_xform; 375 } else { 376 first_xform = &options->auth_xform; 377 } 378 379 /* Setup Cipher Parameters */ 380 return rte_cryptodev_sym_session_create(cdev_id, first_xform); 381 } 382 383 ... 384 385 port_cparams[i].session = initialize_crypto_session(options, 386 port_cparams[i].dev_id); 387 388Crypto operation creation 389~~~~~~~~~~~~~~~~~~~~~~~~~ 390 391Given N packets received from a RX PORT, N crypto operations are allocated 392and filled: 393 394.. code-block:: c 395 396 if (nb_rx) { 397 /* 398 * If we can't allocate a crypto_ops, then drop 399 * the rest of the burst and dequeue and 400 * process the packets to free offload structs 401 */ 402 if (rte_crypto_op_bulk_alloc( 403 l2fwd_crypto_op_pool, 404 RTE_CRYPTO_OP_TYPE_SYMMETRIC, 405 ops_burst, nb_rx) != 406 nb_rx) { 407 for (j = 0; j < nb_rx; j++) 408 rte_pktmbuf_free(pkts_burst[i]); 409 410 nb_rx = 0; 411 } 412 413After filling the crypto operation (including session attachment), 414the mbuf which will be transformed is attached to it:: 415 416 op->sym->m_src = m; 417 418Since no destination mbuf is set, the source mbuf will be overwritten 419after the operation is done (in-place). 420 421Crypto operation enqueuing/dequeuing 422~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 423 424Once the operation has been created, it has to be enqueued in one of the crypto devices. 425Before doing so, for performance reasons, the operation stays in a buffer. 426When the buffer has enough operations (MAX_PKT_BURST), they are enqueued in the device, 427which will perform the operation at that moment: 428 429.. code-block:: c 430 431 static int 432 l2fwd_crypto_enqueue(struct rte_crypto_op *op, 433 struct l2fwd_crypto_params *cparams) 434 { 435 unsigned lcore_id, len; 436 struct lcore_queue_conf *qconf; 437 438 lcore_id = rte_lcore_id(); 439 440 qconf = &lcore_queue_conf[lcore_id]; 441 len = qconf->op_buf[cparams->dev_id].len; 442 qconf->op_buf[cparams->dev_id].buffer[len] = op; 443 len++; 444 445 /* enough ops to be sent */ 446 if (len == MAX_PKT_BURST) { 447 l2fwd_crypto_send_burst(qconf, MAX_PKT_BURST, cparams); 448 len = 0; 449 } 450 451 qconf->op_buf[cparams->dev_id].len = len; 452 return 0; 453 } 454 455 ... 456 457 static int 458 l2fwd_crypto_send_burst(struct lcore_queue_conf *qconf, unsigned n, 459 struct l2fwd_crypto_params *cparams) 460 { 461 struct rte_crypto_op **op_buffer; 462 unsigned ret; 463 464 op_buffer = (struct rte_crypto_op **) 465 qconf->op_buf[cparams->dev_id].buffer; 466 467 ret = rte_cryptodev_enqueue_burst(cparams->dev_id, 468 cparams->qp_id, op_buffer, (uint16_t) n); 469 470 crypto_statistics[cparams->dev_id].enqueued += ret; 471 if (unlikely(ret < n)) { 472 crypto_statistics[cparams->dev_id].errors += (n - ret); 473 do { 474 rte_pktmbuf_free(op_buffer[ret]->sym->m_src); 475 rte_crypto_op_free(op_buffer[ret]); 476 } while (++ret < n); 477 } 478 479 return 0; 480 } 481 482After this, the operations are dequeued from the device, and the transformed mbuf 483is extracted from the operation. Then, the operation is freed and the mbuf is 484forwarded as it is done in the L2 forwarding application. 485 486.. code-block:: c 487 488 /* Dequeue packets from Crypto device */ 489 do { 490 nb_rx = rte_cryptodev_dequeue_burst( 491 cparams->dev_id, cparams->qp_id, 492 ops_burst, MAX_PKT_BURST); 493 494 crypto_statistics[cparams->dev_id].dequeued += 495 nb_rx; 496 497 /* Forward crypto'd packets */ 498 for (j = 0; j < nb_rx; j++) { 499 m = ops_burst[j]->sym->m_src; 500 501 rte_crypto_op_free(ops_burst[j]); 502 l2fwd_simple_forward(m, portid); 503 } 504 } while (nb_rx == MAX_PKT_BURST); 505