share/man/man9/crypto_buffer.9

   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 .\" $FreeBSD$
  32 .\"
  33 .Dd May 25, 2021
  34 .Dt CRYPTO_BUFFER 9
  35 .Os
  36 .Sh NAME
  37 .Nm crypto_buffer
  38 .Nd symmetric cryptographic request buffers
  39 .Sh SYNOPSIS
  40 .In opencrypto/cryptodev.h
  41 .Ft int
  42 .Fo crypto_apply
  43 .Fa "struct cryptop *crp"
  44 .Fa "int off"
  45 .Fa "int len"
  46 .Fa "int (*f)(void *, void *, u_int)"
  47 .Fa "void *arg"
  48 .Fc
  49 .Ft int
  50 .Fo crypto_apply_buf
  51 .Fa "struct crypto_buffer *cb"
  52 .Fa "int off"
  53 .Fa "int len"
  54 .Fa "int (*f)(void *, void *, u_int)"
  55 .Fa "void *arg"
  56 .Fc
  57 .Ft void *
  58 .Fo crypto_buffer_contiguous_subsegment
  59 .Fa "struct crypto_buffer *cb"
  60 .Fa "size_t skip"
  61 .Fa "size_t len"
  62 .Fc
  63 .Ft size_t
  64 .Fn crypto_buffer_len "struct crypto_buffer *cb"
  65 .Ft void *
  66 .Fo crypto_contiguous_subsegment
  67 .Fa "struct cryptop *crp"
  68 .Fa "size_t skip"
  69 .Fa "size_t len"
  70 .Fc
  71 .Ft void
  72 .Fo crypto_cursor_init
  73 .Fa "struct crypto_buffer_cursor *cc"
  74 .Fa "const struct crypto_buffer *cb"
  75 .Fc
  76 .Ft void
  77 .Fn crypto_cursor_advance "struct crypto_buffer_cursor *cc" "size_t amount"
  78 .Ft void
  79 .Fo crypto_cursor_copyback
  80 .Fa "struct crypto_buffer_cursor *cc"
  81 .Fa "int size"
  82 .Fa "const void *src"
  83 .Fc
  84 .Ft void
  85 .Fo crypto_cursor_copydata
  86 .Fa "struct crypto_buffer_cursor *cc"
  87 .Fa "int size"
  88 .Fa "void *dst"
  89 .Fc
  90 .Ft void
  91 .Fo crypto_cursor_copydata_noadv
  92 .Fa "struct crypto_buffer_cursor *cc"
  93 .Fa "int size"
  94 .Fa "void *dst"
  95 .Fc
  96 .Ft void *
  97 .Fn crypto_cursor_segment "struct crypto_buffer_cursor *cc" "size_t *len"
  98 .Ft void *
  99 .Fn crypto_cursor_segbase "struct crypto_buffer_cursor *cc"
 100 .Ft size_t
 101 .Fn crypto_cursor_seglen "struct crypto_buffer_cursor *cc"
 102 .Ft bool
 103 .Fn CRYPTO_HAS_OUTPUT_BUFFER "struct cryptop *crp"
 104 .Sh DESCRIPTION
 105 Symmetric cryptographic requests use data buffers to describe the data to
 106 be modified.
 107 Requests can either specify a single data buffer whose contents are modified
 108 in place,
 109 or requests may specify separate data buffers for input and output.
 110 .Vt struct crypto_buffer
 111 provides an abstraction that permits cryptographic requests to operate on
 112 different types of buffers.
 113 .Vt struct crypto_cursor
 114 allows cryptographic drivers to iterate over a data buffer.
 115 .Pp
 116 .Fn CRYPTO_HAS_OUTPUT_BUFFER
 117 returns true if
 118 .Fa crp
 119 uses separate buffers for input and output and false if
 120 .Fa crp
 121 uses a single buffer.
 122 .Pp
 123 .Fn crypto_buffer_len
 124 returns the length of data buffer
 125 .Fa cb
 126 in bytes.
 127 .Pp
 128 .Fn crypto_apply_buf
 129 invokes a caller-supplied function
 130 to a region of the data buffer
 131 .Fa cb .
 132 The function
 133 .Fa f
 134 is called one or more times.
 135 For each invocation,
 136 the first argument to
 137 .Fa f
 138 is the value of
 139 .Fa arg
 140 passed to
 141 .Fn crypto_apply_buf .
 142 The second and third arguments to
 143 .Fa f
 144 are a pointer and length to a segment of the buffer mapped into the kernel.
 145 The function is called enough times to cover the
 146 .Fa len
 147 bytes of the data buffer which starts at an offset
 148 .Fa off .
 149 If any invocation of
 150 .Fa f
 151 returns a non-zero value,
 152 .Fn crypto_apply_buf
 153 immediately returns that value without invoking
 154 .Fa f
 155 on any remaining segments of the region,
 156 otherwise
 157 .Fn crypto_apply_buf
 158 returns the value from the final call to
 159 .Fa f .
 160 .Fn crypto_apply
 161 invokes the callback
 162 .Fa f
 163 on a region of the input data buffer for
 164 .Fa crp .
 165 .Pp
 166 .Fn crypto_buffer_contiguous_subsegment
 167 attempts to locate a single, virtually-contiguous segment of the data buffer
 168 .Fa cb .
 169 The segment must be
 170 .Fa len
 171 bytes long and start at an offset of
 172 .Fa skip
 173 bytes.
 174 If a segment is found,
 175 a pointer to the start of the segment is returned.
 176 Otherwise,
 177 .Dv NULL
 178 is returned.
 179 .Fn crypto_contiguous_subsegment
 180 attempts to locate a single, virtually-contiguous segment in the input data
 181 buffer for
 182 .Fa crp .
 183 .Ss Data Buffers
 184 Data buffers are described by an instance of
 185 .Vt struct crypto buffer .
 186 The
 187 .Fa cb_type
 188 member contains the type of the data buffer.
 189 The following types are supported:
 190 .Bl -tag -width "  CRYPTO_BUF_CONTIG"
 191 .It Dv CRYPTO_BUF_NONE
 192 An invalid buffer.
 193 Used to mark the output buffer when a crypto request uses a single data buffer.
 194 .It Dv CRYPTO_BUF_CONTIG
 195 An array of bytes mapped into the kernel's address space.
 196 .It Dv CRYPTO_BUF_UIO
 197 A scatter/gather list of kernel buffers as described in
 198 .Xr uio 9 .
 199 .It Dv CRYPTO_BUF_MBUF
 200 A chain of network memory buffers as described in
 201 .Xr mbuf 9 .
 202 .It Dv CRYPTO_BUF_SINGLE_MBUF
 203 A single network memory buffer as described in
 204 .Xr mbuf 9 .
 205 .It Dv CRYPTO_BUF_VMPAGE
 206 A scatter/gather list of
 207 .Vt vm_page_t
 208 structures describing pages in the kernel's address space.
 209 This buffer type is only available if
 210 .Dv CRYPTO_HAS_VMPAGE
 211 is true.
 212 .El
 213 .Pp
 214 The structure also contains the following type-specific fields:
 215 .Bl -tag -width "  cb_vm_page_offset"
 216 .It Fa cb_buf
 217 A pointer to the start of a
 218 .Dv CRYPTO_BUF_CONTIG
 219 data buffer.
 220 .It Fa cb_buf_len
 221 The length of a
 222 .Dv CRYPTO_BUF_CONTIG
 223 data buffer
 224 .It Fa cb_mbuf
 225 A pointer to a
 226 .Vt struct mbuf
 227 for
 228 .Dv CRYPTO_BUF_MBUF
 229 and
 230 .Dv CRYPTO_BUF_SINGLE_MBUF .
 231 .It Fa cb_uio
 232 A pointer to a
 233 .Vt struct uio
 234 for
 235 .Dv CRYPTO_BUF_UIO .
 236 .It Fa cb_vm_page
 237 A pointer to an array of
 238 .Vt struct vm_page
 239 for
 240 .Dv CRYPTO_BUF_VMPAGE .
 241 .It Fa cb_vm_page_len
 242 The total amount of data included in the
 243 .Fa cb_vm_page
 244 array, in bytes.
 245 .It Fa cb_vm_page_offset
 246 Offset in bytes in the first page of
 247 .Fa cb_vm_page
 248 where valid data begins.
 249 .El
 250 .Ss Cursors
 251 Cursors provide a mechanism for iterating over a data buffer.
 252 They are primarily intended for use in software drivers which access data
 253 buffers via virtual addresses.
 254 .Pp
 255 .Fn crypto_cursor_init
 256 initializes the cursor
 257 .Fa cc
 258 to reference the start of the data buffer
 259 .Fa cb .
 260 .Pp
 261 .Fn crypto_cursor_advance
 262 advances the cursor
 263 .Fa amount
 264 bytes forward in the data buffer.
 265 .Pp
 266 .Fn crypto_cursor_copyback
 267 copies
 268 .Fa size
 269 bytes from the local buffer pointed to by
 270 .Fa src
 271 into the data buffer associated with
 272 .Fa cc .
 273 The bytes are written to the current position of
 274 .Fa cc ,
 275 and the cursor is then advanced by
 276 .Fa size
 277 bytes.
 278 .Pp
 279 .Fn crypto_cursor_copydata
 280 copies
 281 .Fa size
 282 bytes out of the data buffer associated with
 283 .Fa cc
 284 into a local buffer pointed to by
 285 .Fa dst .
 286 The bytes are read from the current position of
 287 .Fa cc ,
 288 and the cursor is then advanced by
 289 .Fa size
 290 bytes.
 291 .Pp
 292 .Fn crypto_cursor_copydata_noadv
 293 is similar to
 294 .Fn crypto_cursor_copydata
 295 except that it does not change the current position of
 296 .Fa cc .
 297 .Pp
 298 .Fn crypto_cursor_segment
 299 returns the start of the virtually-contiguous segment at the current position of
 300 .Fa cc .
 301 The length of the segment is stored in
 302 .Fa len .
 303 .Pp
 304 .Fn crypto_cursor_segbase
 305 and
 306 .Fn crypto_cursor_seglen
 307 return the start and length, respectively,
 308 of the virtually-contiguous segment at the current position of
 309 .Fa cc .
 310 .Sh RETURN VALUES
 311 .Fn crypto_apply
 312 and
 313 .Fn crypto_apply_buf
 314 return the return value from the caller-supplied callback function.
 315 .Pp
 316 .Fn crypto_buffer_contiguous_subsegment ,
 317 .Fn crypto_contiguous_subsegment ,
 318 .Fn crypto_cursor_segbase ,
 319 and
 320 .Fn crypto_cursor_segment
 321 return a pointer to a contiguous segment or
 322 .Dv NULL .
 323 .Pp
 324 .Fn crypto_buffer_len
 325 returns the length of a buffer in bytes.
 326 .Pp
 327 .Fn crypto_cursor_seglen
 328 returns the length in bytes of a contiguous segment.
 329 .Pp
 330 .Fn CRYPTO_HAS_OUTPUT_BUFFER
 331 returns true if the request uses a separate output buffer.
 332 .Sh SEE ALSO
 333 .Xr ipsec 4 ,
 334 .Xr crypto 7 ,
 335 .Xr bus_dma 9 ,
 336 .Xr crypto 9 ,
 337 .Xr crypto_driver 9 ,
 338 .Xr crypto_request 9 ,
 339 .Xr crypto_session 9 ,
 340 .Xr mbuf 9 ,
 341 .Xr uio 9
 342 .Sh HISTORY
 343 The
 344 .Nm
 345 functions first appeared in
 346 .Fx 13 .
 347 .Sh AUTHORS
 348 The
 349 .Nm
 350 functions and this manual page were written by
 351 .An John Baldwin Aq Mt jhb@FreeBSD.org .