1 .\" Copyright (c) 2020, Chelsio Inc
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions are met:
6 .\" 1. Redistributions of source code must retain the above copyright notice,
7 .\" this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. Neither the name of the Chelsio Inc nor the names of its
14 .\" contributors may be used to endorse or promote products derived from
15 .\" this software without specific prior written permission.
17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
21 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\" * Other names and brands may be claimed as the property of others.
38 .Nd interface for symmetric cryptographic drivers
40 .In opencrypto/cryptodev.h
43 .Fa "struct cryptop *crp"
46 .Fa "int (*f)(void *, void *, u_int)"
50 .Fo crypto_contiguous_subsegment
51 .Fa "struct cryptop *crp"
56 .Fn crypto_copyback "struct cryptop *crp" "int off" "int size" "const void *src"
58 .Fn crypto_copydata "struct cryptop *crp" "int off" "int size" "void *dst"
60 .Fn crypto_done "struct cryptop *crp"
62 .Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags"
64 .Fn crypto_get_driver_session "crypto_session_t crypto_session"
66 .Fn crypto_read_iv "struct cryptop *crp" "void *iv"
68 .Fn crypto_unblock "uint32_t driverid" "int what"
70 .Fn crypto_unregister_all "uint32_t driverid"
72 .Fn CRYPTODEV_FREESESSION "device_t dev" "crypto_session_t crypto_session"
74 .Fo CRYPTODEV_NEWSESSION
76 .Fa "crypto_session_t crypto_session"
77 .Fa "const struct crypto_session_params *csp"
80 .Fo CRYPTODEV_PROBESESSION
82 .Fa "const struct crypto_session_params *csp"
85 .Fn CRYPTODEV_PROCESS "device_t dev" "struct cryptop *crp" "int flags"
88 .Fa "struct auth_hash *axf"
95 .Fa "struct auth_hash *axf"
101 Symmetric cryptographic drivers process cryptographic requests
102 submitted to sessions associated with the driver.
104 Cryptographic drivers call
105 .Fn crypto_get_driverid
106 to register with the cryptographic framework.
108 is the device used to service requests.
111 methods are defined in the method table for the device driver attached to
114 specifies the size of a driver-specific per-session structure allocated by
115 the cryptographic framework.
117 is a bitmask of properties about the driver.
119 .Dv CRYPTOCAP_F_SOFTWARE
121 .Dv CRYPTOCAP_F_HARDWARE
123 .Dv CRYPTOCAP_F_SOFTWARE
124 should be used for drivers which process requests using host CPUs.
125 .Dv CRYPTOCAP_F_HARDWARE
126 should be used for drivers which process requests on separate co-processors.
128 should be set for drivers which process requests synchronously in
129 .Fn CRYPTODEV_PROCESS .
130 .Fn crypto_get_driverid
131 returns an opaque driver id.
133 .Fn crypto_unregister_all
134 unregisters a driver from the cryptographic framework.
135 If there are any pending operations or open sessions,
136 this function will sleep.
138 is the value returned by an earlier call to
139 .Fn crypto_get_driverid .
141 When a new session is created by
142 .Fn crypto_newsession ,
143 .Fn CRYPTODEV_PROBESESSION
144 is invoked by the cryptographic framework on each active driver to
145 determine the best driver to use for the session.
146 This method should inspect the session parameters in
148 If a driver does not support requests described by
150 this method should return an error value.
151 If the driver does support requests described by
153 it should return a negative value.
154 The framework prefers drivers with the largest negative value,
157 The following values are defined for non-error return values from this
159 .Bl -tag -width "CRYPTODEV_PROBE_ACCEL_SOFTWARE"
160 .It Dv CRYPTODEV_PROBE_HARDWARE
161 The driver processes requests via a co-processor.
162 .It Dv CRYPTODEV_PROBE_ACCEL_SOFTWARE
163 The driver processes requests on the host CPU using optimized instructions
165 .It Dv CRYPTODEV_PROBE_SOFTWARE
166 The driver processes requests on the host CPU.
169 This method should not sleep.
171 Once the framework has chosen a driver for a session,
172 the framework invokes the
173 .Fn CRYPTODEV_NEWSESSION
174 method to initialize driver-specific session state.
175 Prior to calling this method,
176 the framework allocates a per-session driver-specific data structure.
177 This structure is initialized with zeroes,
178 and its size is set by the
181 .Fn crypto_get_driverid .
182 This method can retrieve a pointer to this data structure by passing
185 .Fn crypto_get_driver_session .
186 Session parameters are described in
189 This method should not sleep.
191 .Fn CRYPTODEV_FREESESSION
192 is invoked to release any driver-specific state when a session is
194 The per-session driver-specific data structure is explicitly zeroed
195 and freed by the framework after this method returns.
196 If a driver requires no additional tear-down steps, it can leave
197 this method undefined.
199 This method should not sleep.
201 .Fn CRYPTODEV_PROCESS
202 is invoked for each request submitted to an active session.
203 This method can either complete a request synchronously or
204 schedule it to be completed asynchronously,
205 but it must not sleep.
207 If this method is not able to complete a request due to insufficient
208 resources such as a full command queue,
209 it can defer the request by returning
211 The request will be queued by the framework and retried once the
212 driver releases pending requests via
214 Any requests submitted to sessions belonging to the driver will also
219 If a driver encounters errors while processing a request,
220 it should report them via the
224 rather than returning an error directly.
229 if there are additional requests queued for this driver.
230 The driver can use this as a hint to batch completion interrupts.
231 Note that these additional requests may be from different sessions.
233 .Fn crypto_get_driver_session
234 returns a pointer to the driver-specific per-session data structure
237 This function can be used in the
238 .Fn CRYPTODEV_NEWSESSION ,
239 .Fn CRYPTODEV_PROCESS ,
241 .Fn CRYPTODEV_FREESESSION
247 bytes out of the data buffer for
249 into a local buffer pointed to by
251 The bytes are read starting at an offset of
253 bytes in the request's data buffer.
258 bytes from the local buffer pointed to by
260 into the data buffer for
262 The bytes are written starting at an offset of
264 bytes in the request's data buffer.
267 copies the IV or nonce for
269 into the the local buffer pointed to by
277 Any errors should be set in
279 prior to calling this function.
281 If a driver defers a request by returning
285 the framework will queue all requests for the driver until the driver calls
287 to indicate that the temporary resource shortage has been relieved.
291 due to a full command ring,
294 from a command completion interrupt that makes a command ring entry available.
296 is the value returned by
297 .Fn crypto_get_driverid .
299 indicates which types of requests the driver is able to handle again:
300 .Bl -tag -width "CRYPTO_ASYMQ"
302 indicates that the driver is able to handle symmetric requests passed to
303 .Fn CRYPTODEV_PROCESS .
305 indicates that the driver is able to handle asymmetric requests passed to
306 .Fn CRYPTODEV_KPROCESS .
310 is a helper routine that can be used to invoke a caller-supplied function
311 to a region of the data buffer for
315 is called one or more times.
317 the first argument to
322 The second and third arguments to
324 are a pointer and length to a segment of the buffer mapped into the kernel.
325 The function is called enough times to cover the
327 bytes of the data buffer which starts at an offset
331 returns a non-zero value,
333 immediately returns that value without invoking
335 on any remaining segments of the region,
338 returns the value from the final call to
341 .Fn crypto_contiguous_subsegment
342 attempts to locate a single, virtually-contiguous segment of the data buffer
347 bytes long and start at an offset of
350 If a segment is found,
351 a pointer to the start of the segment is returned.
357 prepares an authentication context to generate the inner hash of an HMAC.
359 is a software implementation of an authentication algorithm such as the
361 .Fn crypto_auth_hash .
363 is a pointer to a HMAC key of
367 points to a valid authentication context for the desired algorithm.
368 The function initializes the context with the supplied key.
373 except that it prepares an authentication context to generate the
374 outer hash of an HMAC.
377 returns the return value from the caller-supplied callback function.
379 .Fn crypto_contiguous_subsegment
380 returns a pointer to a contiguous segment or
383 .Fn crypto_get_driverid
384 returns a driver identifier on success or -1 on error.
387 .Fn crypto_unregister_all ,
388 .Fn CRYPTODEV_FREESESSION ,
389 .Fn CRYPTODEV_NEWSESSION ,
391 .Fn CRYPTODEV_PROCESS
392 return zero on success or an error on failure.
394 .Fn CRYPTODEV_PROBESESSION
395 returns a negative value on success or an error on failure.
399 .Xr crypto_request 9 ,