From mboxrd@z Thu Jan 1 00:00:00 1970 From: Declan Doherty Subject: [PATCH] docs: cryptodev chapter for programmer's guide Date: Fri, 8 Apr 2016 17:02:12 +0100 Message-ID: <1460131332-9847-1-git-send-email-declan.doherty@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Cc: Declan Doherty To: dev@dpdk.org 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) List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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/inde= x.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: =20 + 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/o= verview.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 FO= R + 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 AN= Y + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E + 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", "sn= ow3g" + :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_gu= ide/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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D =20 -The cryptodev library provides a crypto device framework for management = and=20 -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 framewor= k +currently only supports cipher, authentication, chained cipher/authentic= ation +and AEAD symmetric Crypto operations. =20 =20 Design Principles ----------------- =20 +The cryptodev library follows the same basic principles as those used in= DPDKs +Ethernet Device framework. The Crypto framework provides a generic Crypt= o device +framework which supports both physical (hardware) and virtual (software)= Crypto +devices as well as a generic Crypto API which allows Crypto devices to b= e +managed and configured and supports Crypto operations to be provisioned = on +Crypto poll mode driver. =20 =20 +Device Management +----------------- =20 +Device Creation +~~~~~~~~~~~~~~~ =20 +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. =20 -Logical Cores, Memory and Queues Pair Relationships ---------------------------------------------------- - -Crypto devices in the same vane as the :ref `Poll Mode Driver=20 -` library supports NUMA for when a processor=E2=80=99s= =20 -logical cores and interfaces utilize its local memory. Therefore, crypto= =20 -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 t= o -obtain the best performance results and buffer descriptors should be pop= ulated - 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 buf= fer 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 s= ame -processor. - -Multiple logical cores should never share the same queue pairs for enque= uing 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 c= ommand +line options or from within the application using an EAL API directly. =20 -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, t= his -function can be invoked in parallel by different logical cores on differ= ent -queue pairs. +From the command line using the --vdev EAL option =20 -It is the responsibility of the upper-level application to enforce this = rule. +.. code-block:: console =20 -If needed, parallel accesses by multiple logical cores to shared queues = can be -explicitly protected by dedicated inline lock-aware functions built on t= op of -their corresponding lock-free functions of the PMD API. + --vdev 'cryptodev_aesni_mb_pmd0,max_nb_queue_pairs=3D2,max_nb_sessions= =3D1024,socket_id=3D0' =20 +Our using the rte_eal_vdev_init API within the application code. =20 +.. code-block:: c =20 -Device Identification and Configuration ---------------------------------------- + rte_eal_vdev_init("cryptodev_aesni_mb_pmd", + "max_nb_queue_pairs=3D2,max_nb_sessions=3D1024,socket_id=3D0") =20 +All virtual Crypto devices support the following initialization paramete= rs: =20 +* max_nb_queue_pairs - maximum number of queue pairs supported by the de= vice. +* max_nb_sessions - maximum number of sessions supported by the device +* socket_id - socket on which to allocate the device resources on. =20 =20 Device Identification ~~~~~~~~~~~~~~~~~~~~~ =20 -Each crypto device, either virtual or physical is uniquely designated wi= th a -device identifier. Physical crypto devices are discovered during the PCI -probe/enumeration function which is executed at DPDK initialization, bas= ed on -their PCI device identifier, each unique PCI BDF (bus/bridge, device,=20 -function) for a matching identifier will be assigned a two device identi= fiers: - +Each device, whether virtual or physical is uniquely designated by two +identifiers: =20 -- A device index used to designate the crypto device in all functions ex= ported - by the cryptodev API. +- A unique device index used to designate the Crypto device in all funct= ions + exported by the cryptodev API. =20 -- 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 i= ncludes the port index. =20 -Virtual devices can be created by to mechanisms, firstly by using the EA= L -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 assign= ed two -unique identifiers as list for physical crypto devices above.=20 - -Device /Configuration -~~~~~~~~~~~~~~~~~~~~~ - -The configuration of each crypto device includes the following operation= s: - -- 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 +~~~~~~~~~~~~~~~~~~~~ =20 +The configuration of each Crypto device includes the following operation= s: =20 +- Allocation of resources, including hardware resources if a physical de= vice. +- Resetting the device into a well-known default state. +- Initialization of statistics counters. =20 =20 +The rte_cryptodev_configure API is used to configure a Crypto device. =20 +.. code-block:: c =20 + int rte_cryptodev_configure(uint8_t dev_id, + struct rte_cryptodev_config *config) =20 +The rte_cryptodev_config structure is used to pass the configuration par= ameters. +In contains parameter for socket selection, number of queue pairs and th= e +session mempool configuration. =20 +.. code-block:: c =20 + /** 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 */ =20 + struct { + uint32_t nb_objs; + uint32_t cache_size; + } session_mp; + /**< Session mempool configuration */ + }; =20 =20 Configuration of Queue Pairs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 +Each Crypto devices queue pair is individually configured through the +rte_cryptodev_queue_pair_setup API. Each queue pairs resources may be al= located +on a specified socket. =20 +.. code-block:: c =20 + 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) =20 + /** Crypto device queue pair configuration structure. */ + struct rte_cryptodev_qp_conf { + uint32_t nb_descriptors; /**< Number of descriptors per queue pair */ + }; =20 +Logical Cores, Memory and Queues Pair Relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 +The Crypto device Library as the Poll Mode Driver library support NUMA f= or when +a processor=E2=80=99s logical cores and interfaces utilize its local mem= ory. Therefore +Crypto operations, and in the case of symmetric Crypto operations, the s= ession +and the mbuf being operated on, should be allocated from memory pools cr= eated +in the local memory. The buffers should, if possible, remain on the loca= l +processor to obtain the best performance results and buffer descriptors = should +be populated with mbufs allocated from a mempool allocated from local me= mory. =20 +The run-to-completion model also performs better, especially in the case= of +virtual Crypto devices, if the Crypto operation and session and data buf= fer is +in local memory instead of a remote processor's memory. This is also tru= e for +the pipe-line model provided all logical cores used are located on the s= ame +processor. =20 -Device Capabilities -------------------- - -Crypto poll drivers -=20 -=20 - -Registering Device Capabilities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - +Multiple logical cores should never share the same queue pair for enqueu= ing +operations or dequeuing operations on the same Crypto device since this = would +require global locks and hinder performance. It is however possible to u= se 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/de= queue +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 de= vice +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 w= hich +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, th= e +transform identifier and then the particulars of the transform. For the = full +scope of the Crypto capability see the definition of the structure in th= e +*DPDK API Reference*. =20 +.. code-block:: c + + struct rte_cryptodev_capabilities; + + +Each Crypto poll mode driver defines its own private array of capabiliti= es +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[] =3D { + { /* SHA1 HMAC */ + .op =3D RTE_CRYPTO_OP_TYPE_SYMMETRIC, + .sym =3D { + .xform_type =3D RTE_CRYPTO_SYM_XFORM_AUTH, + .auth =3D { + .algo =3D RTE_CRYPTO_AUTH_SHA1_HMAC, + .block_size =3D 64, + .key_size =3D { + .min =3D 64, + .max =3D 64, + .increment =3D 0 + }, + .digest_size =3D { + .min =3D 12, + .max =3D 12, + .increment =3D 0 + }, + .aad_size =3D { 0 } + } + } + }, + { /* AES CBC */ + .op =3D RTE_CRYPTO_OP_TYPE_SYMMETRIC, + .sym =3D { + .xform_type =3D RTE_CRYPTO_SYM_XFORM_CIPHER, + .cipher =3D { + .algo =3D RTE_CRYPTO_CIPHER_AES_CBC, + .block_size =3D 16, + .key_size =3D { + .min =3D 16, + .max =3D 32, + .increment =3D 8 + }, + .iv_size =3D { + .min =3D 16, + .max =3D 16, + .increment =3D 0 + } + } + } + } + } =20 =20 Capabilities Discovery ~~~~~~~~~~~~~~~~~~~~~~ =20 +Discovering the features and capabilities of a Crypto device poll mode d= river +is achieved through the rte_cryptodev_info_get function. =20 +.. code-block:: c =20 + void rte_cryptodev_info_get(uint8_t dev_id, + struct rte_cryptodev_info *dev_info); =20 -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 informa= tion -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.=20 - -The rte_crypto_op data structure and the under lying operation specific = data=20 -fields are represented, in a generic way, to allow provision of the requ= ested -operation by crypto accelerator device. - -Application software is responsible for specifying all the operation spe= cific -fields the rte_crypto_op structure which are used by the crypto PMD to p= rocess -the requested operation. Processed operation return - - -Operation Management and Allocation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This allows the user to query a specific Crypto PMD and get all the devi= ce +features and capabilities. The rte_cryptodev_info structure contains all= the +relevant information for the device. =20 +.. code-block:: c =20 + /** 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. */ =20 + uint64_t feature_flags; /**< Feature flags */ =20 + const struct rte_cryptodev_capabilities *capabilities; + /**< Array of devices supported capabilities */ =20 + unsigned max_nb_queue_pairs; + /**< Maximum number of queues pairs supported by device. */ =20 - - -Enqueue / Dequeue Burst API -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - + struct { + unsigned max_nb_sessions; + /**< Maximum number of sessions supported by device. */ + } sym; + }; =20 =20 =20 +Operation Processing +-------------------- =20 +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 pro= cessed +on the devices hardware input queue, for virtual devices the processing = of the +Crypto operations is usually completed during the enqueue call to the Cr= ypto +device. The dequeue burst API will retrieve any processed operations ava= ilable +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 t= he +enqueue call. + +Enqueue / Dequeue Burst APIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 +The burst enqueue API uses a Crypto device identifier and a queue pair +identifier to specify the Crypto device queue pair to schedule the proce= ssing +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 f= unction +returns the number of operations it actually enqueued for processing, a = return +value equal to *nb_ops* means that all packets have been enqueued. =20 -Symmetric Cryptography Support ------------------------------- +.. code-block:: c =20 -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) =20 +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 proces= sed +operations the user wishes to retrieve and the location in which to stor= e them. +The API call returns the actual number of processed operations returned,= this +can never be larger than *nb_ops*. =20 +.. code-block:: c =20 + uint16_t rte_cryptodev_dequeue_burst(uint8_t dev_id, uint16_t qp_id, + struct rte_crypto_op **ops, uint16_t nb_ops) =20 +Operation Representation +~~~~~~~~~~~~~~~~~~~~~~~~ =20 +An Crypto operation is represented by an rte_crypto_op structure, which = is a +generic metadata container for all necessary information required for th= e +Crypto operation to be processed on a particular Crypto device poll mode= driver. =20 +.. figure:: img/crypto_op.* =20 -Transforms -~~~~~~~~~~ +The operation structure includes the operation type and the operation st= atus, +a reference to the operation specific data, which can vary in size and c= ontent +depending on the operation being provisioned. It also contains the sourc= e +mempool for the operation, if it allocate from a mempool. Finally an +opaque pointer for user specific data is provided. =20 +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. =20 +Application software is responsible for specifying all the operation spe= cific +fields in the rte_crypto_op structure which are then used by the Crypto = PMD to +process the requested operation. =20 =20 +Operation Management and Allocation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 +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 a= nd +ranks for optimal processing. A rte_crypto_op contains a field indicatin= g the +pool that it originated from. When calling rte_crypto_op_free(op), the +operation returns to its original pool. =20 +.. code-block:: c =20 + extern struct rte_mempool * + rte_crypto_op_pool_create(const char *name, enum rte_crypto_op_type typ= e, + unsigned nb_elts, unsigned cache_size, uint16_t priv_size, + int socket_id); =20 +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. =20 =20 +rte_crypto_op_alloc() and rte_crypto_op_bulk_alloc() are used to allocat= e Crypto +operations of a specific type from a given Crypto operation mempool. +__rte_crypto_op_reset() is called on each operation before being returne= d to +allocate to a user so the operation is always in a good known state befo= re use +by the application. =20 +.. code-block:: c =20 + struct rte_crypto_op *rte_crypto_op_alloc(struct rte_mempool *mempool, + enum rte_crypto_op_type type) =20 + 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) =20 -Transform Chaining -~~~~~~~~~~~~~~~~~~ +rte_crypto_op_free() is called by the application to return an operation= to it's +allocating pool. =20 -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 =20 + void rte_crypto_op_free(struct rte_crypto_op *op) =20 =20 +Symmetric Cryptography Support +------------------------------ =20 +The cryptodev library currently provides support for the following symme= tric +Crypto operations; cipher, authentication, including chaining of these +operations, as well as also supporting AEAD operations. =20 =20 +Session and Session Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 +Session are used in symmetric cryptographic processing to store the immu= table +data defined in a cryptographic transform which is used in the operation +processing of a packet flow. Sessions are used to manage information suc= h 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 bas= is for +a flow. Crypto sessions cache this immutable data in a optimal way for t= he +underlying PMD and this allows further acceleration of the offload of +Crypto workloads. =20 +.. figure:: img/cryptodev_sym_sess.* =20 +The Crypto device framework provides a set of session pool management AP= Is for +the creation and freeing of the sessions, utilizing the Mempool Library. =20 +The framework also provides hooks so the PMDs can pass the amount of mem= ory +required for that PMDs private session parameters, as well as initializa= tion +functions for the configuration of the session parameters and freeing fu= nction +so the PMD can managed the memory on destruction of a session. =20 +**Note**: Sessions created on a particular device can only be used on Cr= ypto +devices of the same type, and if you try to use a session on a device di= fferent +to that on which it was created then the Crypto operation will fail. =20 -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 partic= ular +operation and it's parameters. See the section below for details on tran= sforms. =20 -Session are used in symmetric cryptographic processing to store the immu= table -data defined in a cryptographic transform which is used in the operation= =20 -processing of a packet flow. In the DPDK cryptodev implementation the se= ssion -structure fulfills two main purposes, =20 +.. code-block:: c =20 + struct rte_cryptodev_sym_session * rte_cryptodev_sym_session_create( + uint8_t dev_id, struct rte_crypto_sym_xform *xform); =20 +**Note**: For AEAD operations the algorithm selected for authentication = and +ciphering must aligned, eg AES_GCM. =20 +Transforms and Transform Chaining +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 +Symmetric Crypto transforms (rte_crypto_sym_xform) are the mechanism use= d 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 ch= aining +must publish the chaining of symmetric Crypto operations feature flag. =20 =20 +Currently there are two transforms types cipher and authentication, to s= pecify +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. =20 +.. code-block:: c =20 + 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 */ + }; + }; =20 +The API does not place a limit on the number of transforms that can be c= hained +together but this will be limited by the underlying Crypto device poll m= ode +driver which is processing the operation. =20 +.. figure:: img/crypto_xform_chain.* =20 =20 Symmetric Operations ~~~~~~~~~~~~~~~~~~~~ =20 -Symmetric cryptographic functions are provided by c=20 - -=20 - +The symmetric Crypto operation structure contains all the mutable data r= elating +to performing symmetric cryptographic processing on a referenced mbuf da= ta +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_s= rc), +the session type (session-based/less), a valid session (or transform cha= in if in +session-less mode) and the minimum authentication/ cipher parameters req= uired +depending on the type of operation specified in the session or the trans= form +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; + } =20 =20 Asymmetric Cryptography ----------------------- =20 -Asymmetric functionality is currently not supported by the cryptodev API= but is -expected to be added in the near future.=20 +Asymmetric functionality is currently not supported by the cryptodev API= . =20 =20 =20 Crypto Device API ~~~~~~~~~~~~~~~~~~~ =20 -The Ethernet device API exported by the Ethernet PMDs is described in th= e -*DPDK API Reference*. +The cryptodev Library API is described in the *DPDK API Reference* docum= ent. =20 =20 diff --git a/doc/guides/prog_guide/img/crypto_op.svg b/doc/guides/prog_gu= ide/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 <= /g> + + 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 <= tspan x=3D"31.23" dy=3D"1.5em" class=3D"st5">(struct rte_crypto_op) + + diff --git a/doc/guides/prog_guide/img/crypto_xform_chain.svg b/doc/guide= s/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 r= te_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 r= te_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/guide= s/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) + + --=20 2.5.5