1.. BSD LICENSE 2 Copyright(c) 2016-2017 Intel Corporation. All rights reserved. 3 4 Redistribution and use in source and binary forms, with or without 5 modification, are permitted provided that the following conditions 6 are met: 7 8 * Redistributions of source code must retain the above copyright 9 notice, this list of conditions and the following disclaimer. 10 * Redistributions in binary form must reproduce the above copyright 11 notice, this list of conditions and the following disclaimer in 12 the documentation and/or other materials provided with the 13 distribution. 14 * Neither the name of Intel Corporation nor the names of its 15 contributors may be used to endorse or promote products derived 16 from this software without specific prior written permission. 17 18 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30 31Cryptography Device Library 32=========================== 33 34The cryptodev library provides a Crypto device framework for management and 35provisioning of hardware and software Crypto poll mode drivers, defining generic 36APIs which support a number of different Crypto operations. The framework 37currently only supports cipher, authentication, chained cipher/authentication 38and AEAD symmetric Crypto operations. 39 40 41Design Principles 42----------------- 43 44The cryptodev library follows the same basic principles as those used in DPDKs 45Ethernet Device framework. The Crypto framework provides a generic Crypto device 46framework which supports both physical (hardware) and virtual (software) Crypto 47devices as well as a generic Crypto API which allows Crypto devices to be 48managed and configured and supports Crypto operations to be provisioned on 49Crypto poll mode driver. 50 51 52Device Management 53----------------- 54 55Device Creation 56~~~~~~~~~~~~~~~ 57 58Physical Crypto devices are discovered during the PCI probe/enumeration of the 59EAL function which is executed at DPDK initialization, based on 60their PCI device identifier, each unique PCI BDF (bus/bridge, device, 61function). Specific physical Crypto devices, like other physical devices in DPDK 62can be white-listed or black-listed using the EAL command line options. 63 64Virtual devices can be created by two mechanisms, either using the EAL command 65line options or from within the application using an EAL API directly. 66 67From the command line using the --vdev EAL option 68 69.. code-block:: console 70 71 --vdev 'cryptodev_aesni_mb_pmd0,max_nb_queue_pairs=2,max_nb_sessions=1024,socket_id=0' 72 73Our using the rte_vdev_init API within the application code. 74 75.. code-block:: c 76 77 rte_vdev_init("cryptodev_aesni_mb_pmd", 78 "max_nb_queue_pairs=2,max_nb_sessions=1024,socket_id=0") 79 80All virtual Crypto devices support the following initialization parameters: 81 82* ``max_nb_queue_pairs`` - maximum number of queue pairs supported by the device. 83* ``max_nb_sessions`` - maximum number of sessions supported by the device 84* ``socket_id`` - socket on which to allocate the device resources on. 85 86 87Device Identification 88~~~~~~~~~~~~~~~~~~~~~ 89 90Each device, whether virtual or physical is uniquely designated by two 91identifiers: 92 93- A unique device index used to designate the Crypto device in all functions 94 exported by the cryptodev API. 95 96- A device name used to designate the Crypto device in console messages, for 97 administration or debugging purposes. For ease of use, the port name includes 98 the port index. 99 100 101Device Configuration 102~~~~~~~~~~~~~~~~~~~~ 103 104The configuration of each Crypto device includes the following operations: 105 106- Allocation of resources, including hardware resources if a physical device. 107- Resetting the device into a well-known default state. 108- Initialization of statistics counters. 109 110The rte_cryptodev_configure API is used to configure a Crypto device. 111 112.. code-block:: c 113 114 int rte_cryptodev_configure(uint8_t dev_id, 115 struct rte_cryptodev_config *config) 116 117The ``rte_cryptodev_config`` structure is used to pass the configuration parameters. 118In contains parameter for socket selection, number of queue pairs and the 119session mempool configuration. 120 121.. code-block:: c 122 123 struct rte_cryptodev_config { 124 int socket_id; 125 /**< Socket to allocate resources on */ 126 uint16_t nb_queue_pairs; 127 /**< Number of queue pairs to configure on device */ 128 129 struct { 130 uint32_t nb_objs; 131 uint32_t cache_size; 132 } session_mp; 133 /**< Session mempool configuration */ 134 }; 135 136 137Configuration of Queue Pairs 138~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 139 140Each Crypto devices queue pair is individually configured through the 141``rte_cryptodev_queue_pair_setup`` API. 142Each queue pairs resources may be allocated on a specified socket. 143 144.. code-block:: c 145 146 int rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id, 147 const struct rte_cryptodev_qp_conf *qp_conf, 148 int socket_id) 149 150 struct rte_cryptodev_qp_conf { 151 uint32_t nb_descriptors; /**< Number of descriptors per queue pair */ 152 }; 153 154 155Logical Cores, Memory and Queues Pair Relationships 156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 157 158The Crypto device Library as the Poll Mode Driver library support NUMA for when 159a processor’s logical cores and interfaces utilize its local memory. Therefore 160Crypto operations, and in the case of symmetric Crypto operations, the session 161and the mbuf being operated on, should be allocated from memory pools created 162in the local memory. The buffers should, if possible, remain on the local 163processor to obtain the best performance results and buffer descriptors should 164be populated with mbufs allocated from a mempool allocated from local memory. 165 166The run-to-completion model also performs better, especially in the case of 167virtual Crypto devices, if the Crypto operation and session and data buffer is 168in local memory instead of a remote processor's memory. This is also true for 169the pipe-line model provided all logical cores used are located on the same 170processor. 171 172Multiple logical cores should never share the same queue pair for enqueuing 173operations or dequeuing operations on the same Crypto device since this would 174require global locks and hinder performance. It is however possible to use a 175different logical core to dequeue an operation on a queue pair from the logical 176core which it was enqueued on. This means that a crypto burst enqueue/dequeue 177APIs are a logical place to transition from one logical core to another in a 178packet processing pipeline. 179 180 181Device Features and Capabilities 182--------------------------------- 183 184Crypto devices define their functionality through two mechanisms, global device 185features and algorithm capabilities. Global devices features identify device 186wide level features which are applicable to the whole device such as 187the device having hardware acceleration or supporting symmetric Crypto 188operations, 189 190The capabilities mechanism defines the individual algorithms/functions which 191the device supports, such as a specific symmetric Crypto cipher, 192authentication operation or Authenticated Encryption with Associated Data 193(AEAD) operation. 194 195 196Device Features 197~~~~~~~~~~~~~~~ 198 199Currently the following Crypto device features are defined: 200 201* Symmetric Crypto operations 202* Asymmetric Crypto operations 203* Chaining of symmetric Crypto operations 204* SSE accelerated SIMD vector operations 205* AVX accelerated SIMD vector operations 206* AVX2 accelerated SIMD vector operations 207* AESNI accelerated instructions 208* Hardware off-load processing 209 210 211Device Operation Capabilities 212~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 213 214Crypto capabilities which identify particular algorithm which the Crypto PMD 215supports are defined by the operation type, the operation transform, the 216transform identifier and then the particulars of the transform. For the full 217scope of the Crypto capability see the definition of the structure in the 218*DPDK API Reference*. 219 220.. code-block:: c 221 222 struct rte_cryptodev_capabilities; 223 224Each Crypto poll mode driver defines its own private array of capabilities 225for the operations it supports. Below is an example of the capabilities for a 226PMD which supports the authentication algorithm SHA1_HMAC and the cipher 227algorithm AES_CBC. 228 229.. code-block:: c 230 231 static const struct rte_cryptodev_capabilities pmd_capabilities[] = { 232 { /* SHA1 HMAC */ 233 .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC, 234 .sym = { 235 .xform_type = RTE_CRYPTO_SYM_XFORM_AUTH, 236 .auth = { 237 .algo = RTE_CRYPTO_AUTH_SHA1_HMAC, 238 .block_size = 64, 239 .key_size = { 240 .min = 64, 241 .max = 64, 242 .increment = 0 243 }, 244 .digest_size = { 245 .min = 12, 246 .max = 12, 247 .increment = 0 248 }, 249 .aad_size = { 0 }, 250 .iv_size = { 0 } 251 } 252 } 253 }, 254 { /* AES CBC */ 255 .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC, 256 .sym = { 257 .xform_type = RTE_CRYPTO_SYM_XFORM_CIPHER, 258 .cipher = { 259 .algo = RTE_CRYPTO_CIPHER_AES_CBC, 260 .block_size = 16, 261 .key_size = { 262 .min = 16, 263 .max = 32, 264 .increment = 8 265 }, 266 .iv_size = { 267 .min = 16, 268 .max = 16, 269 .increment = 0 270 } 271 } 272 } 273 } 274 } 275 276 277Capabilities Discovery 278~~~~~~~~~~~~~~~~~~~~~~ 279 280Discovering the features and capabilities of a Crypto device poll mode driver 281is achieved through the ``rte_cryptodev_info_get`` function. 282 283.. code-block:: c 284 285 void rte_cryptodev_info_get(uint8_t dev_id, 286 struct rte_cryptodev_info *dev_info); 287 288This allows the user to query a specific Crypto PMD and get all the device 289features and capabilities. The ``rte_cryptodev_info`` structure contains all the 290relevant information for the device. 291 292.. code-block:: c 293 294 struct rte_cryptodev_info { 295 const char *driver_name; 296 enum rte_cryptodev_type dev_type; 297 struct rte_pci_device *pci_dev; 298 299 uint64_t feature_flags; 300 301 const struct rte_cryptodev_capabilities *capabilities; 302 303 unsigned max_nb_queue_pairs; 304 305 struct { 306 unsigned max_nb_sessions; 307 } sym; 308 }; 309 310 311Operation Processing 312-------------------- 313 314Scheduling of Crypto operations on DPDK's application data path is 315performed using a burst oriented asynchronous API set. A queue pair on a Crypto 316device accepts a burst of Crypto operations using enqueue burst API. On physical 317Crypto devices the enqueue burst API will place the operations to be processed 318on the devices hardware input queue, for virtual devices the processing of the 319Crypto operations is usually completed during the enqueue call to the Crypto 320device. The dequeue burst API will retrieve any processed operations available 321from the queue pair on the Crypto device, from physical devices this is usually 322directly from the devices processed queue, and for virtual device's from a 323``rte_ring`` where processed operations are place after being processed on the 324enqueue call. 325 326 327Enqueue / Dequeue Burst APIs 328~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 329 330The burst enqueue API uses a Crypto device identifier and a queue pair 331identifier to specify the Crypto device queue pair to schedule the processing on. 332The ``nb_ops`` parameter is the number of operations to process which are 333supplied in the ``ops`` array of ``rte_crypto_op`` structures. 334The enqueue function returns the number of operations it actually enqueued for 335processing, a return value equal to ``nb_ops`` means that all packets have been 336enqueued. 337 338.. code-block:: c 339 340 uint16_t rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id, 341 struct rte_crypto_op **ops, uint16_t nb_ops) 342 343The dequeue API uses the same format as the enqueue API of processed but 344the ``nb_ops`` and ``ops`` parameters are now used to specify the max processed 345operations the user wishes to retrieve and the location in which to store them. 346The API call returns the actual number of processed operations returned, this 347can never be larger than ``nb_ops``. 348 349.. code-block:: c 350 351 uint16_t rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id, 352 struct rte_crypto_op **ops, uint16_t nb_ops) 353 354 355Operation Representation 356~~~~~~~~~~~~~~~~~~~~~~~~ 357 358An Crypto operation is represented by an rte_crypto_op structure, which is a 359generic metadata container for all necessary information required for the 360Crypto operation to be processed on a particular Crypto device poll mode driver. 361 362.. figure:: img/crypto_op.* 363 364The operation structure includes the operation type, the operation status 365and the session type (session-based/less), a reference to the operation 366specific data, which can vary in size and content depending on the operation 367being provisioned. It also contains the source mempool for the operation, 368if it allocated from a mempool. 369 370If Crypto operations are allocated from a Crypto operation mempool, see next 371section, there is also the ability to allocate private memory with the 372operation for applications purposes. 373 374Application software is responsible for specifying all the operation specific 375fields in the ``rte_crypto_op`` structure which are then used by the Crypto PMD 376to process the requested operation. 377 378 379Operation Management and Allocation 380~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 381 382The cryptodev library provides an API set for managing Crypto operations which 383utilize the Mempool Library to allocate operation buffers. Therefore, it ensures 384that the crytpo operation is interleaved optimally across the channels and 385ranks for optimal processing. 386A ``rte_crypto_op`` contains a field indicating the pool that it originated from. 387When calling ``rte_crypto_op_free(op)``, the operation returns to its original pool. 388 389.. code-block:: c 390 391 extern struct rte_mempool * 392 rte_crypto_op_pool_create(const char *name, enum rte_crypto_op_type type, 393 unsigned nb_elts, unsigned cache_size, uint16_t priv_size, 394 int socket_id); 395 396During pool creation ``rte_crypto_op_init()`` is called as a constructor to 397initialize each Crypto operation which subsequently calls 398``__rte_crypto_op_reset()`` to configure any operation type specific fields based 399on the type parameter. 400 401 402``rte_crypto_op_alloc()`` and ``rte_crypto_op_bulk_alloc()`` are used to allocate 403Crypto operations of a specific type from a given Crypto operation mempool. 404``__rte_crypto_op_reset()`` is called on each operation before being returned to 405allocate to a user so the operation is always in a good known state before use 406by the application. 407 408.. code-block:: c 409 410 struct rte_crypto_op *rte_crypto_op_alloc(struct rte_mempool *mempool, 411 enum rte_crypto_op_type type) 412 413 unsigned rte_crypto_op_bulk_alloc(struct rte_mempool *mempool, 414 enum rte_crypto_op_type type, 415 struct rte_crypto_op **ops, uint16_t nb_ops) 416 417``rte_crypto_op_free()`` is called by the application to return an operation to 418its allocating pool. 419 420.. code-block:: c 421 422 void rte_crypto_op_free(struct rte_crypto_op *op) 423 424 425Symmetric Cryptography Support 426------------------------------ 427 428The cryptodev library currently provides support for the following symmetric 429Crypto operations; cipher, authentication, including chaining of these 430operations, as well as also supporting AEAD operations. 431 432 433Session and Session Management 434 435Session are used in symmetric cryptographic processing to store the immutable 436data defined in a cryptographic transform which is used in the operation 437processing of a packet flow. Sessions are used to manage information such as 438expand cipher keys and HMAC IPADs and OPADs, which need to be calculated for a 439particular Crypto operation, but are immutable on a packet to packet basis for 440a flow. Crypto sessions cache this immutable data in a optimal way for the 441underlying PMD and this allows further acceleration of the offload of 442Crypto workloads. 443 444.. figure:: img/cryptodev_sym_sess.* 445 446The Crypto device framework provides a set of session pool management APIs for 447the creation and freeing of the sessions, utilizing the Mempool Library. 448 449The framework also provides hooks so the PMDs can pass the amount of memory 450required for that PMDs private session parameters, as well as initialization 451functions for the configuration of the session parameters and freeing function 452so the PMD can managed the memory on destruction of a session. 453 454**Note**: Sessions created on a particular device can only be used on Crypto 455devices of the same type, and if you try to use a session on a device different 456to that on which it was created then the Crypto operation will fail. 457 458``rte_cryptodev_sym_session_create()`` is used to create a symmetric session on 459Crypto device. A symmetric transform chain is used to specify the particular 460operation and its parameters. See the section below for details on transforms. 461 462.. code-block:: c 463 464 struct rte_cryptodev_sym_session * rte_cryptodev_sym_session_create( 465 uint8_t dev_id, struct rte_crypto_sym_xform *xform); 466 467 468Transforms and Transform Chaining 469~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 470 471Symmetric Crypto transforms (``rte_crypto_sym_xform``) are the mechanism used 472to specify the details of the Crypto operation. For chaining of symmetric 473operations such as cipher encrypt and authentication generate, the next pointer 474allows transform to be chained together. Crypto devices which support chaining 475must publish the chaining of symmetric Crypto operations feature flag. 476 477Currently there are three transforms types cipher, authentication and AEAD. 478Also it is important to note that the order in which the 479transforms are passed indicates the order of the chaining. 480 481.. code-block:: c 482 483 struct rte_crypto_sym_xform { 484 struct rte_crypto_sym_xform *next; 485 /**< next xform in chain */ 486 enum rte_crypto_sym_xform_type type; 487 /**< xform type */ 488 union { 489 struct rte_crypto_auth_xform auth; 490 /**< Authentication / hash xform */ 491 struct rte_crypto_cipher_xform cipher; 492 /**< Cipher xform */ 493 struct rte_crypto_aead_xform aead; 494 /**< AEAD xform */ 495 }; 496 }; 497 498The API does not place a limit on the number of transforms that can be chained 499together but this will be limited by the underlying Crypto device poll mode 500driver which is processing the operation. 501 502.. figure:: img/crypto_xform_chain.* 503 504 505Symmetric Operations 506~~~~~~~~~~~~~~~~~~~~ 507 508The symmetric Crypto operation structure contains all the mutable data relating 509to performing symmetric cryptographic processing on a referenced mbuf data 510buffer. It is used for either cipher, authentication, AEAD and chained 511operations. 512 513As a minimum the symmetric operation must have a source data buffer (``m_src``), 514a valid session (or transform chain if in session-less mode) and the minimum 515authentication/ cipher/ AEAD parameters required depending on the type of operation 516specified in the session or the transform 517chain. 518 519.. code-block:: c 520 521 struct rte_crypto_sym_op { 522 struct rte_mbuf *m_src; 523 struct rte_mbuf *m_dst; 524 525 union { 526 struct rte_cryptodev_sym_session *session; 527 /**< Handle for the initialised session context */ 528 struct rte_crypto_sym_xform *xform; 529 /**< Session-less API Crypto operation parameters */ 530 }; 531 532 union { 533 struct { 534 struct { 535 uint32_t offset; 536 uint32_t length; 537 } data; /**< Data offsets and length for AEAD */ 538 539 struct { 540 uint8_t *data; 541 phys_addr_t phys_addr; 542 } digest; /**< Digest parameters */ 543 544 struct { 545 uint8_t *data; 546 phys_addr_t phys_addr; 547 } aad; 548 /**< Additional authentication parameters */ 549 } aead; 550 551 struct { 552 struct { 553 struct { 554 uint32_t offset; 555 uint32_t length; 556 } data; /**< Data offsets and length for ciphering */ 557 } cipher; 558 559 struct { 560 struct { 561 uint32_t offset; 562 uint32_t length; 563 } data; 564 /**< Data offsets and length for authentication */ 565 566 struct { 567 uint8_t *data; 568 phys_addr_t phys_addr; 569 } digest; /**< Digest parameters */ 570 571 struct { 572 uint8_t *data; 573 phys_addr_t phys_addr; 574 } aad; 575 /**< Additional authentication parameters */ 576 } auth; 577 }; 578 }; 579 }; 580 581 582Asymmetric Cryptography 583----------------------- 584 585Asymmetric functionality is currently not supported by the cryptodev API. 586 587 588Crypto Device API 589~~~~~~~~~~~~~~~~~ 590 591The cryptodev Library API is described in the *DPDK API Reference* document. 592