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