--- name: "crypto_dispatch" section: "9" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/crypto_clonereq" --- # crypto\_dispatch(9) symmetric cryptographic operations Part of [crypto\_clonereq(9)](/crypto_clonereq/9.md). ## NAME **crypto\_request** – symmetric cryptographic operations ## SYNOPSIS **#include \** *struct cryptop \**\ **crypto\_clonereq**(*crypto\_session\_t cses*, *struct cryptop \*crp*, *int how*); *int*\ **crypto\_dispatch**(*struct cryptop \*crp*); *int*\ **crypto\_dispatch\_async**(*struct cryptop \*crp*, *int flags*); *void*\ **crypto\_dispatch\_batch**(*struct cryptopq \*crpq*, *int flags*); *void*\ **crypto\_destroyreq**(*struct cryptop \*crp*); *void*\ **crypto\_freereq**(*struct cryptop \*crp*); *struct cryptop \**\ **crypto\_getreq**(*crypto\_session\_t cses*, *int how*); *void*\ **crypto\_initreq**(*struct cryptop \*crp*, *crypto\_session\_t cses*); *void*\ **crypto\_use\_buf**(*struct cryptop \*crp*, *void \*buf*, *int len*); *void*\ **crypto\_use\_mbuf**(*struct cryptop \*crp*, *struct mbuf \*m*); *void*\ **crypto\_use\_uio**(*struct cryptop \*crp*, *struct uio \*uio*); *void*\ **crypto\_use\_vmpage**(*struct cryptop \*crp*, *vm\_page\_t \*pages*, *int len*, *int offset*); *void*\ **crypto\_use\_output\_buf**(*struct cryptop \*crp*, *void \*buf*, *int len*); *void*\ **crypto\_use\_output\_mbuf**(*struct cryptop \*crp*, *struct mbuf \*m*); *void*\ **crypto\_use\_output\_uio**(*struct cryptop \*crp*, *struct uio \*uio*); *void*\ **crypto\_use\_output\_vmpage**(*struct cryptop \*crp*, *vm\_page\_t \*pages*, *int len*, *int offset*); ## DESCRIPTION Each symmetric cryptographic operation in the kernel is described by an instance of *struct* *cryptop* and is associated with an active session. Requests can either be allocated dynamically or use caller-supplied storage. Dynamically allocated requests should be allocated by either **crypto\_getreq**() or **crypto\_clonereq**(), and freed by **crypto\_freereq**() once the request has completed. Requests using caller-supplied storage should be initialized by **crypto\_initreq**() at the start of each operation and destroyed by **crypto\_destroyreq**() once the request has completed. For **crypto\_clonereq**(), **crypto\_getreq**(), and **crypto\_initreq**(), *cses* is a reference to an active session. For **crypto\_clonereq**() and **crypto\_getreq**(), *how* is passed to [malloc(9)](/malloc/9.md) and should be set to either M\_NOWAIT or M\_WAITOK. **crypto\_clonereq**() allocates a new request that inherits request inputs such as request buffers from the original *crp* request. However, the new request is associated with the *cses* session rather than inheriting the session from *crp*. *crp* must not be a completed request. Once a request has been initialized, the caller should set fields in the structure to describe request-specific parameters. Unused fields should be left as-is. The **crypto\_dispatch**(), **crypto\_dispatch\_async**(), and **crypto\_dispatch\_batch**() functions pass one or more crypto requests to the driver attached to the request's session. If there are errors in the request's fields, these functions may return an error to the caller. If errors are encountered while servicing the request, they will instead be reported to the request's callback function (*crp\_callback*) via *crp\_etype*. Note that a request's callback function may be invoked before **crypto\_dispatch**() returns. Once a request has signaled completion by invoking its callback function, it should be freed via **crypto\_destroyreq**() or **crypto\_freereq**(). Cryptographic operations include several fields to describe the request. ### Request Buffers Requests can either specify a single data buffer that is modified in place( *crp\_buf*) or separate input( *crp\_buf*) and output( *crp\_obuf*) buffers. Note that separate input and output buffers are not supported for compression mode requests. All requests must have a valid *crp\_buf* initialized by one of the following functions: - **crypto\_use\_buf**() Uses an array of *len* bytes pointed to by *buf* as the data buffer. - **crypto\_use\_mbuf**() Uses the network memory buffer *m* as the data buffer. - **crypto\_use\_uio**() Uses the scatter/gather list *uio* as the data buffer. - **crypto\_use\_vmpage**() Uses the array of *vm\_page\_t* structures as the data buffer. One of the following functions should be used to initialize *crp\_obuf* for requests that use separate input and output buffers: - **crypto\_use\_output\_buf**() Uses an array of *len* bytes pointed to by *buf* as the output buffer. - **crypto\_use\_output\_mbuf**() Uses the network memory buffer *m* as the output buffer. - **crypto\_use\_output\_uio**() Uses the scatter/gather list *uio* as the output buffer. - **crypto\_use\_output\_vmpage**() Uses the array of *vm\_page\_t* structures as the output buffer. ### Request Regions Each request describes one or more regions in the data buffers. Each region is described by an offset relative to the start of a data buffer and a length. The length of some regions is the same for all requests belonging to a session. Those lengths are set in the session parameters of the associated session. All requests must define a payload region. Other regions are only required for specific session modes. For requests with separate input and output data buffers, the AAD, IV, and payload regions are always defined as regions in the input buffer, and a separate payload output region is defined to hold the output of encryption or decryption in the output buffer. The digest region describes a region in the input data buffer for requests that verify an existing digest. For requests that compute a digest, the digest region describes a region in the output data buffer. Note that the only data written to the output buffer is the encryption or decryption result and any computed digest. AAD and IV regions are not copied from the input buffer into the output buffer but are only used as inputs. The following regions are defined: | | | | | --- | --- | --- | | **Region** | **Buffer** | **Description** | | AAD | Input | | | IV | Input | | | Payload | Input | | | Payload Output | Output | | | Digest | Input/Output | | | | | | | --- | --- | --- | | **Region** | **Start** | **Length** | | AAD | *crp\_aad\_start* | *crp\_aad\_length* | | IV | *crp\_iv\_start* | *csp\_ivlen* | | Payload | *crp\_payload\_start* | *crp\_payload\_length* | | Payload Output | *crp\_payload\_output\_start* | *crp\_payload\_length* | | Digest | *crp\_digest\_start* | *csp\_auth\_mlen* | Requests are permitted to operate on only a subset of the data buffer. For example, requests from IPsec operate on network packets that include headers not used as either additional authentication data (AAD) or payload data. ### Request Operations All requests must specify the type of operation to perform in *crp\_op*. Available operations depend on the session's mode. Compression requests support the following operations: - CRYPTO\_OP\_COMPRESS Compress the data in the payload region of the data buffer. - CRYPTO\_OP\_DECOMPRESS Decompress the data in the payload region of the data buffer. Cipher requests support the following operations: - CRYPTO\_OP\_ENCRYPT Encrypt the data in the payload region of the data buffer. - CRYPTO\_OP\_DECRYPT Decrypt the data in the payload region of the data buffer. Digest requests support the following operations: - CRYPTO\_OP\_COMPUTE\_DIGEST Calculate a digest over the payload region of the data buffer and store the result in the digest region. - CRYPTO\_OP\_VERIFY\_DIGEST Calculate a digest over the payload region of the data buffer. Compare the calculated digest to the existing digest from the digest region. If the digests match, complete the request successfully. If the digests do not match, fail the request with EBADMSG. AEAD and Encrypt-then-Authenticate requests support the following operations: - CRYPTO\_OP\_ENCRYPT \| CRYPTO\_OP\_COMPUTE\_DIGEST Encrypt the data in the payload region of the data buffer. Calculate a digest over the AAD and payload regions and store the result in the data buffer. - CRYPTO\_OP\_DECRYPT \| CRYPTO\_OP\_VERIFY\_DIGEST Calculate a digest over the AAD and payload regions of the data buffer. Compare the calculated digest to the existing digest from the digest region. If the digests match, decrypt the payload region. If the digests do not match, fail the request with EBADMSG. ### Request AAD AEAD and Encrypt-then-Authenticate requests may optionally include Additional Authenticated Data. AAD may either be supplied in the AAD region of the input buffer or as a single buffer pointed to by *crp\_aad*. In either case, *crp\_aad\_length* always indicates the amount of AAD in bytes. ### Request ESN IPsec requests may optionally include Extended Sequence Numbers (ESN). ESN may either be supplied in *crp\_esn* or as part of the AAD pointed to by *crp\_aad*. If the ESN is stored in *crp\_esn*, CSP\_F\_ESN should be set in *csp\_flags*. This use case is dedicated for encrypt and authenticate mode, since the high-order 32 bits of the sequence number are appended after the Next Header (RFC 4303). AEAD modes supply the ESN in a separate AAD buffer (see e.g. RFC 4106, Chapter 5 AAD Construction). ### Request IV and/or Nonce Some cryptographic operations require an IV or nonce as an input. An IV may be stored either in the IV region of the data buffer or in *crp\_iv*. By default, the IV is assumed to be stored in the IV region. If the IV is stored in *crp\_iv*, CRYPTO\_F\_IV\_SEPARATE should be set in *crp\_flags* and *crp\_iv\_start* should be left as zero. Requests that store part, but not all, of the IV in the data buffer should store the partial IV in the data buffer and pass the full IV separately in *crp\_iv*. ### Request and Callback Scheduling The crypto framework provides multiple methods of scheduling the dispatch of requests to drivers along with the processing of driver callbacks. The **crypto\_dispatch**(), **crypto\_dispatch\_async**(), and **crypto\_dispatch\_batch**() functions can be used to request different dispatch scheduling policies. **crypto\_dispatch**() synchronously passes the request to the driver. The driver itself may process the request synchronously or asynchronously depending on whether the driver is implemented by software or hardware. **crypto\_dispatch\_async**() dispatches the request asynchronously. If the driver is inherently synchronous, the request is queued to a taskqueue backed by a pool of worker threads. This can increase throughput by allowing requests from a single producer to be processed in parallel. By default the pool is sized to provide one thread for each CPU. Worker threads dequeue requests and pass them to the driver asynchronously. **crypto\_dispatch\_async**() additionally takes a *flags* parameter. The CRYPTO\_ASYNC\_ORDERED flag indicates that completion callbacks for requests must be called in the same order as requests were dispatched. If the driver is asynchronous, the behavior of **crypto\_dispatch\_async**() is identical to that of **crypto\_dispatch**(). **crypto\_dispatch\_batch**() allows the caller to collect a batch of requests and submit them to the driver at the same time. This allows hardware drivers to optimize the scheduling of request processing and batch completion interrupts. A batch is submitted to the driver by invoking the driver's process method on each request, specifying CRYPTO\_HINT\_MORE with each request except for the last. The *flags* parameter to **crypto\_dispatch\_batch**() is currently ignored. Callback function scheduling is simpler than request scheduling. Callbacks can either be invoked synchronously from **crypto\_done**(), or they can be queued to a pool of worker threads. This pool of worker threads is also sized to provide one worker thread for each CPU by default. Note that a callback function invoked synchronously from **crypto\_done**() must follow the same restrictions placed on threaded interrupt handlers. By default, callbacks are invoked asynchronously by a worker thread. If CRYPTO\_F\_CBIMM is set, the callback is always invoked synchronously from **crypto\_done**(). If CRYPTO\_F\_CBIFSYNC is set, the callback is invoked synchronously if the request was processed by a software driver or asynchronously if the request was processed by a hardware driver. If a request was scheduled to the taskqueue with CRYPTO\_ASYNC\_ORDERED, callbacks are always invoked asynchronously ignoring CRYPTO\_F\_CBIMM and CRYPTO\_F\_CBIFSYNC. This flag is used by IPsec to ensure that decrypted network packets are passed up the network stack in roughly the same order they were received. ### Other Request Fields In addition to the fields and flags enumerated above, *struct* *cryptop* includes the following: - *crp\_session* A reference to the active session. This is set when the request is created by **crypto\_getreq**() and should not be modified. Drivers can use this to fetch driver-specific session state or session parameters. - *crp\_etype* Error status. Either zero on success, or an error if a request fails. Set by drivers prior to completing a request via **crypto\_done**(). - *crp\_flags* A bitmask of flags. - *crp\_cipher\_key* Pointer to a request-specific encryption key. If this value is not set, the request uses the session encryption key. - *crp\_auth\_key* Pointer to a request-specific authentication key. If this value is not set, the request uses the session authentication key. - *crp\_opaque* An opaque pointer. This pointer permits users of the cryptographic framework to store information about a request to be used in the callback. - *crp\_callback* Callback function. This must point to a callback function of type *void* *(\*)(struct* *cryptop* *\*)*. The callback function should inspect *crp\_etype* to determine the status of the completed operation. It should also arrange for the request to be freed via **crypto\_freereq**(). - *crp\_olen* Used with compression and decompression requests to describe the updated length of the payload region in the data buffer. If a compression request increases the size of the payload, then the data buffer is unmodified, the request completes successfully, and *crp\_olen* is set to the size the compressed data would have used. Callers can compare this to the payload region length to determine if the compressed data was discarded. ## RETURN VALUES **crypto\_dispatch**() returns an error if the request contained invalid fields, or zero if the request was valid. **crypto\_getreq**() returns a pointer to a new request structure on success, or NULL on failure. NULL can only be returned if M\_NOWAIT was passed in *how*. ## SEE ALSO [ipsec(4)](/ipsec/4.md), [crypto(7)](/crypto/7.md), [crypto(9)](/crypto/9.md), [crypto\_session(9)](/crypto_session/9.md), [mbuf(9)](/mbuf/9.md), [uio(9)](/uio/9.md) ## BUGS Not all drivers properly handle mixing session and per-request keys within a single session. Consumers should either use a single key for a session specified in the session parameters or always use per-request keys.