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, 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 95where, 96 97* p PORTMASK: A hexadecimal bitmask of the ports to configure (default is all the ports) 98 99* q NQ: A number of queues (=ports) per lcore (default is 1) 100 101* s: manage all ports from single core 102 103* T PERIOD: statistics will be refreshed each PERIOD seconds 104 105 (0 to disable, 10 default, 86400 maximum) 106 107* cdev_type: select preferred crypto device type: HW, SW or anything (ANY) 108 109 (default is ANY) 110 111* chain: select the operation chaining to perform: Cipher->Hash (CIPHER_HASH), 112 113 Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash (HASH_ONLY) 114 115 or AEAD (AEAD) 116 117 (default is Cipher->Hash) 118 119* cipher_algo: select the ciphering algorithm (default is aes-cbc) 120 121* cipher_op: select the ciphering operation to perform: ENCRYPT or DECRYPT 122 123 (default is ENCRYPT) 124 125* cipher_key: set the ciphering key to be used. Bytes has to be separated with ":" 126 127* cipher_key_random_size: set the size of the ciphering key, 128 129 which will be generated randomly. 130 131 Note that if --cipher_key is used, this will be ignored. 132 133* cipher_iv: set the cipher IV to be used. Bytes has to be separated with ":" 134 135* cipher_iv_random_size: set the size of the cipher IV, which will be generated randomly. 136 137 Note that if --cipher_iv is used, this will be ignored. 138 139* auth_algo: select the authentication algorithm (default is sha1-hmac) 140 141* auth_op: select the authentication operation to perform: GENERATE or VERIFY 142 143 (default is GENERATE) 144 145* auth_key: set the authentication key to be used. Bytes has to be separated with ":" 146 147* auth_key_random_size: set the size of the authentication key, 148 149 which will be generated randomly. 150 151 Note that if --auth_key is used, this will be ignored. 152 153* auth_iv: set the auth IV to be used. Bytes has to be separated with ":" 154 155* auth_iv_random_size: set the size of the auth IV, which will be generated randomly. 156 157 Note that if --auth_iv is used, this will be ignored. 158 159* aead_algo: select the AEAD algorithm (default is aes-gcm) 160 161* aead_op: select the AEAD operation to perform: ENCRYPT or DECRYPT 162 163 (default is ENCRYPT) 164 165* aead_key: set the AEAD key to be used. Bytes has to be separated with ":" 166 167* aead_key_random_size: set the size of the AEAD key, 168 169 which will be generated randomly. 170 171 Note that if --aead_key is used, this will be ignored. 172 173* aead_iv: set the AEAD IV to be used. Bytes has to be separated with ":" 174 175* aead_iv_random_size: set the size of the AEAD IV, which will be generated randomly. 176 177 Note that if --aead_iv is used, this will be ignored. 178 179* aad: set the AAD to be used. Bytes has to be separated with ":" 180 181* aad_random_size: set the size of the AAD, which will be generated randomly. 182 183 Note that if --aad is used, this will be ignored. 184 185* digest_size: set the size of the digest to be generated/verified. 186 187* sessionless: no crypto session will be created. 188 189* cryptodev_mask: A hexadecimal bitmask of the cryptodevs to be used by the 190 application. 191 192 (default is all cryptodevs). 193 194 195The application requires that crypto devices capable of performing 196the specified crypto operation are available on application initialization. 197This means that HW crypto device/s must be bound to a DPDK driver or 198a SW crypto device/s (virtual crypto PMD) must be created (using --vdev). 199 200To run the application in linuxapp environment with 2 lcores, 2 ports and 2 crypto devices, issue the command: 201 202.. code-block:: console 203 204 $ ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "cryptodev_aesni_mb_pmd" \ 205 --vdev "cryptodev_aesni_mb_pmd" -- -p 0x3 --chain CIPHER_HASH \ 206 --cipher_op ENCRYPT --cipher_algo aes-cbc \ 207 --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \ 208 --auth_op GENERATE --auth_algo aes-xcbc-mac \ 209 --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f 210 211Refer to the *DPDK Getting Started Guide* for general information on running applications 212and the Environment Abstraction Layer (EAL) options. 213 214Explanation 215----------- 216 217The L2 forward with Crypto application demonstrates the performance of a crypto operation 218on a packet received on a RX PORT before forwarding it to a TX PORT. 219 220The following figure illustrates a sample flow of a packet in the application, 221from reception until transmission. 222 223.. _figure_l2_fwd_encrypt_flow: 224 225.. figure:: img/l2_fwd_encrypt_flow.* 226 227 Encryption flow Through the L2 Forwarding with Crypto Application 228 229 230The following sections provide some explanation of the application. 231 232Crypto operation specification 233~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 234 235All the packets received in all the ports get transformed by the crypto device/s 236(ciphering and/or authentication). 237The crypto operation to be performed on the packet is parsed from the command line 238(go to "Running the Application section for all the options). 239 240If no parameter is passed, the default crypto operation is: 241 242* Encryption with AES-CBC with 128 bit key. 243 244* Authentication with SHA1-HMAC (generation). 245 246* Keys, IV and AAD are generated randomly. 247 248There are two methods to pass keys, IV and ADD from the command line: 249 250* Passing the full key, separated bytes by ":":: 251 252 --cipher_key 00:11:22:33:44 253 254* Passing the size, so key is generated randomly:: 255 256 --cipher_key_random_size 16 257 258**Note**: 259 If full key is passed (first method) and the size is passed as well (second method), 260 the latter will be ignored. 261 262Size of these keys are checked (regardless the method), before starting the app, 263to make sure that it is supported by the crypto devices. 264 265Crypto device initialization 266~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 267 268Once the encryption operation is defined, crypto devices are initialized. 269The crypto devices must be either bound to a DPDK driver (if they are physical devices) 270or created using the EAL option --vdev (if they are virtual devices), 271when running the application. 272 273The initialize_cryptodevs() function performs the device initialization. 274It iterates through the list of the available crypto devices and 275check which ones are capable of performing the operation. 276Each device has a set of capabilities associated with it, 277which are stored in the device info structure, so the function checks if the operation 278is within the structure of each device. 279 280The following code checks if the device supports the specified cipher algorithm 281(similar for the authentication algorithm): 282 283.. code-block:: c 284 285 /* Check if device supports cipher algo */ 286 i = 0; 287 opt_cipher_algo = options->cipher_xform.cipher.algo; 288 cap = &dev_info.capabilities[i]; 289 while (cap->op != RTE_CRYPTO_OP_TYPE_UNDEFINED) { 290 cap_cipher_algo = cap->sym.cipher.algo; 291 if (cap->sym.xform_type == 292 RTE_CRYPTO_SYM_XFORM_CIPHER) { 293 if (cap_cipher_algo == opt_cipher_algo) { 294 if (check_type(options, &dev_info) == 0) 295 break; 296 } 297 } 298 cap = &dev_info.capabilities[++i]; 299 } 300 301If a capable crypto device is found, key sizes are checked to see if they are supported 302(cipher key and IV for the ciphering): 303 304.. code-block:: c 305 306 /* 307 * Check if length of provided cipher key is supported 308 * by the algorithm chosen. 309 */ 310 if (options->ckey_param) { 311 if (check_supported_size( 312 options->cipher_xform.cipher.key.length, 313 cap->sym.cipher.key_size.min, 314 cap->sym.cipher.key_size.max, 315 cap->sym.cipher.key_size.increment) 316 != 0) { 317 printf("Unsupported cipher key length\n"); 318 return -1; 319 } 320 /* 321 * Check if length of the cipher key to be randomly generated 322 * is supported by the algorithm chosen. 323 */ 324 } else if (options->ckey_random_size != -1) { 325 if (check_supported_size(options->ckey_random_size, 326 cap->sym.cipher.key_size.min, 327 cap->sym.cipher.key_size.max, 328 cap->sym.cipher.key_size.increment) 329 != 0) { 330 printf("Unsupported cipher key length\n"); 331 return -1; 332 } 333 options->cipher_xform.cipher.key.length = 334 options->ckey_random_size; 335 /* No size provided, use minimum size. */ 336 } else 337 options->cipher_xform.cipher.key.length = 338 cap->sym.cipher.key_size.min; 339 340After all the checks, the device is configured and it is added to the 341crypto device list. 342 343**Note**: 344 The number of crypto devices that supports the specified crypto operation 345 must be at least the number of ports to be used. 346 347Session creation 348~~~~~~~~~~~~~~~~ 349 350The crypto operation has a crypto session associated to it, which contains 351information such as the transform chain to perform (e.g. ciphering then hashing), 352pointers to the keys, lengths... etc. 353 354This session is created and is later attached to the crypto operation: 355 356.. code-block:: c 357 358 static struct rte_cryptodev_sym_session * 359 initialize_crypto_session(struct l2fwd_crypto_options *options, 360 uint8_t cdev_id) 361 { 362 struct rte_crypto_sym_xform *first_xform; 363 364 if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) { 365 first_xform = &options->cipher_xform; 366 first_xform->next = &options->auth_xform; 367 } else if (options->xform_chain == L2FWD_CRYPTO_HASH_CIPHER) { 368 first_xform = &options->auth_xform; 369 first_xform->next = &options->cipher_xform; 370 } else if (options->xform_chain == L2FWD_CRYPTO_CIPHER_ONLY) { 371 first_xform = &options->cipher_xform; 372 } else { 373 first_xform = &options->auth_xform; 374 } 375 376 /* Setup Cipher Parameters */ 377 return rte_cryptodev_sym_session_create(cdev_id, first_xform); 378 } 379 380 ... 381 382 port_cparams[i].session = initialize_crypto_session(options, 383 port_cparams[i].dev_id); 384 385Crypto operation creation 386~~~~~~~~~~~~~~~~~~~~~~~~~ 387 388Given N packets received from a RX PORT, N crypto operations are allocated 389and filled: 390 391.. code-block:: c 392 393 if (nb_rx) { 394 /* 395 * If we can't allocate a crypto_ops, then drop 396 * the rest of the burst and dequeue and 397 * process the packets to free offload structs 398 */ 399 if (rte_crypto_op_bulk_alloc( 400 l2fwd_crypto_op_pool, 401 RTE_CRYPTO_OP_TYPE_SYMMETRIC, 402 ops_burst, nb_rx) != 403 nb_rx) { 404 for (j = 0; j < nb_rx; j++) 405 rte_pktmbuf_free(pkts_burst[i]); 406 407 nb_rx = 0; 408 } 409 410After filling the crypto operation (including session attachment), 411the mbuf which will be transformed is attached to it:: 412 413 op->sym->m_src = m; 414 415Since no destination mbuf is set, the source mbuf will be overwritten 416after the operation is done (in-place). 417 418Crypto operation enqueuing/dequeuing 419~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 420 421Once the operation has been created, it has to be enqueued in one of the crypto devices. 422Before doing so, for performance reasons, the operation stays in a buffer. 423When the buffer has enough operations (MAX_PKT_BURST), they are enqueued in the device, 424which will perform the operation at that moment: 425 426.. code-block:: c 427 428 static int 429 l2fwd_crypto_enqueue(struct rte_crypto_op *op, 430 struct l2fwd_crypto_params *cparams) 431 { 432 unsigned lcore_id, len; 433 struct lcore_queue_conf *qconf; 434 435 lcore_id = rte_lcore_id(); 436 437 qconf = &lcore_queue_conf[lcore_id]; 438 len = qconf->op_buf[cparams->dev_id].len; 439 qconf->op_buf[cparams->dev_id].buffer[len] = op; 440 len++; 441 442 /* enough ops to be sent */ 443 if (len == MAX_PKT_BURST) { 444 l2fwd_crypto_send_burst(qconf, MAX_PKT_BURST, cparams); 445 len = 0; 446 } 447 448 qconf->op_buf[cparams->dev_id].len = len; 449 return 0; 450 } 451 452 ... 453 454 static int 455 l2fwd_crypto_send_burst(struct lcore_queue_conf *qconf, unsigned n, 456 struct l2fwd_crypto_params *cparams) 457 { 458 struct rte_crypto_op **op_buffer; 459 unsigned ret; 460 461 op_buffer = (struct rte_crypto_op **) 462 qconf->op_buf[cparams->dev_id].buffer; 463 464 ret = rte_cryptodev_enqueue_burst(cparams->dev_id, 465 cparams->qp_id, op_buffer, (uint16_t) n); 466 467 crypto_statistics[cparams->dev_id].enqueued += ret; 468 if (unlikely(ret < n)) { 469 crypto_statistics[cparams->dev_id].errors += (n - ret); 470 do { 471 rte_pktmbuf_free(op_buffer[ret]->sym->m_src); 472 rte_crypto_op_free(op_buffer[ret]); 473 } while (++ret < n); 474 } 475 476 return 0; 477 } 478 479After this, the operations are dequeued from the device, and the transformed mbuf 480is extracted from the operation. Then, the operation is freed and the mbuf is 481forwarded as it is done in the L2 forwarding application. 482 483.. code-block:: c 484 485 /* Dequeue packets from Crypto device */ 486 do { 487 nb_rx = rte_cryptodev_dequeue_burst( 488 cparams->dev_id, cparams->qp_id, 489 ops_burst, MAX_PKT_BURST); 490 491 crypto_statistics[cparams->dev_id].dequeued += 492 nb_rx; 493 494 /* Forward crypto'd packets */ 495 for (j = 0; j < nb_rx; j++) { 496 m = ops_burst[j]->sym->m_src; 497 498 rte_crypto_op_free(ops_burst[j]); 499 l2fwd_simple_forward(m, portid); 500 } 501 } while (nb_rx == MAX_PKT_BURST); 502