--- /dev/null
+EVP APIs for supporting cipher pipelining in provided ciphers
+=============================================================
+
+OpenSSL previously supported "pipeline" ciphers via ENGINE implementations.
+That support was lost when we moved to providers. This document discusses API
+design to restore that capability and enable providers to implement such
+ciphers.
+
+Pipeline operation
+-------------------
+
+Certain ciphers, such as AES-GCM, can be optimized by computing blocks in
+parallel. Cipher pipelining support allows application to submit multiple
+chunks of data in one cipher update call, thereby allowing the provided
+implementation to take advantage of parallel computing. This is very beneficial
+for hardware accelerators as pipeline amortizes the latency over multiple
+chunks. Our libssl makes use of pipeline as discussed in
+[here](https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_max_pipelines.html).
+
+Pipelining with ENGINE
+-----------------------
+
+Before discussing API design for providers, let's take a look at existing
+pipeline API that works with engines.
+
+**EVP Interface:**
+Flag to denote pipeline support
+
+```c
+cipher->flags & EVP_CIPH_FLAG_PIPELINE
+```
+
+Input/output and aad buffers are set using `EVP_CIPHER_CTX_ctrl()`
+
+```c
+EVP_CIPHER_CTX_ctrl()
+ - EVP_CTRL_AEAD_TLS1_AAD (loop: one aad at a time)
+ - EVP_CTRL_SET_PIPELINE_OUTPUT_BUFS (array of buffer pointers)
+ - EVP_CTRL_SET_PIPELINE_INPUT_BUFS (array of buffer pointers)
+ - EVP_CTRL_SET_PIPELINE_INPUT_LENS
+```
+
+Single-call cipher invoked to perform encryption/decryption.
+
+```c
+EVP_Cipher()
+```
+
+Proposal for EVP pipeline APIs
+-------------------------------------
+
+Current API design is made similar to non-pipeline counterpart. The document
+will be final once the changes are integrated.
+
+**EVP Interface:**
+API to check for pipeline support in provided cipher.
+
+```c
+/**
+ * @brief checks if the provider has exported required pipeline functions
+ * This function works only with explicitly fetched EVP_CIPHER instances. i.e.
+ * fetched using `EVP_CIPHER_fetch()`. For non-fetched ciphers, it returns 0.
+ *
+ * @param enc 1 for encryption, 0 for decryption
+ * @return 0 (pipeline not supported) or 1 (pipeline supported)
+ */
+int EVP_CIPHER_can_pipeline(const EVP_CIPHER *cipher, int enc);
+```
+
+Multi-call APIs for init, update and final. Associated data for AEAD ciphers
+are set in `EVP_CipherPipelineUpdate`.
+
+```c
+/**
+ * @param iv array of pointers (array length must be numpipes)
+ */
+int EVP_CipherPipelineEncryptInit(EVP_CIPHER_CTX *ctx,
+ const EVP_CIPHER *cipher,
+ const unsigned char *key, size_t keylen,
+ size_t numpipes,
+ const unsigned char **iv, size_t ivlen);
+int EVP_CipherPipelineDecryptInit(EVP_CIPHER_CTX *ctx,
+ const EVP_CIPHER *cipher,
+ const unsigned char *key, size_t keylen,
+ size_t numpipes,
+ const unsigned char **iv, size_t ivlen);
+
+/*
+ * @param out array of pointers to output buffers (array length must be
+ * numpipes)
+ * when NULL, input buffers are treated as AAD data
+ * @param outl pointer to array of output length (array length must be
+ * numpipes)
+ * @param outsize pointer to array of output buffer size (array length must be
+ * numpipes)
+ * @param in array of pointers to input buffers (array length must be
+ * numpipes)
+ * @param inl pointer to array of input length (array length must be numpipes)
+ */
+int EVP_CipherPipelineUpdate(EVP_CIPHER_CTX *ctx,
+ unsigned char **out, size_t *outl,
+ const size_t *outsize,
+ const unsigned char **in, const size_t *inl);
+
+/*
+ * @param outm array of pointers to output buffers (array length must be
+ * numpipes)
+ * @param outl pointer to array of output length (array length must be
+ * numpipes)
+ * @param outsize pointer to array of output buffer size (array length must be
+ * numpipes)
+ */
+int EVP_CipherPipelineFinal(EVP_CIPHER_CTX *ctx,
+ unsigned char **outm, size_t *outl,
+ const size_t *outsize);
+```
+
+API to get/set AEAD auth tag.
+
+```c
+/**
+ * @param buf array of pointers to aead buffers (array length must be
+ * numpipes)
+ * @param bsize size of one buffer (all buffers must be of same size)
+ *
+ * AEAD tag len is set using OSSL_CIPHER_PARAM_AEAD_TAGLEN
+ */
+OSSL_CIPHER_PARAM_PIPELINE_AEAD_TAG (type OSSL_PARAM_OCTET_PTR)
+```
+
+**Alternative:** iovec style interface for input/output buffers.
+
+```c
+typedef struct {
+ unsigned char *buf;
+ size_t buf_len;
+} EVP_CIPHER_buf;
+
+/**
+ * @param out array of EVP_CIPHER_buf containing output buffers (array
+ * length must be numpipes)
+ * when this param is NULL, input buffers are treated as AAD
+ * data (individual pointers within array being NULL will be
+ * an error)
+ * @param in array of EVP_CIPHER_buf containing input buffers (array
+ * length must be numpipes)
+ * @param stride The stride argument must be set to sizeof(EVP_CIPHER_buf)
+ */
+EVP_CipherPipelineUpdate(EVP_CIPHER_CTX *ctx, EVP_CIPHER_buf *out,
+ EVP_CIPHER_buf *in, size_t stride);
+
+/**
+ * @param outm array of EVP_CIPHER_buf containing output buffers (array
+ * length must be numpipes)
+ * @param stride The stride argument must be set to sizeof(EVP_CIPHER_buf)
+ */
+EVP_CipherPipelineFinal(EVP_CIPHER_CTX *ctx,
+ EVP_CIPHER_buf *out, size_t stride);
+
+/**
+ * @param buf array of EVP_CIPHER_buf containing output buffers (array
+ * length must be numpipes)
+ * @param bsize stride; sizeof(EVP_CIPHER_buf)
+ */
+OSSL_CIPHER_PARAM_PIPELINE_AEAD_TAG (type OSSL_PARAM_OCTET_PTR)
+```
+
+**Design Decisions:**
+
+1. Denoting pipeline support
+ - [ ] a. A cipher flag `EVP_CIPH_FLAG_PROVIDED_PIPELINE` (this has to be
+ different than EVP_CIPH_FLAG_PIPELINE, so that it doesn't break legacy
+ applications).
+ - [x] b. A function `EVP_CIPHER_can_pipeline()` that checks if the provider
+ exports pipeline functions.
+ > **Justification:** flags variable is deprecated in EVP_CIPHER struct.
+ > Moreover, EVP can check for presence of pipeline functions, rather than
+ > requiring providers to set a flag.
+
+With the introduction of this new API, there will be two APIs for
+pipelining available until the legacy code is phased out:
+ a. When an Engine that supports pipelining is loaded, it will set the
+ `ctx->flags & EVP_CIPH_FLAG_PIPELINE`. If this flag is set, applications
+ can continue to use the legacy API for pipelining.
+ b. When a Provider that supports pipelining is fetched,
+ `EVP_CIPHER_can_pipeline()` will return true, allowing applications to
+ utilize the new API for pipelining.
+
+2. `numpipes` argument
+ - [x] a. `numpipes` received only in `EVP_CipherPipelineEncryptInit()` and
+ saved in EVP_CIPHER_CTX for further use.
+ - [ ] b. `numpipes` value is repeatedly received in each
+ `EVP_CipherPipelineEncryptInit()`, `EVP_CipherPipelineUpdate()` and
+ `EVP_CipherPipelineFinal()` call.
+ > **Justification:** It is expected for numpipes to be same across init,
+ > update and final operation.
+
+3. Input/Output buffers
+ - [x] a. A set of buffers is represented by an array of buffer pointers and
+ an array of lengths. Example: `unsigned char **out, size_t *outl`.
+ - [ ] b. iovec style: A new type that holds one buffer pointer along with
+ its size. Example: `EVP_CIPHER_buf *out`
+ > **Justification:** While iovec style is better buffer representation, the
+ > EVP - provider interface in core_dispatch.h uses only primitive types.
+
+4. AEAD tag
+ - [x] a. A new OSSL_CIPHER_PARAM of type OSSL_PARAM_OCTET_PTR,
+ `OSSL_CIPHER_PARAM_PIPELINE_AEAD_TAG`, that uses an array of buffer
+ pointers. This can be used with `iovec_buf` if we decide with 3.b.
+ - [ ] b. Reuse `OSSL_CIPHER_PARAM_AEAD_TAG` by using it in a loop,
+ processing one tag at a time.
+ > **Justification:** Reduces cipher get/set param operations.
+
+Future Ideas
+------------
+
+1. It would be nice to have a mechanism for fetching provider with pipeline
+ support over other providers that don't support pipeline. Maybe by using
+ property query strings.
projects / thirdparty / openssl.git / commitdiff
