From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id 9A7902946 for ; Fri, 8 Apr 2016 18:07:32 +0200 (CEST) Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga101.jf.intel.com with ESMTP; 08 Apr 2016 09:05:41 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.24,454,1455004800"; d="scan'208";a="928391746" Received: from dwdohert-dpdk.ir.intel.com ([163.33.210.69]) by orsmga001.jf.intel.com with ESMTP; 08 Apr 2016 09:05:41 -0700 From: Declan Doherty To: dev@dpdk.org Cc: Declan Doherty Date: Fri, 8 Apr 2016 17:02:12 +0100 Message-Id: <1460131332-9847-1-git-send-email-declan.doherty@intel.com> X-Mailer: git-send-email 2.5.5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH] docs: cryptodev chapter for programmer's guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 08 Apr 2016 16:07:33 -0000 Signed-off-by: Declan Doherty --- doc/guides/cryptodevs/index.rst | 3 +- doc/guides/cryptodevs/overview.rst | 94 ++++ doc/guides/prog_guide/cryptodev_lib.rst | 569 +++++++++++++++++------ doc/guides/prog_guide/img/crypto_op.svg | 75 +++ doc/guides/prog_guide/img/crypto_xform_chain.svg | 145 ++++++ doc/guides/prog_guide/img/cryptodev_sym_sess.svg | 66 +++ 6 files changed, 798 insertions(+), 154 deletions(-) create mode 100644 doc/guides/cryptodevs/overview.rst create mode 100644 doc/guides/prog_guide/img/crypto_op.svg create mode 100644 doc/guides/prog_guide/img/crypto_xform_chain.svg create mode 100644 doc/guides/prog_guide/img/cryptodev_sym_sess.svg diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst index 85193da..a3f11f3 100644 --- a/doc/guides/cryptodevs/index.rst +++ b/doc/guides/cryptodevs/index.rst @@ -35,8 +35,9 @@ Crypto Device Drivers :maxdepth: 2 :numbered: + overview aesni_mb aesni_gcm null snow3g - qat + qat \ No newline at end of file diff --git a/doc/guides/cryptodevs/overview.rst b/doc/guides/cryptodevs/overview.rst new file mode 100644 index 0000000..9f9af43 --- /dev/null +++ b/doc/guides/cryptodevs/overview.rst @@ -0,0 +1,94 @@ +.. BSD LICENSE + Copyright(c) 2016 Intel Corporation. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Intel Corporation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Crypto Device Supported Functionality Matrices +---------------------------------------------- + +Supported Feature Flags + +.. csv-table:: + :header: "Feature Flags", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g" + :stub-columns: 1 + + "RTE_CRYPTODEV_FF_SYMMETRIC_CRYPTO",x,x,,, + "RTE_CRYPTODEV_FF_ASYMMETRIC_CRYPTO",,,,, + "RTE_CRYPTODEV_FF_SYM_OPERATION_CHAINING",x,x,x,x,x + "RTE_CRYPTODEV_FF_CPU_SSE",,,x,x,x + "RTE_CRYPTODEV_FF_CPU_AVX",,,x,x,x + "RTE_CRYPTODEV_FF_CPU_AVX2",,,x,x, + "RTE_CRYPTODEV_FF_CPU_AESNI",,,x,x, + "RTE_CRYPTODEV_FF_HW_ACCELERATED",x,,,, + +Supported Cipher Algorithms + +.. csv-table:: + :header: "Cipher Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g" + :stub-columns: 1 + + "NULL",,x,,, + "AES_CBC_128",x,,x,, + "AES_CBC_192",x,,x,, + "AES_CBC_256",x,,x,, + "AES_CTR_128",,,,, + "AES_CTR_192",,,,, + "AES_CTR_256",,,,, + "SNOW3G_UEA2",x,,,,x + +Supported Authentication Algorithms + +.. csv-table:: + :header: "Cipher Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g" + :stub-columns: 1 + + "NONE",,x,,, + "MD5",,,,, + "MD5_HMAC",,,x,, + "SHA1",,,,, + "SHA1_HMAC",x,,x,, + "SHA224",,,,, + "SHA224_HMAC",,,x,, + "SHA256",,,,, + "SHA256_HMAC",x,,x,, + "SHA384",,,,, + "SHA384_HMAC",,,x,, + "SHA512",,,,, + "SHA512_HMAC",x,,x,, + "AES_XCBC",x,,x,, + "SNOW3G_UIA2",x,,,,x + + +Supported AEAD Algorithms + +.. csv-table:: + :header: "AEAD Algorithms", "qat", "null", "aesni_mb", "aesni_gcm", "snow3g" + :stub-columns: 1 + + "AES_GCM_128",x,,x,, + "AES_GCM_192",x,,,, + "AES_GCM_256",x,,,, diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst index 638a02c..6396d02 100644 --- a/doc/guides/prog_guide/cryptodev_lib.rst +++ b/doc/guides/prog_guide/cryptodev_lib.rst @@ -31,291 +31,554 @@ Cryptography Device Library ============================= -The cryptodev library provides a crypto device framework for management and -provisioning of hardware and virtual crypto poll mode drivers, defining generic -APIs which support a number of different crypto operations. - - - - - -Requirements and Assumptions ----------------------------- - - - - +The cryptodev library provides a Crypto device framework for management and +provisioning of hardware and software Crypto poll mode drivers, defining generic +APIs which support a number of different Crypto operations. The framework +currently only supports cipher, authentication, chained cipher/authentication +and AEAD symmetric Crypto operations. Design Principles ----------------- +The cryptodev library follows the same basic principles as those used in DPDKs +Ethernet Device framework. The Crypto framework provides a generic Crypto device +framework which supports both physical (hardware) and virtual (software) Crypto +devices as well as a generic Crypto API which allows Crypto devices to be +managed and configured and supports Crypto operations to be provisioned on +Crypto poll mode driver. +Device Management +----------------- +Device Creation +~~~~~~~~~~~~~~~ +Physical Crypto devices are discovered during the PCI probe/enumeration of the +EAL function which is executed at DPDK initialization, based on +their PCI device identifier, each unique PCI BDF (bus/bridge, device, +function). Specific physical Crypto devices, like other physical devices in DPDK +can be white-listed or black-listed using the EAL command line options. -Logical Cores, Memory and Queues Pair Relationships ---------------------------------------------------- - -Crypto devices in the same vane as the :ref `Poll Mode Driver -` library supports NUMA for when a processor’s -logical cores and interfaces utilize its local memory. Therefore, crypto -operations, and in the case of symmetric crypto operations, session and the mbuf -being operated on, should be allocated from memory pools created in the local -memory. The buffers should, if possible, remain on the local processor to -obtain the best performance results and buffer descriptors should be populated - with mbufs allocated from a mempool allocated from local memory. - -The run-to-completion model also performs better, especially in the case of -virtual crypto devices, if the crypto operation and session and data buffer is -in local memory instead of a remote processors memory. This is also true for -the pipe-line model provided all logical cores used are located on the same -processor. - -Multiple logical cores should never share the same queue pairs for enqueuing or -dequeuing operations on the same Crypto device since this would require global -locks and hinder performance. It is however possible to use a different logical -core to enqueue and dequeue operation on a queue pair. - -Generalities -~~~~~~~~~~~~ - -By default, all functions exported by a PMD are lock-free functions that are -assumed not to be invoked in parallel on different logical cores to work on the -same target object. +Virtual devices can be created by two mechanisms, either using the EAL command +line options or from within the application using an EAL API directly. -For instance, a PMD dequeue burst function cannot be invoked in parallel on two -logical cores to poll the same queue pair of the same port. Of course, this -function can be invoked in parallel by different logical cores on different -queue pairs. +From the command line using the --vdev EAL option -It is the responsibility of the upper-level application to enforce this rule. +.. code-block:: console -If needed, parallel accesses by multiple logical cores to shared queues can be -explicitly protected by dedicated inline lock-aware functions built on top of -their corresponding lock-free functions of the PMD API. + --vdev 'cryptodev_aesni_mb_pmd0,max_nb_queue_pairs=2,max_nb_sessions=1024,socket_id=0' +Our using the rte_eal_vdev_init API within the application code. +.. code-block:: c -Device Identification and Configuration ---------------------------------------- + rte_eal_vdev_init("cryptodev_aesni_mb_pmd", + "max_nb_queue_pairs=2,max_nb_sessions=1024,socket_id=0") +All virtual Crypto devices support the following initialization parameters: +* max_nb_queue_pairs - maximum number of queue pairs supported by the device. +* max_nb_sessions - maximum number of sessions supported by the device +* socket_id - socket on which to allocate the device resources on. Device Identification ~~~~~~~~~~~~~~~~~~~~~ -Each crypto device, either virtual or physical is uniquely designated with a -device identifier. Physical crypto devices are discovered during the PCI -probe/enumeration function which is executed at DPDK initialization, based on -their PCI device identifier, each unique PCI BDF (bus/bridge, device, -function) for a matching identifier will be assigned a two device identifiers: - +Each device, whether virtual or physical is uniquely designated by two +identifiers: -- A device index used to designate the crypto device in all functions exported - by the cryptodev API. +- A unique device index used to designate the Crypto device in all functions + exported by the cryptodev API. -- A device name used to designate the crypto device in console messages, for +- A device name used to designate the Crypto device in console messages, for administration or debugging purposes. For ease of use, the port name includes the port index. -Virtual devices can be created by to mechanisms, firstly by using the EAL -command line, using the "--vdev" option or directly in an application by using -the rte_eal_vdev_init() API. Again virtual crypto devices will be assigned two -unique identifiers as list for physical crypto devices above. - -Device /Configuration -~~~~~~~~~~~~~~~~~~~~~ - -The configuration of each crypto device includes the following operations: - -- Allocate of hardware resources, if a physical device. -- Reset the device into a well-known default state. -- Initialize of statistics counters. - - -Device Initialization -~~~~~~~~~~~~~~~~~~~~~ - -Crypto devices support du - +Device Configuration +~~~~~~~~~~~~~~~~~~~~ +The configuration of each Crypto device includes the following operations: +- Allocation of resources, including hardware resources if a physical device. +- Resetting the device into a well-known default state. +- Initialization of statistics counters. +The rte_cryptodev_configure API is used to configure a Crypto device. +.. code-block:: c + int rte_cryptodev_configure(uint8_t dev_id, + struct rte_cryptodev_config *config) +The rte_cryptodev_config structure is used to pass the configuration parameters. +In contains parameter for socket selection, number of queue pairs and the +session mempool configuration. +.. code-block:: c + /** Crypto device configuration structure */ + struct rte_cryptodev_config { + int socket_id; + /**< Socket to allocate resources on */ + uint16_t nb_queue_pairs; + /**< Number of queue pairs to configure on device */ + struct { + uint32_t nb_objs; + uint32_t cache_size; + } session_mp; + /**< Session mempool configuration */ + }; Configuration of Queue Pairs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Each Crypto devices queue pair is individually configured through the +rte_cryptodev_queue_pair_setup API. Each queue pairs resources may be allocated +on a specified socket. +.. code-block:: c + int rte_cryptodev_queue_pair_setup(uint8_t dev_id, uint16_t queue_pair_id, + const struct rte_cryptodev_qp_conf *qp_conf, + int socket_id) + /** Crypto device queue pair configuration structure. */ + struct rte_cryptodev_qp_conf { + uint32_t nb_descriptors; /**< Number of descriptors per queue pair */ + }; +Logical Cores, Memory and Queues Pair Relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The Crypto device Library as the Poll Mode Driver library support NUMA for when +a processor’s logical cores and interfaces utilize its local memory. Therefore +Crypto operations, and in the case of symmetric Crypto operations, the session +and the mbuf being operated on, should be allocated from memory pools created +in the local memory. The buffers should, if possible, remain on the local +processor to obtain the best performance results and buffer descriptors should +be populated with mbufs allocated from a mempool allocated from local memory. +The run-to-completion model also performs better, especially in the case of +virtual Crypto devices, if the Crypto operation and session and data buffer is +in local memory instead of a remote processor's memory. This is also true for +the pipe-line model provided all logical cores used are located on the same +processor. -Device Capabilities -------------------- - -Crypto poll drivers - - - -Registering Device Capabilities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - +Multiple logical cores should never share the same queue pair for enqueuing +operations or dequeuing operations on the same Crypto device since this would +require global locks and hinder performance. It is however possible to use a +different logical core to dequeue an operation on a queue pair from the logical +core which it was enqueued on. This means that a crypto burst enqueue/dequeue +APIs are a logical place to transition from one logical core to another in a +packet processing pipeline. + +Device Features and Capabilities +--------------------------------- + +Crypto devices define their functionality through two mechanisms, global device +features and algorithm capabilities. Global devices features identify device +wide level features which are applicable to the whole device such as +the device having hardware acceleration or supporting symmetric Crypto +operations, + +The capabilities mechanism defines the individual algorithms/functions which +the device supports, such as a specific symmetric Crypto cipher or +authentication operation. + +Device Features +~~~~~~~~~~~~~~~ + +Currently the following Crypto device features are defined: + +* Symmetric Crypto operations +* Asymmetric Crypto operations +* Chaining of symmetric Crypto operations +* SSE accelerated SIMD vector operations +* AVX accelerated SIMD vector operations +* AVX2 accelerated SIMD vector operations +* AESNI accelerated instructions +* Hardware off-load processing + + +Device Operation Capabilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Crypto capabilities which identify particular algorithm which the Crypto PMD +supports are defined by the operation type, the operation transform, the +transform identifier and then the particulars of the transform. For the full +scope of the Crypto capability see the definition of the structure in the +*DPDK API Reference*. +.. code-block:: c + + struct rte_cryptodev_capabilities; + + +Each Crypto poll mode driver defines its own private array of capabilities +for the operations it supports. Below is an example of the capabilities for a +PMD which supports the authentication algorithm SHA1_HMAC and the cipher +algorithm AES_CBC. + +.. code-block:: c + + static const struct rte_cryptodev_capabilities pmd_capabilities[] = { + { /* SHA1 HMAC */ + .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC, + .sym = { + .xform_type = RTE_CRYPTO_SYM_XFORM_AUTH, + .auth = { + .algo = RTE_CRYPTO_AUTH_SHA1_HMAC, + .block_size = 64, + .key_size = { + .min = 64, + .max = 64, + .increment = 0 + }, + .digest_size = { + .min = 12, + .max = 12, + .increment = 0 + }, + .aad_size = { 0 } + } + } + }, + { /* AES CBC */ + .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC, + .sym = { + .xform_type = RTE_CRYPTO_SYM_XFORM_CIPHER, + .cipher = { + .algo = RTE_CRYPTO_CIPHER_AES_CBC, + .block_size = 16, + .key_size = { + .min = 16, + .max = 32, + .increment = 8 + }, + .iv_size = { + .min = 16, + .max = 16, + .increment = 0 + } + } + } + } + } Capabilities Discovery ~~~~~~~~~~~~~~~~~~~~~~ +Discovering the features and capabilities of a Crypto device poll mode driver +is achieved through the rte_cryptodev_info_get function. +.. code-block:: c + void rte_cryptodev_info_get(uint8_t dev_id, + struct rte_cryptodev_info *dev_info); -Operation Processing --------------------- - - - - -Operation Representation -~~~~~~~~~~~~~~~~~~~~~~~~ - -An crypto operation is represented by an rte_crypto_op structure, which is a -generic metadata structure containing all necessary housekeeping information -for the operation which the PMD is to process. - -This includes the operation type and the operation status, a pointer to the -operation specific data, as well as the source mempool for the operation and a -opaque pointer for user specific data. - -The rte_crypto_op data structure and the under lying operation specific data -fields are represented, in a generic way, to allow provision of the requested -operation by crypto accelerator device. - -Application software is responsible for specifying all the operation specific -fields the rte_crypto_op structure which are used by the crypto PMD to process -the requested operation. Processed operation return - - -Operation Management and Allocation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This allows the user to query a specific Crypto PMD and get all the device +features and capabilities. The rte_cryptodev_info structure contains all the +relevant information for the device. +.. code-block:: c + /** Crypto device information */ + struct rte_cryptodev_info { + const char *driver_name; /**< Driver name. */ + enum rte_cryptodev_type dev_type; /**< Device type */ + struct rte_pci_device *pci_dev; /**< PCI information. */ + uint64_t feature_flags; /**< Feature flags */ + const struct rte_cryptodev_capabilities *capabilities; + /**< Array of devices supported capabilities */ + unsigned max_nb_queue_pairs; + /**< Maximum number of queues pairs supported by device. */ - - -Enqueue / Dequeue Burst API -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - + struct { + unsigned max_nb_sessions; + /**< Maximum number of sessions supported by device. */ + } sym; + }; +Operation Processing +-------------------- +Scheduling of Crypto operations on DPDK's application data path is +performed using a burst oriented asynchronous API set. A queue pair on a Crypto +device accepts a burst of Crypto operations using enqueue burst API. On physical +Crypto devices the enqueue burst API will place the operations to be processed +on the devices hardware input queue, for virtual devices the processing of the +Crypto operations is usually completed during the enqueue call to the Crypto +device. The dequeue burst API will retrieve any processed operations available +from the queue pair on the Crypto device, from physical devices this is usually +directly from the devices processed queue, and for virtual device's from a +rte_ring where processed operations are place after being processed on the +enqueue call. + +Enqueue / Dequeue Burst APIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The burst enqueue API uses a Crypto device identifier and a queue pair +identifier to specify the Crypto device queue pair to schedule the processing +on. The *nb_ops* parameter is the number of operations to process which are +supplied in the *ops* array of *rte_crypto_op* structures. The enqueue function +returns the number of operations it actually enqueued for processing, a return +value equal to *nb_ops* means that all packets have been enqueued. -Symmetric Cryptography Support ------------------------------- +.. code-block:: c -Symmetric crypto transforms currently support are cipher transforms and authentication. + uint16_t rte_cryptodev_enqueue_burst(uint8_t dev_id, uint16_t qp_id, + struct rte_crypto_op **ops, uint16_t nb_ops) +The dequeue API uses the same format as the enqueue API of processed but +the *nb_ops* and *ops* parameters are now used to specify the max processed +operations the user wishes to retrieve and the location in which to store them. +The API call returns the actual number of processed operations returned, this +can never be larger than *nb_ops*. +.. code-block:: c + uint16_t rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id, + struct rte_crypto_op **ops, uint16_t nb_ops) +Operation Representation +~~~~~~~~~~~~~~~~~~~~~~~~ +An Crypto operation is represented by an rte_crypto_op structure, which is a +generic metadata container for all necessary information required for the +Crypto operation to be processed on a particular Crypto device poll mode driver. +.. figure:: img/crypto_op.* -Transforms -~~~~~~~~~~ +The operation structure includes the operation type and the operation status, +a reference to the operation specific data, which can vary in size and content +depending on the operation being provisioned. It also contains the source +mempool for the operation, if it allocate from a mempool. Finally an +opaque pointer for user specific data is provided. +If Crypto operations are allocated from a Crypto operation mempool, see next +section, there is also the ability to allocate private memory with the +operation for applications purposes. +Application software is responsible for specifying all the operation specific +fields in the rte_crypto_op structure which are then used by the Crypto PMD to +process the requested operation. +Operation Management and Allocation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The cryptodev library provides an API set for managing Crypto operations which +utilize the Mempool Library to allocate operation buffers. Therefore, it ensures +that the crytpo operation is interleaved optimally across the channels and +ranks for optimal processing. A rte_crypto_op contains a field indicating the +pool that it originated from. When calling rte_crypto_op_free(op), the +operation returns to its original pool. +.. code-block:: c + extern struct rte_mempool * + rte_crypto_op_pool_create(const char *name, enum rte_crypto_op_type type, + unsigned nb_elts, unsigned cache_size, uint16_t priv_size, + int socket_id); +During pool creation rte_crypto_op_init() is called as a constructor to +initialize each Crypto operation which subsequently calls +__rte_crypto_op_reset() to configure any operation type specific fields based +on the type parameter. +rte_crypto_op_alloc() and rte_crypto_op_bulk_alloc() are used to allocate Crypto +operations of a specific type from a given Crypto operation mempool. +__rte_crypto_op_reset() is called on each operation before being returned to +allocate to a user so the operation is always in a good known state before use +by the application. +.. code-block:: c + struct rte_crypto_op *rte_crypto_op_alloc(struct rte_mempool *mempool, + enum rte_crypto_op_type type) + unsigned rte_crypto_op_bulk_alloc(struct rte_mempool *mempool, + enum rte_crypto_op_type type, + struct rte_crypto_op **ops, uint16_t nb_ops) -Transform Chaining -~~~~~~~~~~~~~~~~~~ +rte_crypto_op_free() is called by the application to return an operation to it's +allocating pool. -Transform chaining allows multiple transforms to be processed in one -cryptographic operation. The two most common chaining combinations are -authentication verify then cipher decryption and cipher encryption and -authentication generate. The API does not place a limit on the number of -transforms that can be chained together but this will be limited by the -underlying Crypto device which is processing the operation. +.. code-block:: c + void rte_crypto_op_free(struct rte_crypto_op *op) +Symmetric Cryptography Support +------------------------------ +The cryptodev library currently provides support for the following symmetric +Crypto operations; cipher, authentication, including chaining of these +operations, as well as also supporting AEAD operations. +Session and Session Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Session are used in symmetric cryptographic processing to store the immutable +data defined in a cryptographic transform which is used in the operation +processing of a packet flow. Sessions are used to manage information such as +expand cipher keys and HMAC IPADs and OPADs, which need to be calculated for a +particular Crypto operation, but are immutable on a packet to packet basis for +a flow. Crypto sessions cache this immutable data in a optimal way for the +underlying PMD and this allows further acceleration of the offload of +Crypto workloads. +.. figure:: img/cryptodev_sym_sess.* +The Crypto device framework provides a set of session pool management APIs for +the creation and freeing of the sessions, utilizing the Mempool Library. +The framework also provides hooks so the PMDs can pass the amount of memory +required for that PMDs private session parameters, as well as initialization +functions for the configuration of the session parameters and freeing function +so the PMD can managed the memory on destruction of a session. +**Note**: Sessions created on a particular device can only be used on Crypto +devices of the same type, and if you try to use a session on a device different +to that on which it was created then the Crypto operation will fail. -Session and Session Management -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +rte_cryptodev_sym_session_create() is used to create a symmetric session on +Crypto device. A symmetric transform chain is used to specify the particular +operation and it's parameters. See the section below for details on transforms. -Session are used in symmetric cryptographic processing to store the immutable -data defined in a cryptographic transform which is used in the operation -processing of a packet flow. In the DPDK cryptodev implementation the session -structure fulfills two main purposes, +.. code-block:: c + struct rte_cryptodev_sym_session * rte_cryptodev_sym_session_create( + uint8_t dev_id, struct rte_crypto_sym_xform *xform); +**Note**: For AEAD operations the algorithm selected for authentication and +ciphering must aligned, eg AES_GCM. +Transforms and Transform Chaining +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Symmetric Crypto transforms (rte_crypto_sym_xform) are the mechanism used to +specify the details of the Crypto operation. For chaining of symmetric +operations such as cipher encrypt and authentication generate, the next pointer +allows transform to be chained together. Crypto devices which support chaining +must publish the chaining of symmetric Crypto operations feature flag. +Currently there are two transforms types cipher and authentication, to specify +an AEAD operation it is required to chain a cipher and an authentication +transform together. Also it is important to note that the order in which the +transforms are passed indicates the order of the chaining. +.. code-block:: c + struct rte_crypto_sym_xform { + struct rte_crypto_sym_xform *next; + /**< next xform in chain */ + enum rte_crypto_sym_xform_type type + ; /**< xform type */ + union { + struct rte_crypto_auth_xform auth; + /**< Authentication / hash xform */ + struct rte_crypto_cipher_xform cipher; + /**< Cipher xform */ + }; + }; +The API does not place a limit on the number of transforms that can be chained +together but this will be limited by the underlying Crypto device poll mode +driver which is processing the operation. +.. figure:: img/crypto_xform_chain.* Symmetric Operations ~~~~~~~~~~~~~~~~~~~~ -Symmetric cryptographic functions are provided by c - - - +The symmetric Crypto operation structure contains all the mutable data relating +to performing symmetric cryptographic processing on a referenced mbuf data +buffer. It is used for either cipher, authentication, AEAD and chained +operations. + +As a minimum the symmetric operation must have a source data buffer (m_src), +the session type (session-based/less), a valid session (or transform chain if in +session-less mode) and the minimum authentication/ cipher parameters required +depending on the type of operation specified in the session or the transform +chain. + +.. code-block:: c + + struct rte_crypto_sym_op { + struct rte_mbuf *m_src; /**< source mbuf */ + struct rte_mbuf *m_dst; /**< destination mbuf */ + + enum rte_crypto_sym_op_sess_type type; + + union { + struct rte_cryptodev_sym_session *session; + /**< Handle for the initialised session context */ + struct rte_crypto_sym_xform *xform; + /**< Session-less API Crypto operation parameters */ + }; + + struct { + struct { + uint32_t offset; + uint32_t length; + } data; /**< Data offsets and length for ciphering */ + + struct { + uint8_t *data; + phys_addr_t phys_addr; + uint16_t length; + } iv; /**< Initialisation vector parameters */ + } cipher; + + struct { + struct { + uint32_t offset; + uint32_t length; + } data; /**< Data offsets and length for authentication */ + + struct { + uint8_t *data; + phys_addr_t phys_addr; + uint16_t length; + } digest; /**< Digest parameters */ + + struct { + uint8_t *data; + phys_addr_t phys_addr; + uint16_t length; + } aad; + /**< Additional authentication parameters */ + } auth; + } Asymmetric Cryptography ----------------------- -Asymmetric functionality is currently not supported by the cryptodev API but is -expected to be added in the near future. +Asymmetric functionality is currently not supported by the cryptodev API. Crypto Device API ~~~~~~~~~~~~~~~~~~~ -The Ethernet device API exported by the Ethernet PMDs is described in the -*DPDK API Reference*. +The cryptodev Library API is described in the *DPDK API Reference* document. diff --git a/doc/guides/prog_guide/img/crypto_op.svg b/doc/guides/prog_guide/img/crypto_op.svg new file mode 100644 index 0000000..96e3aff --- /dev/null +++ b/doc/guides/prog_guide/img/crypto_op.svg @@ -0,0 +1,75 @@ + + + + + + + + + + + + + + + + + + + + Page-1 + + Rounded Rectangle.24 + Crypto Operation + + Crypto Operation + + Rounded Rectangle.7 + Operation Specific Data (struct rte_crypto_sym_op) + + Operation Specific Data (struct rte_crypto_sym_op) + + Rounded Rectangle.8 + private data + + + + + private data + + Rounded Rectangle.9 + General Operation Data (struct rte_crypto_op) + + General Operation Data (struct rte_crypto_op) + + diff --git a/doc/guides/prog_guide/img/crypto_xform_chain.svg b/doc/guides/prog_guide/img/crypto_xform_chain.svg new file mode 100644 index 0000000..4670a07 --- /dev/null +++ b/doc/guides/prog_guide/img/crypto_xform_chain.svg @@ -0,0 +1,145 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + Rounded Rectangle.24 + Symmetric Transform (struct rte_crypto_sym_xform) + + Symmetric Transform (struct rte_crypto_sym_xform) + + Rounded Rectangle.25 + Transform Parameters struct rte_crypto_auth_xform struct rte_... + + + + + Transform Parameters struct rte_crypto_auth_xform struct rte_crypto_cipher_xform + + Rounded Rectangle.26 + next transform (struct rte_crypto_sym_xform *) + + next transform (struct rte_crypto_sym_xform *) + + Rounded Rectangle.29 + transform type (enum rte_crypto_sym_xform_type) + + transform type (enum rte_crypto_sym_xform_type) + + Rounded Rectangle.30 + Symmetric Transform (struct rte_crypto_sym_xform) + + Symmetric Transform (struct rte_crypto_sym_xform) + + Rounded Rectangle.31 + Transform Parameters struct rte_crypto_auth_xform struct rte_... + + + + + Transform Parameters struct rte_crypto_auth_xform struct rte_crypto_cipher_xform + + Rounded Rectangle.32 + next transform (struct rte_crypto_sym_xform *) + + next transform (struct rte_crypto_sym_xform *) + + Rounded Rectangle.33 + transform type (enum rte_crypto_sym_xform_type) + + transform type (enum rte_crypto_sym_xform_type) + + Dynamic connector + + + + diff --git a/doc/guides/prog_guide/img/cryptodev_sym_sess.svg b/doc/guides/prog_guide/img/cryptodev_sym_sess.svg new file mode 100644 index 0000000..e5f41ec --- /dev/null +++ b/doc/guides/prog_guide/img/cryptodev_sym_sess.svg @@ -0,0 +1,66 @@ + + + + + + + + + + + + + + + + + + + + Page-1 + + Rounded Rectangle.12 + Crypto Symmetric Session + + Crypto Symmetric Session + + Rounded Rectangle.13 + Private Session Data + + + + + Private Session Data + + Rounded Rectangle.15 + General Session Data (struct rte_cryptodev_sym_session) + + General Session Data (struct rte_cryptodev_sym_session) + + -- 2.5.5