1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2016-2017 Intel Corporation.
6 L2 Forwarding with Crypto Sample Application
7 ============================================
9 The L2 Forwarding with Crypto (l2fwd-crypto) sample application is a simple example of packet processing using
10 the Data Plane Development Kit (DPDK), in conjunction with the Cryptodev library.
15 The L2 Forwarding with Crypto sample application performs a crypto operation (cipher/hash)
16 specified by the user from command line (or using the default values),
17 with a crypto device capable of doing that operation,
18 for each packet that is received on a RX_PORT and performs L2 forwarding.
19 The destination port is the adjacent port from the enabled portmask, that is,
20 if the first four ports are enabled (portmask 0xf),
21 ports 0 and 1 forward into each other, and ports 2 and 3 forward into each other.
22 Also, if MAC addresses updating is enabled, the MAC addresses are affected as follows:
24 * The source MAC address is replaced by the TX_PORT MAC address
26 * The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID
28 Compiling the Application
29 -------------------------
31 To compile the sample application see :doc:`compiling`.
33 The application is located in the ``l2fwd-crypt`` sub-directory.
35 Running the Application
36 -----------------------
38 The application requires a number of command line options:
40 .. code-block:: console
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]
57 * p PORTMASK: A hexadecimal bitmask of the ports to configure (default is all the ports)
59 * q NQ: A number of queues (=ports) per lcore (default is 1)
61 * s: manage all ports from single core
63 * T PERIOD: statistics will be refreshed each PERIOD seconds
65 (0 to disable, 10 default, 86400 maximum)
67 * cdev_type: select preferred crypto device type: HW, SW or anything (ANY)
71 * chain: select the operation chaining to perform: Cipher->Hash (CIPHER_HASH),
73 Hash->Cipher (HASH_CIPHER), Cipher (CIPHER_ONLY), Hash (HASH_ONLY)
77 (default is Cipher->Hash)
79 * cipher_algo: select the ciphering algorithm (default is aes-cbc)
81 * cipher_op: select the ciphering operation to perform: ENCRYPT or DECRYPT
85 * cipher_dataunit_len: set the length of the cipher data-unit.
87 * cipher_key: set the ciphering key to be used. Bytes has to be separated with ":"
89 * cipher_key_random_size: set the size of the ciphering key,
91 which will be generated randomly.
93 Note that if --cipher_key is used, this will be ignored.
95 * cipher_iv: set the cipher IV to be used. Bytes has to be separated with ":"
97 * cipher_iv_random_size: set the size of the cipher IV, which will be generated randomly.
99 Note that if --cipher_iv is used, this will be ignored.
101 * auth_algo: select the authentication algorithm (default is sha1-hmac)
103 * auth_op: select the authentication operation to perform: GENERATE or VERIFY
105 (default is GENERATE)
107 * auth_key: set the authentication key to be used. Bytes has to be separated with ":"
109 * auth_key_random_size: set the size of the authentication key,
111 which will be generated randomly.
113 Note that if --auth_key is used, this will be ignored.
115 * auth_iv: set the auth IV to be used. Bytes has to be separated with ":"
117 * auth_iv_random_size: set the size of the auth IV, which will be generated randomly.
119 Note that if --auth_iv is used, this will be ignored.
121 * aead_algo: select the AEAD algorithm (default is aes-gcm)
123 * aead_op: select the AEAD operation to perform: ENCRYPT or DECRYPT
127 * aead_key: set the AEAD key to be used. Bytes has to be separated with ":"
129 * aead_key_random_size: set the size of the AEAD key,
131 which will be generated randomly.
133 Note that if --aead_key is used, this will be ignored.
135 * aead_iv: set the AEAD IV to be used. Bytes has to be separated with ":"
137 * aead_iv_random_size: set the size of the AEAD IV, which will be generated randomly.
139 Note that if --aead_iv is used, this will be ignored.
141 * aad: set the AAD to be used. Bytes has to be separated with ":"
143 * aad_random_size: set the size of the AAD, which will be generated randomly.
145 Note that if --aad is used, this will be ignored.
147 * digest_size: set the size of the digest to be generated/verified.
149 * sessionless: no crypto session will be created.
151 * cryptodev_mask: A hexadecimal bitmask of the cryptodevs to be used by the
154 (default is all cryptodevs).
156 * [no-]mac-updating: Enable or disable MAC addresses updating (enabled by default).
159 The application requires that crypto devices capable of performing
160 the specified crypto operation are available on application initialization.
161 This means that HW crypto device/s must be bound to a DPDK driver or
162 a SW crypto device/s (virtual crypto PMD) must be created (using --vdev).
164 To run the application in linux environment with 2 lcores, 2 ports and 2 crypto devices, issue the command:
166 .. code-block:: console
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
175 Refer to the *DPDK Getting Started Guide* for general information on running applications
176 and the Environment Abstraction Layer (EAL) options.
180 * The ``l2fwd-crypto`` sample application requires IPv4 packets for crypto operation.
182 * If multiple Ethernet ports is passed, then equal number of crypto devices are to be passed.
184 * All crypto devices shall use the same session.
189 The L2 forward with Crypto application demonstrates the performance of a crypto operation
190 on a packet received on a RX PORT before forwarding it to a TX PORT.
192 The following figure illustrates a sample flow of a packet in the application,
193 from reception until transmission.
195 .. _figure_l2_fwd_encrypt_flow:
197 .. figure:: img/l2_fwd_encrypt_flow.*
199 Encryption flow Through the L2 Forwarding with Crypto Application
202 The following sections provide some explanation of the application.
204 Crypto operation specification
205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
207 All the packets received in all the ports get transformed by the crypto device/s
208 (ciphering and/or authentication).
209 The 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).
212 If no parameter is passed, the default crypto operation is:
214 * Encryption with AES-CBC with 128 bit key.
216 * Authentication with SHA1-HMAC (generation).
218 * Keys, IV and AAD are generated randomly.
220 There are two methods to pass keys, IV and ADD from the command line:
222 * Passing the full key, separated bytes by ":"::
224 --cipher_key 00:11:22:33:44
226 * Passing the size, so key is generated randomly::
228 --cipher_key_random_size 16
231 If full key is passed (first method) and the size is passed as well (second method),
232 the latter will be ignored.
234 Size of these keys are checked (regardless the method), before starting the app,
235 to make sure that it is supported by the crypto devices.
237 Crypto device initialization
238 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
240 Once the encryption operation is defined, crypto devices are initialized.
241 The crypto devices must be either bound to a DPDK driver (if they are physical devices)
242 or created using the EAL option --vdev (if they are virtual devices),
243 when running the application.
245 The initialize_cryptodevs() function performs the device initialization.
246 It iterates through the list of the available crypto devices and
247 check which ones are capable of performing the operation.
248 Each device has a set of capabilities associated with it,
249 which are stored in the device info structure, so the function checks if the operation
250 is within the structure of each device.
252 The following code checks if the device supports the specified cipher algorithm
253 (similar for the authentication algorithm):
255 .. literalinclude:: ../../../examples/l2fwd-crypto/main.c
257 :start-after: Check if device supports cipher algo. 8<
258 :end-before: >8 End of check if device supports cipher algo.
261 If a capable crypto device is found, key sizes are checked to see if they are supported
262 (cipher key and IV for the ciphering):
264 .. literalinclude:: ../../../examples/l2fwd-crypto/main.c
266 :start-after: Check if capable cipher is supported. 8<
267 :end-before: >8 End of checking if cipher is supported.
270 After all the checks, the device is configured and it is added to the
274 The number of crypto devices that supports the specified crypto operation
275 must be at least the number of ports to be used.
280 The crypto operation has a crypto session associated to it, which contains
281 information such as the transform chain to perform (e.g. ciphering then hashing),
282 pointers to the keys, lengths... etc.
284 This session is created and is later attached to the crypto operation:
286 .. literalinclude:: ../../../examples/l2fwd-crypto/main.c
288 :start-after: Session is created and is later attached to the crypto operation. 8<
289 :end-before: >8 End of creation of session.
291 Crypto operation creation
292 ~~~~~~~~~~~~~~~~~~~~~~~~~
294 Given N packets received from a RX PORT, N crypto operations are allocated
297 .. literalinclude:: ../../../examples/l2fwd-crypto/main.c
299 :start-after: Allocate and fillcrypto operations. 8<
300 :end-before: >8 End of crypto operation allocated and filled.
303 After filling the crypto operation (including session attachment),
304 the mbuf which will be transformed is attached to it::
308 Since no destination mbuf is set, the source mbuf will be overwritten
309 after the operation is done (in-place).
311 Crypto operation enqueuing/dequeuing
312 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
314 Once the operation has been created, it has to be enqueued in one of the crypto devices.
315 Before doing so, for performance reasons, the operation stays in a buffer.
316 When the buffer has enough operations (MAX_PKT_BURST), they are enqueued in the device,
317 which will perform the operation at that moment:
319 .. literalinclude:: ../../../examples/l2fwd-crypto/main.c
321 :start-after: Crypto enqueue. 8<
322 :end-before: >8 End of crypto enqueue.
324 .. literalinclude:: ../../../examples/l2fwd-crypto/main.c
326 :start-after: l2fwd_crypto_send_burst 8<
327 :end-before: >8 End of l2fwd_crypto_send_burst.
329 After this, the operations are dequeued from the device, and the transformed mbuf
330 is extracted from the operation. Then, the operation is freed and the mbuf is
331 forwarded as it is done in the L2 forwarding application.
333 .. literalinclude:: ../../../examples/l2fwd-crypto/main.c
335 :start-after: Dequeue packets from Crypto device. 8<
336 :end-before: >8 End of dequeue packets from crypto device.