doc/guides/sample_app_ug/l2_forward_crypto.rst

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