diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/SSL_write.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/SSL_write.3 | 210 |
1 files changed, 91 insertions, 119 deletions
diff --git a/secure/lib/libcrypto/man/man3/SSL_write.3 b/secure/lib/libcrypto/man/man3/SSL_write.3 index f7e62b0169f3..867c650af27e 100644 --- a/secure/lib/libcrypto/man/man3/SSL_write.3 +++ b/secure/lib/libcrypto/man/man3/SSL_write.3 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .ft R .fi .. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' . ds C` . ds C' 'br\} @@ -68,144 +52,130 @@ . \} .\} .rr rF -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "SSL_WRITE 3ossl" -.TH SSL_WRITE 3ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH SSL_WRITE 3ossl 2025-07-01 3.5.1 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh -.SH "NAME" -SSL_write_ex, SSL_write, SSL_sendfile \- write bytes to a TLS/SSL connection -.SH "SYNOPSIS" +.SH NAME +SSL_write_ex2, SSL_write_ex, SSL_write, SSL_sendfile, SSL_WRITE_FLAG_CONCLUDE \- +write bytes to a TLS/SSL connection +.SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/ssl.h> \& +\& #define SSL_WRITE_FLAG_CONCLUDE +\& \& ossl_ssize_t SSL_sendfile(SSL *s, int fd, off_t offset, size_t size, int flags); +\& int SSL_write_ex2(SSL *s, const void *buf, size_t num, +\& uint64_t flags, +\& size_t *written); \& int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written); \& int SSL_write(SSL *ssl, const void *buf, int num); .Ve -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBSSL_write_ex()\fR and \fBSSL_write()\fR write \fBnum\fR bytes from the buffer \fBbuf\fR into the specified \fBssl\fR connection. On success \fBSSL_write_ex()\fR will store the number of bytes written in \fB*written\fR. .PP +\&\fBSSL_write_ex2()\fR functions similarly to \fBSSL_write_ex()\fR but can also accept +optional flags which modify its behaviour. Calling \fBSSL_write_ex2()\fR with a +\&\fIflags\fR argument of 0 is exactly equivalent to calling \fBSSL_write_ex()\fR. +.PP \&\fBSSL_sendfile()\fR writes \fBsize\fR bytes from offset \fBoffset\fR in the file -descriptor \fBfd\fR to the specified \s-1SSL\s0 connection \fBs\fR. This function provides +descriptor \fBfd\fR to the specified SSL connection \fBs\fR. This function provides efficient zero-copy semantics. \fBSSL_sendfile()\fR is available only when -Kernel \s-1TLS\s0 is enabled, which can be checked by calling \fBBIO_get_ktls_send()\fR. +Kernel TLS is enabled, which can be checked by calling \fBBIO_get_ktls_send()\fR. It is provided here to allow users to maintain the same interface. The meaning of \fBflags\fR is platform dependent. Currently, under Linux it is ignored. -.SH "NOTES" +.PP +The \fIflags\fR argument to \fBSSL_write_ex2()\fR can accept zero or more of the +following flags. Note that which flags are supported will depend on the kind of +SSL object and underlying protocol being used: +.IP \fBSSL_WRITE_FLAG_CONCLUDE\fR 4 +.IX Item "SSL_WRITE_FLAG_CONCLUDE" +This flag is only supported on QUIC stream SSL objects (or QUIC connection SSL +objects with a default stream attached). +.Sp +If this flag is set, and the call to \fBSSL_write_ex2()\fR succeeds, and all of the +data passed to the call is written (meaning that \f(CW\*(C`*written == num\*(C'\fR), the +relevant QUIC stream's send part is concluded automatically as though +\&\fBSSL_stream_conclude\fR\|(3) was called (causing transmission of a FIN for the +stream). +.Sp +While using this flag is semantically equivalent to calling +\&\fBSSL_stream_conclude\fR\|(3) after a successful call to this function, using this +flag enables greater efficiency than making these two API calls separately, as +it enables the written stream data and the FIN flag indicating the end of the +stream to be scheduled as part of the same QUIC STREAM frame and QUIC packet. +.Sp +Setting this flag does not cause a stream's send part to be concluded if not all +of the data passed to the call was consumed. +.PP +A call to \fBSSL_write_ex2()\fR fails if a flag is passed which is not supported or +understood by the given SSL object. An application should determine if a flag is +supported (for example, for \fBSSL_WRITE_FLAG_CONCLUDE\fR, that a QUIC stream SSL +object is being used) before attempting to use it. +.SH NOTES .IX Header "NOTES" -In the paragraphs below a \*(L"write function\*(R" is defined as one of either +In the paragraphs below a "write function" is defined as one of either \&\fBSSL_write_ex()\fR, or \fBSSL_write()\fR. .PP -If necessary, a write function will negotiate a \s-1TLS/SSL\s0 session, if not already +If necessary, a write function will negotiate a TLS/SSL session, if not already explicitly performed by \fBSSL_connect\fR\|(3) or \fBSSL_accept\fR\|(3). If the peer requests a re-negotiation, it will be performed transparently during the write function operation. The behaviour of the write functions depends on the -underlying \s-1BIO.\s0 +underlying BIO. .PP For the transparent negotiation to succeed, the \fBssl\fR must have been initialized to client or server mode. This is being done by calling \&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state()\fR before the first call to a write function. .PP -If the underlying \s-1BIO\s0 is \fBblocking\fR, the write functions will only return, once +If the underlying BIO is \fBblocking\fR, the write functions will only return, once the write operation has been finished or an error occurred. .PP -If the underlying \s-1BIO\s0 is \fBnonblocking\fR the write functions will also return -when the underlying \s-1BIO\s0 could not satisfy the needs of the function to continue +If the underlying BIO is \fBnonblocking\fR the write functions will also return +when the underlying BIO could not satisfy the needs of the function to continue the operation. In this case a call to \fBSSL_get_error\fR\|(3) with the -return value of the write function will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR -or \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. As at any time a re-negotiation is possible, a +return value of the write function will yield \fBSSL_ERROR_WANT_READ\fR +or \fBSSL_ERROR_WANT_WRITE\fR. As at any time a re-negotiation is possible, a call to a write function can also cause read operations! The calling process then must repeat the call after taking appropriate action to satisfy the needs -of the write function. The action depends on the underlying \s-1BIO.\s0 When using a +of the write function. The action depends on the underlying BIO. When using a nonblocking socket, nothing is to be done, but \fBselect()\fR can be used to check -for the required condition. When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data -must be written into or retrieved out of the \s-1BIO\s0 before being able to continue. +for the required condition. When using a buffering BIO, like a BIO pair, data +must be written into or retrieved out of the BIO before being able to continue. .PP The write functions will only return with success when the complete contents of \&\fBbuf\fR of length \fBnum\fR has been written. This default behaviour can be changed -with the \s-1SSL_MODE_ENABLE_PARTIAL_WRITE\s0 option of \fBSSL_CTX_set_mode\fR\|(3). When +with the SSL_MODE_ENABLE_PARTIAL_WRITE option of \fBSSL_CTX_set_mode\fR\|(3). When this flag is set the write functions will also return with success when a partial write has been successfully completed. In this case the write function operation is considered completed. The bytes are sent and a new write call with a new buffer (with the already sent bytes removed) must be started. A partial write is performed with the size of a message block, which is 16kB. -.SH "WARNINGS" +.PP +When used with a QUIC SSL object, calling an I/O function such as \fBSSL_write()\fR +allows internal network event processing to be performed. It is important that +this processing is performed regularly. If an application is not using thread +assisted mode, an application should ensure that an I/O function such as +\&\fBSSL_write()\fR is called regularly, or alternatively ensure that \fBSSL_handle_events()\fR +is called regularly. See \fBopenssl\-quic\fR\|(7) and \fBSSL_handle_events\fR\|(3) for more +information. +.SH WARNINGS .IX Header "WARNINGS" When a write function call has to be repeated because \fBSSL_get_error\fR\|(3) -returned \fB\s-1SSL_ERROR_WANT_READ\s0\fR or \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR, it must be repeated +returned \fBSSL_ERROR_WANT_READ\fR or \fBSSL_ERROR_WANT_WRITE\fR, it must be repeated with the same arguments. The data that was passed might have been partially processed. -When \fB\s-1SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\s0\fR was set using \fBSSL_CTX_set_mode\fR\|(3) +When \fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR was set using \fBSSL_CTX_set_mode\fR\|(3) the pointer can be different, but the data and length should still be the same. .PP You should not call \fBSSL_write()\fR with num=0, it will return an error. @@ -213,22 +183,23 @@ You should not call \fBSSL_write()\fR with num=0, it will return an error. the peer. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fBSSL_write_ex()\fR will return 1 for success or 0 for failure. Success means that -all requested application data bytes have been written to the \s-1SSL\s0 connection or, -if \s-1SSL_MODE_ENABLE_PARTIAL_WRITE\s0 is in use, at least 1 application data byte has -been written to the \s-1SSL\s0 connection. Failure means that not all the requested -bytes have been written yet (if \s-1SSL_MODE_ENABLE_PARTIAL_WRITE\s0 is not in use) or -no bytes could be written to the \s-1SSL\s0 connection (if -\&\s-1SSL_MODE_ENABLE_PARTIAL_WRITE\s0 is in use). Failures can be retryable (e.g. the -network write buffer has temporarily filled up) or non-retryable (e.g. a fatal -network error). In the event of a failure call \fBSSL_get_error\fR\|(3) to find out -the reason which indicates whether the call is retryable or not. +\&\fBSSL_write_ex()\fR and \fBSSL_write_ex2()\fR return 1 for success or 0 for failure. +Success means that all requested application data bytes have been written to the +SSL connection or, if SSL_MODE_ENABLE_PARTIAL_WRITE is in use, at least 1 +application data byte has been written to the SSL connection. Failure means that +not all the requested bytes have been written yet (if +SSL_MODE_ENABLE_PARTIAL_WRITE is not in use) or no bytes could be written to the +SSL connection (if SSL_MODE_ENABLE_PARTIAL_WRITE is in use). Failures can be +retryable (e.g. the network write buffer has temporarily filled up) or +non-retryable (e.g. a fatal network error). In the event of a failure call +\&\fBSSL_get_error\fR\|(3) to find out the reason which indicates whether the call is +retryable or not. .PP For \fBSSL_write()\fR the following return values can occur: .IP "> 0" 4 .IX Item "> 0" The write operation was successful, the return value is the number of -bytes actually written to the \s-1TLS/SSL\s0 connection. +bytes actually written to the TLS/SSL connection. .IP "<= 0" 4 .IX Item "<= 0" The write operation was not successful, because either the connection was @@ -243,7 +214,7 @@ For \fBSSL_sendfile()\fR, the following return values can occur: .IP ">= 0" 4 .IX Item ">= 0" The write operation was successful, the return value is the number -of bytes of the file written to the \s-1TLS/SSL\s0 connection. The return +of bytes of the file written to the TLS/SSL connection. The return value can be less than \fBsize\fR for a partial write. .IP "< 0" 4 .IX Item "< 0" @@ -257,15 +228,16 @@ Call \fBSSL_get_error()\fR with the return value to find out the reason. \&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3) \&\fBSSL_set_connect_state\fR\|(3), \fBBIO_ctrl\fR\|(3), \&\fBssl\fR\|(7), \fBbio\fR\|(7) -.SH "HISTORY" +.SH HISTORY .IX Header "HISTORY" The \fBSSL_write_ex()\fR function was added in OpenSSL 1.1.1. The \fBSSL_sendfile()\fR function was added in OpenSSL 3.0. -.SH "COPYRIGHT" +The \fBSSL_write_ex2()\fR function was added in OpenSSL 3.3. +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy -in the file \s-1LICENSE\s0 in the source distribution or at +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |