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