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 105Symmetric cryptographic requests use data buffers to describe the data to 106be modified. 107Requests can either specify a single data buffer whose contents are modified 108in place, 109or requests may specify separate data buffers for input and output. 110.Vt struct crypto_buffer 111provides an abstraction that permits cryptographic requests to operate on 112different types of buffers. 113.Vt struct crypto_cursor 114allows cryptographic drivers to iterate over a data buffer. 115.Pp 116.Fn CRYPTO_HAS_OUTPUT_BUFFER 117returns true if 118.Fa crp 119uses separate buffers for input and output and false if 120.Fa crp 121uses a single buffer. 122.Pp 123.Fn crypto_buffer_len 124returns the length of data buffer 125.Fa cb 126in bytes. 127.Pp 128.Fn crypto_apply_buf 129invokes a caller-supplied function 130to a region of the data buffer 131.Fa cb . 132The function 133.Fa f 134is called one or more times. 135For each invocation, 136the first argument to 137.Fa f 138is the value of 139.Fa arg 140passed to 141.Fn crypto_apply_buf . 142The second and third arguments to 143.Fa f 144are a pointer and length to a segment of the buffer mapped into the kernel. 145The function is called enough times to cover the 146.Fa len 147bytes of the data buffer which starts at an offset 148.Fa off . 149If any invocation of 150.Fa f 151returns a non-zero value, 152.Fn crypto_apply_buf 153immediately returns that value without invoking 154.Fa f 155on any remaining segments of the region, 156otherwise 157.Fn crypto_apply_buf 158returns the value from the final call to 159.Fa f . 160.Fn crypto_apply 161invokes the callback 162.Fa f 163on a region of the input data buffer for 164.Fa crp . 165.Pp 166.Fn crypto_buffer_contiguous_subsegment 167attempts to locate a single, virtually-contiguous segment of the data buffer 168.Fa cb . 169The segment must be 170.Fa len 171bytes long and start at an offset of 172.Fa skip 173bytes. 174If a segment is found, 175a pointer to the start of the segment is returned. 176Otherwise, 177.Dv NULL 178is returned. 179.Fn crypto_contiguous_subsegment 180attempts to locate a single, virtually-contiguous segment in the input data 181buffer for 182.Fa crp . 183.Ss Data Buffers 184Data buffers are described by an instance of 185.Vt struct crypto buffer . 186The 187.Fa cb_type 188member contains the type of the data buffer. 189The following types are supported: 190.Bl -tag -width " CRYPTO_BUF_CONTIG" 191.It Dv CRYPTO_BUF_NONE 192An invalid buffer. 193Used to mark the output buffer when a crypto request uses a single data buffer. 194.It Dv CRYPTO_BUF_CONTIG 195An array of bytes mapped into the kernel's address space. 196.It Dv CRYPTO_BUF_UIO 197A scatter/gather list of kernel buffers as described in 198.Xr uio 9 . 199.It Dv CRYPTO_BUF_MBUF 200A chain of network memory buffers as described in 201.Xr mbuf 9 . 202.It Dv CRYPTO_BUF_SINGLE_MBUF 203A single network memory buffer as described in 204.Xr mbuf 9 . 205.It Dv CRYPTO_BUF_VMPAGE 206A scatter/gather list of 207.Vt vm_page_t 208structures describing pages in the kernel's address space. 209This buffer type is only available if 210.Dv CRYPTO_HAS_VMPAGE 211is true. 212.El 213.Pp 214The structure also contains the following type-specific fields: 215.Bl -tag -width " cb_vm_page_offset" 216.It Fa cb_buf 217A pointer to the start of a 218.Dv CRYPTO_BUF_CONTIG 219data buffer. 220.It Fa cb_buf_len 221The length of a 222.Dv CRYPTO_BUF_CONTIG 223data buffer 224.It Fa cb_mbuf 225A pointer to a 226.Vt struct mbuf 227for 228.Dv CRYPTO_BUF_MBUF 229and 230.Dv CRYPTO_BUF_SINGLE_MBUF . 231.It Fa cb_uio 232A pointer to a 233.Vt struct uio 234for 235.Dv CRYPTO_BUF_UIO . 236.It Fa cb_vm_page 237A pointer to an array of 238.Vt struct vm_page 239for 240.Dv CRYPTO_BUF_VMPAGE . 241.It Fa cb_vm_page_len 242The total amount of data included in the 243.Fa cb_vm_page 244array, in bytes. 245.It Fa cb_vm_page_offset 246Offset in bytes in the first page of 247.Fa cb_vm_page 248where valid data begins. 249.El 250.Ss Cursors 251Cursors provide a mechanism for iterating over a data buffer. 252They are primarily intended for use in software drivers which access data 253buffers via virtual addresses. 254.Pp 255.Fn crypto_cursor_init 256initializes the cursor 257.Fa cc 258to reference the start of the data buffer 259.Fa cb . 260.Pp 261.Fn crypto_cursor_advance 262advances the cursor 263.Fa amount 264bytes forward in the data buffer. 265.Pp 266.Fn crypto_cursor_copyback 267copies 268.Fa size 269bytes from the local buffer pointed to by 270.Fa src 271into the data buffer associated with 272.Fa cc . 273The bytes are written to the current position of 274.Fa cc , 275and the cursor is then advanced by 276.Fa size 277bytes. 278.Pp 279.Fn crypto_cursor_copydata 280copies 281.Fa size 282bytes out of the data buffer associated with 283.Fa cc 284into a local buffer pointed to by 285.Fa dst . 286The bytes are read from the current position of 287.Fa cc , 288and the cursor is then advanced by 289.Fa size 290bytes. 291.Pp 292.Fn crypto_cursor_copydata_noadv 293is similar to 294.Fn crypto_cursor_copydata 295except that it does not change the current position of 296.Fa cc . 297.Pp 298.Fn crypto_cursor_segment 299returns the start of the virtually-contiguous segment at the current position of 300.Fa cc . 301The length of the segment is stored in 302.Fa len . 303.Pp 304.Fn crypto_cursor_segbase 305and 306.Fn crypto_cursor_seglen 307return the start and length, respectively, 308of the virtually-contiguous segment at the current position of 309.Fa cc . 310.Sh RETURN VALUES 311.Fn crypto_apply 312and 313.Fn crypto_apply_buf 314return 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 , 319and 320.Fn crypto_cursor_segment 321return a pointer to a contiguous segment or 322.Dv NULL . 323.Pp 324.Fn crypto_buffer_len 325returns the length of a buffer in bytes. 326.Pp 327.Fn crypto_cursor_seglen 328returns the length in bytes of a contiguous segment. 329.Pp 330.Fn CRYPTO_HAS_OUTPUT_BUFFER 331returns 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 343The 344.Nm 345functions first appeared in 346.Fx 13 . 347.Sh AUTHORS 348The 349.Nm 350functions and this manual page were written by 351.An John Baldwin Aq Mt jhb@FreeBSD.org . 352