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