diff options
Diffstat (limited to 'upstream/debian-unstable/man3/OSSL_HTTP_transfer.3ssl')
| -rw-r--r-- | upstream/debian-unstable/man3/OSSL_HTTP_transfer.3ssl | 22 |
1 files changed, 16 insertions, 6 deletions
diff --git a/upstream/debian-unstable/man3/OSSL_HTTP_transfer.3ssl b/upstream/debian-unstable/man3/OSSL_HTTP_transfer.3ssl index 048969dd..a178ae79 100644 --- a/upstream/debian-unstable/man3/OSSL_HTTP_transfer.3ssl +++ b/upstream/debian-unstable/man3/OSSL_HTTP_transfer.3ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OSSL_HTTP_TRANSFER 3SSL" -.TH OSSL_HTTP_TRANSFER 3SSL 2024-02-03 3.1.5 OpenSSL +.TH OSSL_HTTP_TRANSFER 3SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -160,8 +160,8 @@ but cannot be used when both \fIbio\fR and \fIrbio\fR are given. .Ve .PP The callback function may modify the BIO provided in the \fIbio\fR argument, -whereby it may make use of a custom defined argument \fIarg\fR, -which may for instance point to an \fBSSL_CTX\fR structure. +whereby it may use an optional custom defined argument \fIarg\fR, +which can for instance point to an \fBSSL_CTX\fR structure. During connection establishment, just after calling \fBBIO_do_connect_retry()\fR, the callback function is invoked with the \fIconnect\fR argument being 1 and \&\fIdetail\fR being 1 if \fIuse_ssl\fR is nonzero (i.e., HTTPS is requested), else 0. @@ -169,7 +169,7 @@ On disconnect \fIconnect\fR is 0 and \fIdetail\fR is 1 if no error occurred, els For instance, on connect the callback may push an SSL BIO to implement HTTPS; after disconnect it may do some diagnostic output and pop and free the SSL BIO. .PP -The callback function must return either the potentially modified BIO \fIbio\fR. +The callback function must return either the potentially modified BIO \fIbio\fR or NULL to indicate failure, in which case it should not modify the BIO. .PP Here is a simple example that supports TLS connections (but not via a proxy): @@ -198,6 +198,8 @@ Here is a simple example that supports TLS connections (but not via a proxy): .Ve .PP After disconnect the modified BIO will be deallocated using \fBBIO_free_all()\fR. +The optional callback function argument \fIarg\fR is not consumed, +so must be freed by the caller when not needed any more. .PP The \fIbuf_size\fR parameter specifies the response header maximum line length. A value <= 0 means that the \fBOSSL_HTTP_DEFAULT_MAX_LINE_LEN\fR (4KiB) is used. @@ -235,9 +237,17 @@ else HTTP POST with the contents of \fIreq\fR and optional \fIcontent_type\fR, w the length of the data in \fIreq\fR does not need to be determined in advance: the BIO will be read on-the-fly while sending the request, which supports streaming. The optional list \fIheaders\fR may contain additional custom HTTP header lines. -If the parameter \fIexpected_content_type\fR -is not NULL then the client will check that the given content type string +.PP +If the \fIexpected_content_type\fR argument is not NULL, +the client will check that the specified content-type string is included in the HTTP header of the response and return an error if not. +In the content-type header line the specified string should be present either +as a whole, or in case the specified string does not include a \f(CW\*(C`;\*(C'\fR character, +it is sufficient that the specified string appears as a prefix +in the header line, followed by a \f(CW\*(C`;\*(C'\fR character and any further text. +For instance, if \fIexpected_content_type\fR specifies \f(CW\*(C`text/html\*(C'\fR, +this is matched by \f(CW\*(C`text/html\*(C'\fR, \f(CW\*(C`text/html; charset=UTF\-8\*(C'\fR, etc. +.PP If the \fIexpect_asn1\fR parameter is nonzero, a structure in ASN.1 encoding will be expected as response content. The \fImax_resp_len\fR parameter specifies the maximum allowed |