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