From patchwork Fri Sep 6 13:13:30 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Fan Zhang X-Patchwork-Id: 58872 X-Patchwork-Delegate: gakhil@marvell.com Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 1F6BE1F3D9; Fri, 6 Sep 2019 15:14:11 +0200 (CEST) Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id 2048D1F3A3 for ; Fri, 6 Sep 2019 15:13:51 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 06 Sep 2019 06:13:51 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.64,473,1559545200"; d="scan'208";a="213140808" Received: from silpixa00398673.ir.intel.com (HELO silpixa00398673.ger.corp.intel.com) ([10.237.223.136]) by fmsmga002.fm.intel.com with ESMTP; 06 Sep 2019 06:13:49 -0700 From: Fan Zhang To: dev@dpdk.org Cc: konstantin.ananyev@intel.com, declan.doherty@intel.com, akhil.goyal@nxp.com, Fan Zhang Date: Fri, 6 Sep 2019 14:13:30 +0100 Message-Id: <20190906131330.40185-11-roy.fan.zhang@intel.com> X-Mailer: git-send-email 2.14.5 In-Reply-To: <20190906131330.40185-1-roy.fan.zhang@intel.com> References: <20190903154046.55992-1-roy.fan.zhang@intel.com> <20190906131330.40185-1-roy.fan.zhang@intel.com> Subject: [dpdk-dev] [PATCH 10/10] doc: update security cpu process description X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" This patch updates programmer's guide and release note for newly added security cpu process description. Signed-off-by: Fan Zhang --- doc/guides/cryptodevs/aesni_gcm.rst | 6 ++ doc/guides/cryptodevs/aesni_mb.rst | 7 +++ doc/guides/prog_guide/rte_security.rst | 112 ++++++++++++++++++++++++++++++++- doc/guides/rel_notes/release_19_11.rst | 7 +++ 4 files changed, 131 insertions(+), 1 deletion(-) diff --git a/doc/guides/cryptodevs/aesni_gcm.rst b/doc/guides/cryptodevs/aesni_gcm.rst index 9a8bc9323..31297fabd 100644 --- a/doc/guides/cryptodevs/aesni_gcm.rst +++ b/doc/guides/cryptodevs/aesni_gcm.rst @@ -9,6 +9,12 @@ The AES-NI GCM PMD (**librte_pmd_aesni_gcm**) provides poll mode crypto driver support for utilizing Intel multi buffer library (see AES-NI Multi-buffer PMD documentation to learn more about it, including installation). +The AES-NI GCM PMD also supports rte_security with security session create +and ``rte_security_process_cpu_crypto_bulk`` function call to process +symmetric crypto synchronously with all algorithms specified below. With this +way it supports scather-gather buffers (``rte_security_vec`` can be greater than +``1``. Please refer to ``rte_security`` programmer's guide for more detail. + Features -------- diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst index 1eff2b073..1a3ddd850 100644 --- a/doc/guides/cryptodevs/aesni_mb.rst +++ b/doc/guides/cryptodevs/aesni_mb.rst @@ -12,6 +12,13 @@ support for utilizing Intel multi buffer library, see the white paper The AES-NI MB PMD has current only been tested on Fedora 21 64-bit with gcc. +The AES-NI MB PMD also supports rte_security with security session create +and ``rte_security_process_cpu_crypto_bulk`` function call to process +symmetric crypto synchronously with all algorithms specified below. However +it does not support scather-gather buffer so the ``num`` value in +``rte_security_vec`` can only be ``1``. Please refer to ``rte_security`` +programmer's guide for more detail. + Features -------- diff --git a/doc/guides/prog_guide/rte_security.rst b/doc/guides/prog_guide/rte_security.rst index 7d0734a37..861619202 100644 --- a/doc/guides/prog_guide/rte_security.rst +++ b/doc/guides/prog_guide/rte_security.rst @@ -296,6 +296,56 @@ Just like IPsec, in case of PDCP also header addition/deletion, cipher/ de-cipher, integrity protection/verification is done based on the action type chosen. + +Synchronous CPU Crypto +~~~~~~~~~~~~~~~~~~~~~~ + +RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO: +This action type allows the burst of symmetric crypto workload using the same +algorithm, key, and direction being processed by CPU cycles synchronously. + +The packet is sent to the crypto device for symmetric crypto +processing. The device will encrypt or decrypt the buffer based on the key(s) +and algorithm(s) specified and preprocessed in the security session. Different +than the inline or lookaside modes, when the function exits, the user will +expect the buffers are either processed successfully, or having the error number +assigned to the appropriate index of the status array. + +E.g. in case of IPsec, the application will use CPU cycles to process both +stack and crypto workload synchronously. + +.. code-block:: console + + Egress Data Path + | + +--------|--------+ + | egress IPsec | + | | | + | +------V------+ | + | | SADB lookup | | + | +------|------+ | + | +------V------+ | + | | Desc | | + | +------|------+ | + +--------V--------+ + | + +--------V--------+ + | L2 Stack | + +-----------------+ + | | + | Synchronous | <------ Using CPU instructions + | Crypto Process | + | | + +--------V--------+ + | L2 Stack Post | <------ Add tunnel, ESP header etc header etc. + +--------|--------+ + | + +--------|--------+ + | NIC | + +--------|--------+ + V + + Device Features and Capabilities --------------------------------- @@ -491,6 +541,7 @@ Security Session configuration structure is defined as ``rte_security_session_co struct rte_security_ipsec_xform ipsec; struct rte_security_macsec_xform macsec; struct rte_security_pdcp_xform pdcp; + struct rte_security_cpu_crypto_xform cpu_crypto; }; /**< Configuration parameters for security session */ struct rte_crypto_sym_xform *crypto_xform; @@ -515,9 +566,12 @@ Offload. RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL, /**< All security protocol processing is performed inline during * transmission */ - RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL + RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL, /**< All security protocol processing including crypto is performed * on a lookaside accelerator */ + RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO + /**< Crypto processing for security protocol is processed by CPU + * synchronously }; The ``rte_security_session_protocol`` is defined as @@ -587,6 +641,10 @@ PDCP related configuration parameters are defined in ``rte_security_pdcp_xform`` uint32_t hfn_threshold; }; +For CPU Crypto processing action, the application should attach the initialized +`xform` to the security session configuration to specify the algorithm, key, +direction, and other necessary fields required to perform crypto operation. + Security API ~~~~~~~~~~~~ @@ -650,3 +708,55 @@ it is only valid to have a single flow to map to that security session. +-------+ +--------+ +-----+ | Eth | -> ... -> | ESP | -> | END | +-------+ +--------+ +-----+ + + +Process bulk crypto workload using CPU instructions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The inline and lookaside mode depends on the external HW to complete the +workload, where the user has another option to use rte_security to process +symmetric crypto synchronously with CPU instructions. + +When creating the security session the user need to fill the +``rte_security_session_conf`` parameter with the ``action_type`` field as +``RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO``, and points ``crypto_xform`` to an +properly initialized cryptodev xform. The user then passes the +``rte_security_session_conf`` instance to ``rte_security_session_create()`` +along with the security context pointer belongs to a certain SW crypto device. +The crypto device may or may not support this action type or the algorithm / +key sizes specified in the ``crypto_xform``, but when everything is ok +the function will return the created security session. + +The user then can use this session to process the crypto workload synchronously. +Instead of using mbuf ``next`` pointers, synchronous CPU crypto processing uses +a special structure ``rte_security_vec`` to describe scatter-gather buffers. + +.. code-block:: c + + struct rte_security_vec { + struct iovec *vec; + uint32_t num; + }; + +Where the structure ``rte_security_vec`` is used to store scatter-gather buffer +pointers, where ``vec`` is the pointer to one buffer and ``num`` indicates the +number of buffers. + +Please note not all crypto devices support scatter-gather buffer processing, +please check ``cryptodev`` guide for more details. + +The API of the synchronous CPU crypto process is + +.. code-block:: c + + void + rte_security_process_cpu_crypto_bulk(struct rte_security_ctx *instance, + struct rte_security_session *sess, + struct rte_security_vec buf[], void *iv[], void *aad[], + void *digest[], int status[], uint32_t num); + +This function will process ``num`` number of ``rte_security_vec`` buffers using +the content stored in ``iv`` and ``aad`` arrays. The API only support in-place +operation so ``buf`` will be overwritten the encrypted or decrypted values +when successfully processed. Otherwise the error number of the status array's +according index. diff --git a/doc/guides/rel_notes/release_19_11.rst b/doc/guides/rel_notes/release_19_11.rst index 8490d897c..6cd21704f 100644 --- a/doc/guides/rel_notes/release_19_11.rst +++ b/doc/guides/rel_notes/release_19_11.rst @@ -56,6 +56,13 @@ New Features Also, make sure to start the actual text at the margin. ========================================================= +* **RTE_SECURITY is added new synchronous Crypto burst API with CPU** + + A new API rte_security_process_cpu_crypto_bulk is introduced in security + library to process crypto workload in bulk using CPU instructions. AESNI_MB + and AESNI_GCM PMD, as well as unit-test and ipsec-secgw sample applications + are updated to support this feature. + Removed Items -------------