2 Copyright(c) 2016-2017 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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
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.
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.
31 .. _l2_fwd_crypto_app:
33 L2 Forwarding with Crypto Sample Application
34 ============================================
36 The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example of packet processing using
37 the Data Plane Development Kit (DPDK), in conjunction with the Cryptodev library.
42 The L2 Forwarding with Crypto sample application performs a crypto operation (cipher/hash)
43 specified by the user from command line (or using the default values),
44 with a crypto device capable of doing that operation,
45 for each packet that is received on a RX_PORT and performs L2 forwarding.
46 The destination port is the adjacent port from the enabled portmask, that is,
47 if the first four ports are enabled (portmask 0xf),
48 ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other.
49 Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows:
51 * The source MAC address is replaced by the TX_PORT MAC address
53 * The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID
55 Compiling the Application
56 -------------------------
58 To compile the sample application see :doc:`compiling`.
60 The application is located in the ``l2fwd-crypt`` sub-directory.
62 Running the Application
63 -----------------------
65 The application requires a number of command line options:
67 .. code-block:: console
69 ./build/l2fwd-crypto [EAL options] -- [-p PORTMASK] [-q NQ] [-s] [-T PERIOD] /
70 [--cdev_type HW/SW/ANY] [--chain HASH_CIPHER/CIPHER_HASH/CIPHER_ONLY/HASH_ONLY/AEAD] /
71 [--cipher_algo ALGO] [--cipher_op ENCRYPT/DECRYPT] [--cipher_key KEY] /
72 [--cipher_key_random_size SIZE] [--cipher_iv IV] [--cipher_iv_random_size SIZE] /
73 [--auth_algo ALGO] [--auth_op GENERATE/VERIFY] [--auth_key KEY] /
74 [--auth_key_random_size SIZE] [--auth_iv IV] [--auth_iv_random_size SIZE] /
75 [--aead_algo ALGO] [--aead_op ENCRYPT/DECRYPT] [--aead_key KEY] /
76 [--aead_key_random_size SIZE] [--aead_iv] [--aead_iv_random_size SIZE] /
77 [--aad AAD] [--aad_random_size SIZE] /
78 [--digest size SIZE] [--sessionless] [--cryptodev_mask MASK] /
79 [--mac-updating] [--no-mac-updating]
83 * p PORTMASK: A hexadecimal bitmask of the ports to configure (default is all the ports)
85 * q NQ: A number of queues (=ports) per lcore (default is 1)
87 * s: manage all ports from single core
89 * T PERIOD: statistics will be refreshed each PERIOD seconds
91 (0 to disable, 10 default, 86400 maximum)
93 * cdev_type: select preferred crypto device type: HW, SW or anything (ANY)
97 * chain: select the operation chaining to perform: Cipher->Hash (CIPHER_HASH),
99 Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash (HASH_ONLY)
103 (default is Cipher->Hash)
105 * cipher_algo: select the ciphering algorithm (default is aes-cbc)
107 * cipher_op: select the ciphering operation to perform: ENCRYPT or DECRYPT
111 * cipher_key: set the ciphering key to be used. Bytes has to be separated with ":"
113 * cipher_key_random_size: set the size of the ciphering key,
115 which will be generated randomly.
117 Note that if --cipher_key is used, this will be ignored.
119 * cipher_iv: set the cipher IV to be used. Bytes has to be separated with ":"
121 * cipher_iv_random_size: set the size of the cipher IV, which will be generated randomly.
123 Note that if --cipher_iv is used, this will be ignored.
125 * auth_algo: select the authentication algorithm (default is sha1-hmac)
127 * auth_op: select the authentication operation to perform: GENERATE or VERIFY
129 (default is GENERATE)
131 * auth_key: set the authentication key to be used. Bytes has to be separated with ":"
133 * auth_key_random_size: set the size of the authentication key,
135 which will be generated randomly.
137 Note that if --auth_key is used, this will be ignored.
139 * auth_iv: set the auth IV to be used. Bytes has to be separated with ":"
141 * auth_iv_random_size: set the size of the auth IV, which will be generated randomly.
143 Note that if --auth_iv is used, this will be ignored.
145 * aead_algo: select the AEAD algorithm (default is aes-gcm)
147 * aead_op: select the AEAD operation to perform: ENCRYPT or DECRYPT
151 * aead_key: set the AEAD key to be used. Bytes has to be separated with ":"
153 * aead_key_random_size: set the size of the AEAD key,
155 which will be generated randomly.
157 Note that if --aead_key is used, this will be ignored.
159 * aead_iv: set the AEAD IV to be used. Bytes has to be separated with ":"
161 * aead_iv_random_size: set the size of the AEAD IV, which will be generated randomly.
163 Note that if --aead_iv is used, this will be ignored.
165 * aad: set the AAD to be used. Bytes has to be separated with ":"
167 * aad_random_size: set the size of the AAD, which will be generated randomly.
169 Note that if --aad is used, this will be ignored.
171 * digest_size: set the size of the digest to be generated/verified.
173 * sessionless: no crypto session will be created.
175 * cryptodev_mask: A hexadecimal bitmask of the cryptodevs to be used by the
178 (default is all cryptodevs).
180 * [no-]mac-updating: Enable or disable MAC addresses updating (enabled by default).
183 The application requires that crypto devices capable of performing
184 the specified crypto operation are available on application initialization.
185 This means that HW crypto device/s must be bound to a DPDK driver or
186 a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
188 To run the application in linuxapp environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
190 .. code-block:: console
192 $ ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "crypto_aesni_mb0" \
193 --vdev "crypto_aesni_mb1" -- -p 0x3 --chain CIPHER_HASH \
194 --cipher_op ENCRYPT --cipher_algo aes-cbc \
195 --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \
196 --auth_op GENERATE --auth_algo aes-xcbc-mac \
197 --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f
199 Refer to the *DPDK Getting Started Guide* for general information on running applications
200 and the Environment Abstraction Layer (EAL) options.
204 * The ``l2fwd-crypto`` sample application requires IPv4 packets for crypto operation.
206 * If multiple Ethernet ports is passed, then equal number of crypto devices are to be passed.
208 * All crypto devices shall use the same session.
213 The L2 forward with Crypto application demonstrates the performance of a crypto operation
214 on a packet received on a RX PORT before forwarding it to a TX PORT.
216 The following figure illustrates a sample flow of a packet in the application,
217 from reception until transmission.
219 .. _figure_l2_fwd_encrypt_flow:
221 .. figure:: img/l2_fwd_encrypt_flow.*
223 Encryption flow Through the L2 Forwarding with Crypto Application
226 The following sections provide some explanation of the application.
228 Crypto operation specification
229 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
231 All the packets received in all the ports get transformed by the crypto device/s
232 (ciphering and/or authentication).
233 The crypto operation to be performed on the packet is parsed from the command line
234 (go to "Running the Application section for all the options).
236 If no parameter is passed, the default crypto operation is:
238 * Encryption with AES-CBC with 128 bit key.
240 * Authentication with SHA1-HMAC (generation).
242 * Keys, IV and AAD are generated randomly.
244 There are two methods to pass keys, IV and ADD from the command line:
246 * Passing the full key, separated bytes by ":"::
248 --cipher_key 00:11:22:33:44
250 * Passing the size, so key is generated randomly::
252 --cipher_key_random_size 16
255 If full key is passed (first method) and the size is passed as well (second method),
256 the latter will be ignored.
258 Size of these keys are checked (regardless the method), before starting the app,
259 to make sure that it is supported by the crypto devices.
261 Crypto device initialization
262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
264 Once the encryption operation is defined, crypto devices are initialized.
265 The crypto devices must be either bound to a DPDK driver (if they are physical devices)
266 or created using the EAL option --vdev (if they are virtual devices),
267 when running the application.
269 The initialize_cryptodevs() function performs the device initialization.
270 It iterates through the list of the available crypto devices and
271 check which ones are capable of performing the operation.
272 Each device has a set of capabilities associated with it,
273 which are stored in the device info structure, so the function checks if the operation
274 is within the structure of each device.
276 The following code checks if the device supports the specified cipher algorithm
277 (similar for the authentication algorithm):
281 /* Check if device supports cipher algo */
283 opt_cipher_algo = options->cipher_xform.cipher.algo;
284 cap = &dev_info.capabilities[i];
285 while (cap->op != RTE_CRYPTO_OP_TYPE_UNDEFINED) {
286 cap_cipher_algo = cap->sym.cipher.algo;
287 if (cap->sym.xform_type ==
288 RTE_CRYPTO_SYM_XFORM_CIPHER) {
289 if (cap_cipher_algo == opt_cipher_algo) {
290 if (check_type(options, &dev_info) == 0)
294 cap = &dev_info.capabilities[++i];
297 If a capable crypto device is found, key sizes are checked to see if they are supported
298 (cipher key and IV for the ciphering):
303 * Check if length of provided cipher key is supported
304 * by the algorithm chosen.
306 if (options->ckey_param) {
307 if (check_supported_size(
308 options->cipher_xform.cipher.key.length,
309 cap->sym.cipher.key_size.min,
310 cap->sym.cipher.key_size.max,
311 cap->sym.cipher.key_size.increment)
313 printf("Unsupported cipher key length\n");
317 * Check if length of the cipher key to be randomly generated
318 * is supported by the algorithm chosen.
320 } else if (options->ckey_random_size != -1) {
321 if (check_supported_size(options->ckey_random_size,
322 cap->sym.cipher.key_size.min,
323 cap->sym.cipher.key_size.max,
324 cap->sym.cipher.key_size.increment)
326 printf("Unsupported cipher key length\n");
329 options->cipher_xform.cipher.key.length =
330 options->ckey_random_size;
331 /* No size provided, use minimum size. */
333 options->cipher_xform.cipher.key.length =
334 cap->sym.cipher.key_size.min;
336 After all the checks, the device is configured and it is added to the
340 The number of crypto devices that supports the specified crypto operation
341 must be at least the number of ports to be used.
346 The crypto operation has a crypto session associated to it, which contains
347 information such as the transform chain to perform (e.g. ciphering then hashing),
348 pointers to the keys, lengths... etc.
350 This session is created and is later attached to the crypto operation:
354 static struct rte_cryptodev_sym_session *
355 initialize_crypto_session(struct l2fwd_crypto_options *options,
358 struct rte_crypto_sym_xform *first_xform;
359 struct rte_cryptodev_sym_session *session;
360 uint8_t socket_id = rte_cryptodev_socket_id(cdev_id);
361 struct rte_mempool *sess_mp = session_pool_socket[socket_id];
364 if (options->xform_chain == L2FWD_CRYPTO_AEAD) {
365 first_xform = &options->aead_xform;
366 } else if (options->xform_chain == L2FWD_CRYPTO_CIPHER_HASH) {
367 first_xform = &options->cipher_xform;
368 first_xform->next = &options->auth_xform;
369 } else if (options->xform_chain == L2FWD_CRYPTO_HASH_CIPHER) {
370 first_xform = &options->auth_xform;
371 first_xform->next = &options->cipher_xform;
372 } else if (options->xform_chain == L2FWD_CRYPTO_CIPHER_ONLY) {
373 first_xform = &options->cipher_xform;
375 first_xform = &options->auth_xform;
378 session = rte_cryptodev_sym_session_create(sess_mp);
383 if (rte_cryptodev_sym_session_init(cdev_id, session,
384 first_xform, sess_mp) < 0)
392 port_cparams[i].session = initialize_crypto_session(options,
393 port_cparams[i].dev_id);
395 Crypto operation creation
396 ~~~~~~~~~~~~~~~~~~~~~~~~~
398 Given N packets received from a RX PORT, N crypto operations are allocated
405 * If we can't allocate a crypto_ops, then drop
406 * the rest of the burst and dequeue and
407 * process the packets to free offload structs
409 if (rte_crypto_op_bulk_alloc(
410 l2fwd_crypto_op_pool,
411 RTE_CRYPTO_OP_TYPE_SYMMETRIC,
414 for (j = 0; j < nb_rx; j++)
415 rte_pktmbuf_free(pkts_burst[i]);
420 After filling the crypto operation (including session attachment),
421 the mbuf which will be transformed is attached to it::
425 Since no destination mbuf is set, the source mbuf will be overwritten
426 after the operation is done (in-place).
428 Crypto operation enqueuing/dequeuing
429 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
431 Once the operation has been created, it has to be enqueued in one of the crypto devices.
432 Before doing so, for performance reasons, the operation stays in a buffer.
433 When the buffer has enough operations (MAX_PKT_BURST), they are enqueued in the device,
434 which will perform the operation at that moment:
439 l2fwd_crypto_enqueue(struct rte_crypto_op *op,
440 struct l2fwd_crypto_params *cparams)
442 unsigned lcore_id, len;
443 struct lcore_queue_conf *qconf;
445 lcore_id = rte_lcore_id();
447 qconf = &lcore_queue_conf[lcore_id];
448 len = qconf->op_buf[cparams->dev_id].len;
449 qconf->op_buf[cparams->dev_id].buffer[len] = op;
452 /* enough ops to be sent */
453 if (len == MAX_PKT_BURST) {
454 l2fwd_crypto_send_burst(qconf, MAX_PKT_BURST, cparams);
458 qconf->op_buf[cparams->dev_id].len = len;
465 l2fwd_crypto_send_burst(struct lcore_queue_conf *qconf, unsigned n,
466 struct l2fwd_crypto_params *cparams)
468 struct rte_crypto_op **op_buffer;
471 op_buffer = (struct rte_crypto_op **)
472 qconf->op_buf[cparams->dev_id].buffer;
474 ret = rte_cryptodev_enqueue_burst(cparams->dev_id,
475 cparams->qp_id, op_buffer, (uint16_t) n);
477 crypto_statistics[cparams->dev_id].enqueued += ret;
478 if (unlikely(ret < n)) {
479 crypto_statistics[cparams->dev_id].errors += (n - ret);
481 rte_pktmbuf_free(op_buffer[ret]->sym->m_src);
482 rte_crypto_op_free(op_buffer[ret]);
489 After this, the operations are dequeued from the device, and the transformed mbuf
490 is extracted from the operation. Then, the operation is freed and the mbuf is
491 forwarded as it is done in the L2 forwarding application.
495 /* Dequeue packets from Crypto device */
497 nb_rx = rte_cryptodev_dequeue_burst(
498 cparams->dev_id, cparams->qp_id,
499 ops_burst, MAX_PKT_BURST);
501 crypto_statistics[cparams->dev_id].dequeued +=
504 /* Forward crypto'd packets */
505 for (j = 0; j < nb_rx; j++) {
506 m = ops_burst[j]->sym->m_src;
508 rte_crypto_op_free(ops_burst[j]);
509 l2fwd_simple_forward(m, portid);
511 } while (nb_rx == MAX_PKT_BURST);