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
42 .Fn crypto_copyback "struct cryptop *crp" "int off" "int size" "const void *src"
44 .Fn crypto_copydata "struct cryptop *crp" "int off" "int size" "void *dst"
46 .Fn crypto_done "struct cryptop *crp"
48 .Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags"
50 .Fn crypto_get_driver_session "crypto_session_t crypto_session"
52 .Fn crypto_read_iv "struct cryptop *crp" "void *iv"
54 .Fn crypto_unblock "uint32_t driverid" "int what"
56 .Fn crypto_unregister_all "uint32_t driverid"
58 .Fn CRYPTODEV_FREESESSION "device_t dev" "crypto_session_t crypto_session"
60 .Fo CRYPTODEV_NEWSESSION
62 .Fa "crypto_session_t crypto_session"
63 .Fa "const struct crypto_session_params *csp"
66 .Fo CRYPTODEV_PROBESESSION
68 .Fa "const struct crypto_session_params *csp"
71 .Fn CRYPTODEV_PROCESS "device_t dev" "struct cryptop *crp" "int flags"
74 .Fa "struct auth_hash *axf"
81 .Fa "struct auth_hash *axf"
87 Symmetric cryptographic drivers process cryptographic requests
88 submitted to sessions associated with the driver.
90 Cryptographic drivers call
91 .Fn crypto_get_driverid
92 to register with the cryptographic framework.
94 is the device used to service requests.
97 methods are defined in the method table for the device driver attached to
100 specifies the size of a driver-specific per-session structure allocated by
101 the cryptographic framework.
103 is a bitmask of properties about the driver.
105 .Dv CRYPTOCAP_F_SOFTWARE
107 .Dv CRYPTOCAP_F_HARDWARE
109 .Dv CRYPTOCAP_F_SOFTWARE
110 should be used for drivers which process requests using host CPUs.
111 .Dv CRYPTOCAP_F_HARDWARE
112 should be used for drivers which process requests on separate co-processors.
114 should be set for drivers which process requests synchronously in
115 .Fn CRYPTODEV_PROCESS .
116 .Dv CRYPTOCAP_F_ACCEL_SOFTWARE
117 should be set for software drivers which use accelerated CPU instructions.
118 .Fn crypto_get_driverid
119 returns an opaque driver id.
121 .Fn crypto_unregister_all
122 unregisters a driver from the cryptographic framework.
123 If there are any pending operations or open sessions,
124 this function will sleep.
126 is the value returned by an earlier call to
127 .Fn crypto_get_driverid .
129 When a new session is created by
130 .Fn crypto_newsession ,
131 .Fn CRYPTODEV_PROBESESSION
132 is invoked by the cryptographic framework on each active driver to
133 determine the best driver to use for the session.
134 This method should inspect the session parameters in
136 If a driver does not support requests described by
138 this method should return an error value.
139 If the driver does support requests described by
141 it should return a negative value.
142 The framework prefers drivers with the largest negative value,
145 The following values are defined for non-error return values from this
147 .Bl -tag -width "CRYPTODEV_PROBE_ACCEL_SOFTWARE"
148 .It Dv CRYPTODEV_PROBE_HARDWARE
149 The driver processes requests via a co-processor.
150 .It Dv CRYPTODEV_PROBE_ACCEL_SOFTWARE
151 The driver processes requests on the host CPU using optimized instructions
153 .It Dv CRYPTODEV_PROBE_SOFTWARE
154 The driver processes requests on the host CPU.
157 This method should not sleep.
159 Once the framework has chosen a driver for a session,
160 the framework invokes the
161 .Fn CRYPTODEV_NEWSESSION
162 method to initialize driver-specific session state.
163 Prior to calling this method,
164 the framework allocates a per-session driver-specific data structure.
165 This structure is initialized with zeroes,
166 and its size is set by the
169 .Fn crypto_get_driverid .
170 This method can retrieve a pointer to this data structure by passing
173 .Fn crypto_get_driver_session .
174 Session parameters are described in
177 This method should not sleep.
179 .Fn CRYPTODEV_FREESESSION
180 is invoked to release any driver-specific state when a session is
182 The per-session driver-specific data structure is explicitly zeroed
183 and freed by the framework after this method returns.
184 If a driver requires no additional tear-down steps, it can leave
185 this method undefined.
187 This method should not sleep.
189 .Fn CRYPTODEV_PROCESS
190 is invoked for each request submitted to an active session.
191 This method can either complete a request synchronously or
192 schedule it to be completed asynchronously,
193 but it must not sleep.
195 If this method is not able to complete a request due to insufficient
196 resources such as a full command queue,
197 it can defer the request by returning
199 The request will be queued by the framework and retried once the
200 driver releases pending requests via
202 Any requests submitted to sessions belonging to the driver will also
207 If a driver encounters errors while processing a request,
208 it should report them via the
212 rather than returning an error directly.
217 if there are additional requests queued for this driver.
218 The driver can use this as a hint to batch completion interrupts.
219 Note that these additional requests may be from different sessions.
221 .Fn crypto_get_driver_session
222 returns a pointer to the driver-specific per-session data structure
225 This function can be used in the
226 .Fn CRYPTODEV_NEWSESSION ,
227 .Fn CRYPTODEV_PROCESS ,
229 .Fn CRYPTODEV_FREESESSION
235 bytes out of the input buffer for
237 into a local buffer pointed to by
239 The bytes are read starting at an offset of
241 bytes in the request's input buffer.
246 bytes from the local buffer pointed to by
248 into the output buffer for
250 The bytes are written starting at an offset of
252 bytes in the request's output buffer.
255 copies the IV or nonce for
257 into the local buffer pointed to by
265 Any errors should be set in
267 prior to calling this function.
269 If a driver defers a request by returning
273 the framework will queue all requests for the driver until the driver calls
275 to indicate that the temporary resource shortage has been relieved.
279 due to a full command ring,
282 from a command completion interrupt that makes a command ring entry available.
284 is the value returned by
285 .Fn crypto_get_driverid .
287 indicates which types of requests the driver is able to handle again:
288 .Bl -tag -width "CRYPTO_ASYMQ"
290 indicates that the driver is able to handle symmetric requests passed to
291 .Fn CRYPTODEV_PROCESS .
293 indicates that the driver is able to handle asymmetric requests passed to
294 .Fn CRYPTODEV_KPROCESS .
299 prepares an authentication context to generate the inner hash of an HMAC.
301 is a software implementation of an authentication algorithm such as the
303 .Fn crypto_auth_hash .
305 is a pointer to a HMAC key of
309 points to a valid authentication context for the desired algorithm.
310 The function initializes the context with the supplied key.
315 except that it prepares an authentication context to generate the
316 outer hash of an HMAC.
319 returns the return value from the caller-supplied callback function.
321 .Fn crypto_contiguous_subsegment
322 returns a pointer to a contiguous segment or
325 .Fn crypto_get_driverid
326 returns a driver identifier on success or -1 on error.
329 .Fn crypto_unregister_all ,
330 .Fn CRYPTODEV_FREESESSION ,
331 .Fn CRYPTODEV_NEWSESSION ,
333 .Fn CRYPTODEV_PROCESS
334 return zero on success or an error on failure.
336 .Fn CRYPTODEV_PROBESESSION
337 returns a negative value on success or an error on failure.
341 .Xr crypto_buffer 9 ,
342 .Xr crypto_request 9 ,