doc/guides/sample_app_ug/l2_forward_crypto.rst

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