1.\" $OpenBSD: BIO_s_datagram.3,v 1.3 2023/04/28 16:49:00 schwarze Exp $ 2.\" 3.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 28 2023 $ 18.Dt BIO_S_DATAGRAM 3 19.Os 20.Sh NAME 21.Nm BIO_s_datagram , 22.Nm BIO_new_dgram , 23.Nm BIO_dgram_set_peer , 24.Nm BIO_ctrl_dgram_connect , 25.Nm BIO_dgram_get_peer , 26.Nm BIO_ctrl_set_connected , 27.Nm BIO_dgram_recv_timedout , 28.Nm BIO_dgram_send_timedout , 29.Nm BIO_dgram_non_fatal_error 30.\" .Nm BIO_CTRL_DGRAM_QUERY_MTU and 31.\" .Nm BIO_CTRL_DGRAM_MTU_DISCOVER are intentionally undocumented. 32.\" They are almost unused, and OpenBSD does not appear to support them. 33.Nd datagram socket BIO 34.Sh SYNOPSIS 35.In openssl/bio.h 36.Ft const BIO_METHOD * 37.Fn BIO_s_datagram void 38.Ft BIO * 39.Fo BIO_new_dgram 40.Fa "int fd" 41.Fa "int close_flag" 42.Fc 43.Ft int 44.Fo BIO_dgram_set_peer 45.Fa "BIO *b" 46.Fa "struct sockaddr *sa" 47.Fc 48.Ft int 49.Fo BIO_ctrl_dgram_connect 50.Fa "BIO *b" 51.Fa "struct sockaddr *sa" 52.Fc 53.Ft int 54.Fo BIO_dgram_get_peer 55.Fa "BIO *b" 56.Fa "struct sockaddr *sa" 57.Fc 58.Ft int 59.Fo BIO_ctrl_set_connected 60.Fa "BIO *b" 61.Fa "long argl" 62.Fa "struct sockaddr *sa" 63.Fc 64.Ft int 65.Fn BIO_dgram_recv_timedout "BIO *b" 66.Ft int 67.Fn BIO_dgram_send_timedout "BIO *b" 68.Ft int 69.Fn BIO_dgram_non_fatal_error "int errnum" 70.Sh DESCRIPTION 71.Fn BIO_s_datagram 72returns the datagram socket BIO method. 73The usual application is to transmit data using the IPv4 or IPv6 74.Xr udp 4 75protocol. 76.Pp 77When called on a datagram socket BIO object, 78.Xr BIO_method_type 3 79returns the constant 80.Dv BIO_TYPE_DGRAM 81and 82.Xr BIO_method_name 3 83returns a pointer to the static string 84.Qq datagram socket . 85.Ss Constructors and destructors 86.Xr BIO_new 3 87allocates a new datagram socket BIO object and initializes all its data 88to zero, including the datagram socket file descriptor, the peer address, 89the init flag that can be retrieved with 90.Xr BIO_get_init 3 , 91the connected flag, the MTU, and all timeout and error information. 92The reference count and the close flag are set to 1. 93.Pp 94.Fn BIO_new_dgram 95allocates and initializes a new datagram socket BIO object with 96.Xr BIO_new 3 , 97sets the datagram socket file descriptor and the close flag 98according to its arguments, and sets the init flag to 1. 99.Pp 100If the reference count reaches 0 in 101.Xr BIO_free 3 102and the close and init flags are set, 103.Xr shutdown 2 104and 105.Xr close 2 106are called on the datagram socket file descriptor before freeing the 107storage used by the BIO object. 108.Pp 109When a chain containing a datagram socket BIO is copied with 110.Xr BIO_dup_chain 3 , 111the datagram socket file descriptor, the init flag, the close flag, 112the flags accessible with 113.Xr BIO_test_flags 3 , 114and any data that was set with 115.Xr BIO_set_ex_data 3 116are automatically copied from the original BIO object to the new one, 117but the peer address, the connected flag, the MTU and all timeout and 118error information are not copied but instead initialized to zero. 119.Ss Initialization and configuration 120If the close flag is set in 121.Fa b , 122.Xr BIO_set_fd 3 123clears all flags that are set in 124.Fa b 125and if the init flag was set, it calls 126.Xr shutdown 2 127and 128.Xr close 2 129on the previously assigned file descriptor. 130In any case, 131.Xr BIO_set_fd 3 132then sets the new file descriptor and the new close flag according to 133its arguments and sets the init flag to 1. 134.Pp 135If the init flag is set in 136.Fa b , 137.Xr BIO_get_fd 3 138returns its datagram socket file descriptor, and unless the 139.Fa c 140argument is a 141.Dv NULL 142pointer, it also stores the file descriptor in 143.Pf * Fa c . 144If the init flag is not set, 145.Xr BIO_get_fd 3 146fails and returns \-1. 147.Pp 148.Xr BIO_set_close 3 149sets the close flag in 150.Fa b 151to the 152.Fa flag 153argument. 154.Xr BIO_get_close 3 155returns the value of the close flag from 156.Fa b . 157.Pp 158For datagram socket BIO objects, 159the shutdown flag is the same flag as the close flag. 160Consequently, 161.Xr BIO_set_shutdown 3 162has the same effect as 163.Xr BIO_set_close 3 164and 165.Xr BIO_get_shutdown 3 166has the same effect as 167.Xr BIO_get_close 3 . 168.Pp 169.Fn BIO_dgram_set_peer 170copies 171.Fa sa 172as the peer address into 173.Fa b . 174.Pp 175.Fn BIO_ctrl_dgram_connect 176does exactly the same as 177.Fn BIO_dgram_set_peer . 178Its name is even more misleading than the name of 179.Fn BIO_ctrl_set_connected . 180In addition to what is said there, 181.Fn BIO_ctrl_dgram_connect 182does not even set the connected flag in 183.Fa b . 184.Pp 185.Fn BIO_dgram_get_peer 186copies the peer address from 187.Fa b 188to 189.Pf * Fa sa . 190Before calling this function, the caller has to make sure 191that the peer address is indeed set in 192.Fa b 193and that sufficient memory is available starting at 194.Fa sa 195to copy a complete 196.Vt struct sockaddr , 197.Vt struct sockaddr_in , 198or 199.Vt struct sockaddr_in6 200to that place, depending on which address family 201.Fa b 202is currently used for. 203.Pp 204Unless 205.Fa sa 206is 207.Dv NULL , 208.Fn BIO_ctrl_set_connected 209sets the connected flag in 210.Fa b 211and copies 212.Fa sa 213as the peer address into 214.Fa b . 215If 216.Fa sa 217is 218.Dv NULL , 219.Fn BIO_ctrl_set_connected 220clears the connected flag and the peer address in 221.Fa b . 222Considering that communication using a datagram protocol is connectionless, 223the name of this function is misleading. 224It is neither establishing or terminating a connection nor changing 225anything with respect to the state of the datagram socket, but merely 226modifying some purely informational data in the wrapping BIO object. 227The additional 228.Fa argl 229argument is passed through to the callbacks documented in 230.Xr BIO_set_callback 3 231if any such callbacks are installed, but it is otherwise ignored. 232.Pp 233.Xr BIO_ctrl 3 234with a 235.Fa cmd 236of 237.Dv BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT 238interprets the 239.Fa parg 240argument as a pointer to a 241.Vt struct timeval 242and sets the read timeout to the specified absolute UTC time. 243.Pp 244.Xr BIO_ctrl 3 245with a 246.Fa cmd 247of 248.Dv BIO_CTRL_DGRAM_SET_RECV_TIMEOUT , 249.Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT , 250.Dv BIO_CTRL_DGRAM_SET_SEND_TIMEOUT , 251or 252.Dv BIO_CTRL_DGRAM_GET_SEND_TIMEOUT 253interprets the 254.Fa parg 255argument as a pointer to a 256.Vt struct timeval 257and calls 258.Xr setsockopt 2 259or 260.Xr getsockopt 2 261on the datagram socket file descriptor of 262.Fa b 263with an argument of 264.Dv SO_RCVTIMEO 265or 266.Dv SO_SNDTIMEO , 267respectively. 268.Dv BIO_CTRL_DGRAM_SET_RECV_TIMEOUT 269and 270.Dv BIO_CTRL_DGRAM_SET_SEND_TIMEOUT 271return 1 on success, 272.Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT 273and 274.Dv BIO_CTRL_DGRAM_GET_SEND_TIMEOUT 275the number of bytes written to 276.Pf * Fa parg . 277All four return \-1 on failure. 278Remember that 279.Xr BIO_read 3 280may actually use a shorter timeout when 281.Dv BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT 282is in effect. 283.Pp 284.Xr BIO_ctrl 3 285with a 286.Fa cmd 287of 288.Dv BIO_CTRL_DGRAM_GET_FALLBACK_MTU 289returns 1232 if the peer address is an IPv6 address that is not IPv4 mapped 290or 548 otherwise. 291Making sure that a peer address is set before issuing this command 292is the responsibility of the caller. 293.Pp 294.Xr BIO_ctrl 3 295with a 296.Fa cmd 297of 298.Dv BIO_CTRL_DGRAM_SET_MTU 299sets the MTU attribute of 300.Fa b 301to the value of the 302.Fa larg 303argument and also returns that argument. 304.Xr BIO_ctrl 3 305with a 306.Fa cmd 307of 308.Dv BIO_CTRL_DGRAM_GET_MTU 309returns the MTU attribute of 310.Fa b 311or 0 if it was not set. 312.Pp 313.Xr BIO_ctrl 3 314with a 315.Fa cmd 316of 317.Dv BIO_CTRL_DGRAM_MTU_EXCEEDED 318returns 1 if the most recent non-fatal failure of 319.Xr BIO_read 3 320or 321.Xr BIO_write 3 322was caused by 323.Er EMSGSIZE 324or 0 otherwise. 325This command also clears the 326.Xr errno 2 327value that was saved internally for this particular purpose, so that 328issuing the same command again will return 0 until the next 329.Er EMSGSIZE 330failure occurs. 331.Pp 332.Fn BIO_dgram_recv_timedout 333and 334.Fn BIO_dgram_send_timedout 335check whether the most recent non-fatal failure of 336.Xr BIO_read 3 337or 338.Xr BIO_write 3 339was caused by 340.Er EAGAIN . 341Despite having different names, both functions do exactly the same, 342and both inspect the most recent non-fatal I/O failure, no matter 343whether it occurred during a receive or send operation. 344Both functions also clear the 345.Xr errno 2 346value that was saved internally for this particular purpose, 347so that calling these functions again will return 0 until the next 348.Er EAGAIN 349failure occurs. 350.Pp 351Datagram socket BIOs do not support 352.Xr BIO_eof 3 , 353.Xr BIO_get_mem_data 3 , 354.Xr BIO_pending 3 , 355.Xr BIO_reset 3 , 356.Xr BIO_seek 3 , 357.Xr BIO_tell 3 , 358and 359.Xr BIO_wpending 3 , 360and attempting any such operation results in failure 361and returns a value of 0. 362.Pp 363Control commands correspond to accessor functions as follows: 364.Pp 365.Bl -tag -width BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP -compact 366.It Dv BIO_C_GET_FD 367.Xr BIO_get_fd 3 368.It Dv BIO_C_SET_FD 369.Xr BIO_set_fd 3 370.It Dv BIO_CTRL_DGRAM_CONNECT 371.Fn BIO_ctrl_dgram_connect Pq deprecated 372.It Dv BIO_CTRL_DGRAM_GET_PEER 373.Fn BIO_dgram_get_peer 374.It BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP 375.Fn BIO_dgram_recv_timedout 376.It BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP 377.Fn BIO_dgram_send_timedout 378.It Dv BIO_CTRL_DGRAM_SET_CONNECTED 379.Fn BIO_ctrl_set_connected 380.It Dv BIO_CTRL_DGRAM_SET_PEER 381.Fn BIO_dgram_set_peer 382.It Dv BIO_CTRL_GET_CLOSE 383.Xr BIO_get_close 3 384.It Dv BIO_CTRL_SET_CLOSE 385.Xr BIO_set_close 3 386.El 387.Ss Input and output operations 388.Xr BIO_read 3 389attempts to read up to 390.Fa len 391bytes into 392.Fa buf 393from the datagram socket file descriptor using 394.Xr recvfrom 2 . 395If a read timeout is set, 396.Xr setsockopt 2 397is used with an argument of 398.Dv SO_RCVTIMEO 399to temporarily shorten the timeout on the datagram socket during the 400.Xr recvfrom 2 401call such that it returns before the read timeout expires. 402.Pp 403If 404.Xr recvfrom 2 405succeeds and the connected flag is not yet set, 406.Xr BIO_read 3 407also copies the peer address received from 408.Xr recvfrom 2 409into 410.Fa b . 411.Pp 412If 413.Xr recvfrom 2 414is attempted, 415.Xr BIO_read 3 416clears the flags 417.Dv BIO_FLAGS_WRITE 418and 419.Dv BIO_FLAGS_IO_SPECIAL 420in 421.Fa b 422and clears or sets the flags 423.Dv BIO_FLAGS_READ 424and 425.Dv BIO_FLAGS_SHOULD_RETRY 426as appropriate. 427.Pp 428If the connected flag is set in 429.Fa b , 430.Xr BIO_write 3 431attempts to 432.Xr write 2 433.Fa len 434bytes from 435.Fa buf 436to the datagram socket file descriptor. 437If the connected flag is not set, it attempts to transmit 438.Fa len 439bytes from 440.Fa buf 441to the peer using 442.Xr sendto 2 . 443.Pp 444If 445.Xr write 2 446or 447.Xr sendto 2 448is attempted, 449.Xr BIO_write 3 450clears the flags 451.Dv BIO_FLAGS_READ 452and 453.Dv BIO_FLAGS_IO_SPECIAL 454in 455.Fa b 456and clears or sets the flags 457.Dv BIO_FLAGS_WRITE 458and 459.Dv BIO_FLAGS_SHOULD_RETRY 460as appropriate. 461.Pp 462The effect of 463.Xr BIO_puts 3 464is similar to the effect of 465.Xr BIO_write 3 466with a 467.Fa len 468argument of 469.Fn strlen string . 470.Pp 471Datagram socket BIOs do not support 472.Xr BIO_gets 3 . 473Calling this function fails and returns \-2. 474.Pp 475.Xr BIO_flush 3 476has no effect on a datagram socket BIO. 477It always succeeds and returns 1. 478.Sh RETURN VALUES 479.Fn BIO_s_datagram 480returns the datagram socket BIO method. 481.Pp 482.Fn BIO_new_dgram 483returns a newly allocated datagram socket BIO object or 484.Dv NULL 485on failure. 486.Pp 487.Fn BIO_dgram_set_peer , 488.Fn BIO_ctrl_dgram_connect , 489and 490.Fn BIO_ctrl_set_connected 491return 1 on success or a value less than or equal to zero on failure. 492They can only fail if 493.Fa b 494is not a datagram socket BIO object. 495.Pp 496.Fn BIO_dgram_get_peer 497returns the number of bytes copied to 498.Fa sa 499or a value less than or equal to zero on failure. 500It can only fail if 501.Fa b 502is not a datagram socket BIO object. 503.Pp 504.Fn BIO_dgram_recv_timedout 505and 506.Fn BIO_dgram_send_timedout 507return 1 if the most recent non-fatal I/O error was caused by 508.Er EAGAIN 509or 0 otherwise. 510.Pp 511.Fn BIO_dgram_non_fatal_error 512returns 1 if 513.Fa errnum 514is 515.Er EAGAIN , 516.Er EALREADY , 517.Er EINPROGRESS , 518or 519.Er EINTR 520or 0 otherwise, even if 521.Fa errnum 522is 0. 523.Sh SEE ALSO 524.Xr close 2 , 525.Xr getsockopt 2 , 526.Xr recvfrom 2 , 527.Xr sendto 2 , 528.Xr shutdown 2 , 529.Xr BIO_ctrl 3 , 530.Xr BIO_get_init 3 , 531.Xr BIO_new 3 , 532.Xr BIO_read 3 , 533.Xr BIO_s_connect 3 , 534.Xr BIO_set_fd 3 , 535.Xr BIO_should_retry 3 , 536.Xr udp 4 537.Sh HISTORY 538.Fn BIO_s_datagram , 539.Fn BIO_new_dgram , 540.Fn BIO_dgram_set_peer , 541.Fn BIO_ctrl_dgram_connect , 542.Fn BIO_ctrl_set_connected , 543.Fn BIO_dgram_recv_timedout , 544.Fn BIO_dgram_send_timedout , 545and 546.Fn BIO_dgram_non_fatal_error 547first appeared in OpenSSL 0.9.8 and have been available since 548.Ox 4.5 . 549.Pp 550.Fn BIO_dgram_get_peer 551first appeared in OpenSSL 0.9.8m and has been available since 552.Ox 4.9 . 553.Sh BUGS 554If 555.Xr getsockopt 2 556or 557.Xr setsockopt 2 558fails during 559.Xr BIO_read 3 , 560the library prints an error message to standard error output 561but otherwise ignores the problem, thus possibly using unintended 562timeout values. 563.Pp 564.Xr BIO_read 3 565and 566.Xr BIO_write 3 567may clear the global variable 568.Xr errno 2 569before attempting the 570.Xr recvfrom 2 571or 572.Xr sendto 2 573system call but may not clear it if they fail before reaching this point. 574