xref: /freebsd/share/man/man9/crypto_driver.9 (revision e5b786625f7f82a1fa91e41823332459ea5550f9)
1.\" Copyright (c) 2020, Chelsio Inc
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions are met:
5.\"
6.\" 1. Redistributions of source code must retain the above copyright notice,
7.\"    this list of conditions and the following disclaimer.
8.\"
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.
12.\"
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.
16.\"
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.
28.\"
29.\" * Other names and brands may be claimed as the property of others.
30.\"
31.Dd April 12, 2021
32.Dt CRYPTO_DRIVER 9
33.Os
34.Sh NAME
35.Nm crypto_driver
36.Nd interface for symmetric cryptographic drivers
37.Sh SYNOPSIS
38.In opencrypto/cryptodev.h
39.Ft void
40.Fn crypto_copyback "struct cryptop *crp" "int off" "int size" "const void *src"
41.Ft void
42.Fn crypto_copydata "struct cryptop *crp" "int off" "int size" "void *dst"
43.Ft void
44.Fn crypto_done "struct cryptop *crp"
45.Ft int32_t
46.Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags"
47.Ft void *
48.Fn crypto_get_driver_session "crypto_session_t crypto_session"
49.Ft void
50.Fn crypto_read_iv "struct cryptop *crp" "void *iv"
51.Ft int
52.Fn crypto_unblock "uint32_t driverid" "int what"
53.Ft int
54.Fn crypto_unregister_all "uint32_t driverid"
55.Ft int
56.Fn CRYPTODEV_FREESESSION "device_t dev" "crypto_session_t crypto_session"
57.Ft int
58.Fo CRYPTODEV_NEWSESSION
59.Fa "device_t dev"
60.Fa "crypto_session_t crypto_session"
61.Fa "const struct crypto_session_params *csp"
62.Fc
63.Ft int
64.Fo CRYPTODEV_PROBESESSION
65.Fa "device_t dev"
66.Fa "const struct crypto_session_params *csp"
67.Fc
68.Ft int
69.Fn CRYPTODEV_PROCESS "device_t dev" "struct cryptop *crp" "int flags"
70.Ft void
71.Fo hmac_init_ipad
72.Fa "struct auth_hash *axf"
73.Fa "const char *key"
74.Fa "int klen"
75.Fa "void *auth_ctx"
76.Fc
77.Ft void
78.Fo hmac_init_opad
79.Fa "struct auth_hash *axf"
80.Fa "const char *key"
81.Fa "int klen"
82.Fa "void *auth_ctx"
83.Fc
84.Sh DESCRIPTION
85Symmetric cryptographic drivers process cryptographic requests
86submitted to sessions associated with the driver.
87.Pp
88Cryptographic drivers call
89.Fn crypto_get_driverid
90to register with the cryptographic framework.
91.Fa dev
92is the device used to service requests.
93The
94.Fn CRYPTODEV
95methods are defined in the method table for the device driver attached to
96.Fa dev .
97.Fa session_size
98specifies the size of a driver-specific per-session structure allocated by
99the cryptographic framework.
100.Fa flags
101is a bitmask of properties about the driver.
102Exactly one of
103.Dv CRYPTOCAP_F_SOFTWARE
104or
105.Dv CRYPTOCAP_F_HARDWARE
106must be specified.
107.Dv CRYPTOCAP_F_SOFTWARE
108should be used for drivers which process requests using host CPUs.
109.Dv CRYPTOCAP_F_HARDWARE
110should be used for drivers which process requests on separate co-processors.
111.Dv CRYPTOCAP_F_SYNC
112should be set for drivers which process requests synchronously in
113.Fn CRYPTODEV_PROCESS .
114.Dv CRYPTOCAP_F_ACCEL_SOFTWARE
115should be set for software drivers which use accelerated CPU instructions.
116.Fn crypto_get_driverid
117returns an opaque driver id.
118.Pp
119.Fn crypto_unregister_all
120unregisters a driver from the cryptographic framework.
121If there are any pending operations or open sessions,
122this function will sleep.
123.Fa driverid
124is the value returned by an earlier call to
125.Fn crypto_get_driverid .
126.Pp
127When a new session is created by
128.Fn crypto_newsession ,
129.Fn CRYPTODEV_PROBESESSION
130is invoked by the cryptographic framework on each active driver to
131determine the best driver to use for the session.
132This method should inspect the session parameters in
133.Fa csp .
134If a driver does not support requests described by
135.Fa csp ,
136this method should return an error value.
137If the driver does support requests described by
138.Fa csp ,
139it should return a negative value.
140The framework prefers drivers with the largest negative value,
141similar to
142.Xr DEVICE_PROBE 9 .
143The following values are defined for non-error return values from this
144method:
145.Bl -tag -width "CRYPTODEV_PROBE_ACCEL_SOFTWARE"
146.It Dv CRYPTODEV_PROBE_HARDWARE
147The driver processes requests via a co-processor.
148.It Dv CRYPTODEV_PROBE_ACCEL_SOFTWARE
149The driver processes requests on the host CPU using optimized instructions
150such as AES-NI.
151.It Dv CRYPTODEV_PROBE_SOFTWARE
152The driver processes requests on the host CPU.
153.El
154.Pp
155This method should not sleep.
156.Pp
157Once the framework has chosen a driver for a session,
158the framework invokes the
159.Fn CRYPTODEV_NEWSESSION
160method to initialize driver-specific session state.
161Prior to calling this method,
162the framework allocates a per-session driver-specific data structure.
163This structure is initialized with zeroes,
164and its size is set by the
165.Fa session_size
166passed to
167.Fn crypto_get_driverid .
168This method can retrieve a pointer to this data structure by passing
169.Fa crypto_session
170to
171.Fn crypto_get_driver_session .
172Session parameters are described in
173.Fa csp .
174.Pp
175This method should not sleep.
176.Pp
177.Fn CRYPTODEV_FREESESSION
178is invoked to release any driver-specific state when a session is
179destroyed.
180The per-session driver-specific data structure is explicitly zeroed
181and freed by the framework after this method returns.
182If a driver requires no additional tear-down steps, it can leave
183this method undefined.
184.Pp
185This method should not sleep.
186.Pp
187.Fn CRYPTODEV_PROCESS
188is invoked for each request submitted to an active session.
189This method can either complete a request synchronously or
190schedule it to be completed asynchronously,
191but it must not sleep.
192.Pp
193If this method is not able to complete a request due to insufficient
194resources such as a full command queue,
195it can defer the request by returning
196.Dv ERESTART .
197The request will be queued by the framework and retried once the
198driver releases pending requests via
199.Fn crypto_unblock .
200Any requests submitted to sessions belonging to the driver will also
201be queued until
202.Fn crypto_unblock
203is called.
204.Pp
205If a driver encounters errors while processing a request,
206it should report them via the
207.Fa crp_etype
208field of
209.Fa crp
210rather than returning an error directly.
211.Pp
212.Fa flags
213may be set to
214.Dv CRYPTO_HINT_MORE
215if there are additional requests queued for this driver.
216The driver can use this as a hint to batch completion interrupts.
217Note that these additional requests may be from different sessions.
218.Pp
219.Fn crypto_get_driver_session
220returns a pointer to the driver-specific per-session data structure
221for the session
222.Fa crypto_session .
223This function can be used in the
224.Fn CRYPTODEV_NEWSESSION ,
225.Fn CRYPTODEV_PROCESS ,
226and
227.Fn CRYPTODEV_FREESESSION
228callbacks.
229.Pp
230.Fn crypto_copydata
231copies
232.Fa size
233bytes out of the input buffer for
234.Fa crp
235into a local buffer pointed to by
236.Fa dst .
237The bytes are read starting at an offset of
238.Fa off
239bytes in the request's input buffer.
240.Pp
241.Fn crypto_copyback
242copies
243.Fa size
244bytes from the local buffer pointed to by
245.Fa src
246into the output buffer for
247.Fa crp .
248The bytes are written starting at an offset of
249.Fa off
250bytes in the request's output buffer.
251.Pp
252.Fn crypto_read_iv
253copies the IV or nonce for
254.Fa crp
255into the local buffer pointed to by
256.Fa iv .
257.Pp
258A driver calls
259.Fn crypto_done
260to mark the request
261.Fa crp
262as completed.
263Any errors should be set in
264.Fa crp_etype
265prior to calling this function.
266.Pp
267If a driver defers a request by returning
268.Dv ERESTART
269from
270.Dv CRYPTO_PROCESS ,
271the framework will queue all requests for the driver until the driver calls
272.Fn crypto_unblock
273to indicate that the temporary resource shortage has been relieved.
274For example,
275if a driver returns
276.Dv ERESTART
277due to a full command ring,
278it would invoke
279.Fn crypto_unblock
280from a command completion interrupt that makes a command ring entry available.
281.Fa driverid
282is the value returned by
283.Fn crypto_get_driverid .
284.Fa what
285indicates which types of requests the driver is able to handle again:
286.Bl -tag -width "CRYPTO_SYMQ"
287.It Dv CRYPTO_SYMQ
288indicates that the driver is able to handle symmetric requests passed to
289.Fn CRYPTODEV_PROCESS .
290.El
291.Pp
292.Fn hmac_init_ipad
293prepares an authentication context to generate the inner hash of an HMAC.
294.Fa axf
295is a software implementation of an authentication algorithm such as the
296value returned by
297.Fn crypto_auth_hash .
298.Fa key
299is a pointer to a HMAC key of
300.Fa klen
301bytes.
302.Fa auth_ctx
303points to a valid authentication context for the desired algorithm.
304The function initializes the context with the supplied key.
305.Pp
306.Fn hmac_init_opad
307is similar to
308.Fn hmac_init_ipad
309except that it prepares an authentication context to generate the
310outer hash of an HMAC.
311.Sh RETURN VALUES
312.Fn crypto_apply
313returns the return value from the caller-supplied callback function.
314.Pp
315.Fn crypto_contiguous_subsegment
316returns a pointer to a contiguous segment or
317.Dv NULL .
318.Pp
319.Fn crypto_get_driverid
320returns a driver identifier on success or -1 on error.
321.Pp
322.Fn crypto_unblock ,
323.Fn crypto_unregister_all ,
324.Fn CRYPTODEV_FREESESSION ,
325.Fn CRYPTODEV_NEWSESSION ,
326and
327.Fn CRYPTODEV_PROCESS
328return zero on success or an error on failure.
329.Pp
330.Fn CRYPTODEV_PROBESESSION
331returns a negative value on success or an error on failure.
332.Sh SEE ALSO
333.Xr crypto 7 ,
334.Xr crypto 9 ,
335.Xr crypto_buffer 9 ,
336.Xr crypto_request 9 ,
337.Xr crypto_session 9
338