diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OSSL_HTTP_REQ_CTX.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OSSL_HTTP_REQ_CTX.3 | 294 |
1 files changed, 128 insertions, 166 deletions
diff --git a/secure/lib/libcrypto/man/man3/OSSL_HTTP_REQ_CTX.3 b/secure/lib/libcrypto/man/man3/OSSL_HTTP_REQ_CTX.3 index f8bf77c2d172..a9f99ef453d8 100644 --- a/secure/lib/libcrypto/man/man3/OSSL_HTTP_REQ_CTX.3 +++ b/secure/lib/libcrypto/man/man3/OSSL_HTTP_REQ_CTX.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,75 +52,15 @@ . \} .\} .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 "OSSL_HTTP_REQ_CTX 3ossl" -.TH OSSL_HTTP_REQ_CTX 3ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH OSSL_HTTP_REQ_CTX 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" +.SH NAME OSSL_HTTP_REQ_CTX, OSSL_HTTP_REQ_CTX_new, OSSL_HTTP_REQ_CTX_free, @@ -150,9 +74,10 @@ OSSL_HTTP_REQ_CTX_exchange, OSSL_HTTP_REQ_CTX_get0_mem_bio, OSSL_HTTP_REQ_CTX_get_resp_len, OSSL_HTTP_REQ_CTX_set_max_response_length, +OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines, OSSL_HTTP_is_alive \&\- HTTP client low\-level functions -.SH "SYNOPSIS" +.SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/http.h> @@ -169,7 +94,7 @@ OSSL_HTTP_is_alive \& const char *name, const char *value); \& \& int OSSL_HTTP_REQ_CTX_set_expected(OSSL_HTTP_REQ_CTX *rctx, -\& const char *content_type, int asn1, +\& const char *expected_content_type, int expect_asn1, \& int timeout, int keep_alive); \& int OSSL_HTTP_REQ_CTX_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type, \& const ASN1_ITEM *it, const ASN1_VALUE *req); @@ -182,41 +107,44 @@ OSSL_HTTP_is_alive \& size_t OSSL_HTTP_REQ_CTX_get_resp_len(const OSSL_HTTP_REQ_CTX *rctx); \& void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx, \& unsigned long len); +\& void OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines(OSSL_HTTP_REQ_CTX *rctx, +\& size_t count); \& \& int OSSL_HTTP_is_alive(const OSSL_HTTP_REQ_CTX *rctx); .Ve -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" -\&\fB\s-1OSSL_HTTP_REQ_CTX\s0\fR is a context structure for an \s-1HTTP\s0 request and response, +\&\fBOSSL_HTTP_REQ_CTX\fR is a context structure for an HTTP request and response, used to collect all the necessary data to perform that request. .PP -This file documents low-level \s-1HTTP\s0 functions rarely used directly. High-level -\&\s-1HTTP\s0 client functions like \fBOSSL_HTTP_get\fR\|(3) and \fBOSSL_HTTP_transfer\fR\|(3) +This file documents low-level HTTP functions rarely used directly. High-level +HTTP client functions like \fBOSSL_HTTP_get\fR\|(3) and \fBOSSL_HTTP_transfer\fR\|(3) should be preferred. .PP -\&\fBOSSL_HTTP_REQ_CTX_new()\fR allocates a new \s-1HTTP\s0 request context structure, -which gets populated with the \fB\s-1BIO\s0\fR to write/send the request to (\fIwbio\fR), -the \fB\s-1BIO\s0\fR to read/receive the response from (\fIrbio\fR, which may be equal to +\&\fBOSSL_HTTP_REQ_CTX_new()\fR allocates a new HTTP request context structure, +which gets populated with the \fBBIO\fR to write/send the request to (\fIwbio\fR), +the \fBBIO\fR to read/receive the response from (\fIrbio\fR, which may be equal to \&\fIwbio\fR), and the maximum expected response header line length \fIbuf_size\fR. A value <= 0 indicates that -the \fB\s-1OSSL_HTTP_DEFAULT_MAX_LINE_LEN\s0\fR of 4KiB should be used. +the \fBOSSL_HTTP_DEFAULT_MAX_LINE_LEN\fR of 4KiB should be used. \&\fIbuf_size\fR is also used as the number of content bytes that are read at a time. -The allocated context structure includes an internal memory \fB\s-1BIO\s0\fR, -which collects the \s-1HTTP\s0 request header lines. +The allocated context structure includes an internal memory \fBBIO\fR, +which collects the HTTP request header lines. .PP -\&\fBOSSL_HTTP_REQ_CTX_free()\fR frees up the \s-1HTTP\s0 request context \fIrctx\fR. +\&\fBOSSL_HTTP_REQ_CTX_free()\fR frees up the HTTP request context \fIrctx\fR. The \fIrbio\fR is not free'd, \fIwbio\fR will be free'd if \fIfree_wbio\fR is set. +If the argument is NULL, nothing is done. .PP -\&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR adds the 1st \s-1HTTP\s0 request line to \fIrctx\fR. -The \s-1HTTP\s0 method is determined by \fImethod_POST\fR, +\&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR adds the 1st HTTP request line to \fIrctx\fR. +The HTTP method is determined by \fImethod_POST\fR, which should be 1 to indicate \f(CW\*(C`POST\*(C'\fR or 0 to indicate \f(CW\*(C`GET\*(C'\fR. \&\fIserver\fR and \fIport\fR may be set to give the server and the optional port that -an \s-1HTTP\s0 proxy shall forward the request to, otherwise they must be left \s-1NULL.\s0 -\&\fIpath\fR provides the \s-1HTTP\s0 request path; if left \s-1NULL,\s0 \f(CW\*(C`/\*(C'\fR is used. +an HTTP proxy shall forward the request to, otherwise they must be left NULL. +\&\fIpath\fR provides the HTTP request path; if left NULL, \f(CW\*(C`/\*(C'\fR is used. For backward compatibility, \fIpath\fR may begin with \f(CW\*(C`http://\*(C'\fR and thus convey -an absoluteURI. In this case it indicates \s-1HTTP\s0 proxy use and provides also the +an absoluteURI. In this case it indicates HTTP proxy use and provides also the server (and optionally the port) that the proxy shall forward the request to. -In this case the \fIserver\fR and \fIport\fR arguments must be \s-1NULL.\s0 +In this case the \fIserver\fR and \fIport\fR arguments must be NULL. .PP \&\fBOSSL_HTTP_REQ_CTX_add1_header()\fR adds header \fIname\fR with value \fIvalue\fR to the context \fIrctx\fR. It can be called more than once to add multiple header lines. @@ -227,90 +155,115 @@ For example, to add a \f(CW\*(C`Host\*(C'\fR header for \f(CW\*(C`example.com\*( .Ve .PP \&\fBOSSL_HTTP_REQ_CTX_set_expected()\fR optionally sets in \fIrctx\fR some expectations -of the \s-1HTTP\s0 client on the response. -Due to the structure of an \s-1HTTP\s0 request, if the \fIkeep_alive\fR argument is +of the HTTP client on the response. +Due to the structure of an HTTP request, if the \fIkeep_alive\fR argument is nonzero the function must be used before calling \fBOSSL_HTTP_REQ_CTX_set1_req()\fR. -If the \fIcontent_type\fR parameter -is not \s-1NULL\s0 then the client will check that the given content type string -is included in the \s-1HTTP\s0 header of the response and return an error if not. -If the \fIasn1\fR parameter is nonzero a structure in \s-1ASN.1\s0 encoding will be +.PP +If the \fIexpected_content_type\fR argument is not NULL, the client will +check in a case-insensitive way that the specified \f(CW\*(C`Content\-Type\*(C'\fR string value +is included in the HTTP header of the response and return an error if not. +In the \f(CW\*(C`Content\-Type\*(C'\fR 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 the \fIexpected_content_type\fR argument 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 the response content and input streaming is disabled. This means -that an \s-1ASN.1\s0 sequence header is required, its length field is checked, and +that an ASN.1 sequence header is required, its length field is checked, and \&\fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR should be used to get the buffered response. -Otherwise (by default) any input format is allowed without length checks. -In this case the \s-1BIO\s0 given as \fIrbio\fR argument to \fBOSSL_HTTP_REQ_CTX_new()\fR should +Otherwise (by default) any input format is allowed, +with body length checks being performed on error messages only. +In this case the BIO given as \fIrbio\fR argument to \fBOSSL_HTTP_REQ_CTX_new()\fR should be used directly to read the response contents, which may support streaming. +.PP If the \fItimeout\fR parameter is > 0 this indicates the maximum number of seconds -the subsequent \s-1HTTP\s0 transfer (sending the request and receiving a response) +the subsequent HTTP transfer (sending the request and receiving a response) is allowed to take. \&\fItimeout\fR == 0 enables waiting indefinitely, i.e., no timeout can occur. This is the default. \&\fItimeout\fR < 0 takes over any value set via the \fIoverall_timeout\fR argument of \&\fBOSSL_HTTP_open\fR\|(3) with the default being 0, which means no timeout. +.PP If the \fIkeep_alive\fR parameter is 0, which is the default, the connection is not -kept open after receiving a response. This is the default behavior for \s-1HTTP 1.0.\s0 +kept open after receiving a response. This is the default behavior for HTTP 1.0. If the value is 1 or 2 then a persistent connection is requested. If the value is 2 then a persistent connection is required, i.e., an error occurs in case the server does not grant it. .PP -\&\fBOSSL_HTTP_REQ_CTX_set1_req()\fR finalizes the \s-1HTTP\s0 request context. +\&\fBOSSL_HTTP_REQ_CTX_set1_req()\fR finalizes the HTTP request context. It is needed if the \fImethod_POST\fR parameter in the \&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR call was 1 -and an \s-1ASN\s0.1\-encoded request should be sent. -It must also be used when requesting \*(L"keep-alive\*(R", -even if a \s-1GET\s0 request is going to be sent, in which case \fIreq\fR must be \s-1NULL.\s0 -Unless \fIreq\fR is \s-1NULL,\s0 the function adds the \s-1DER\s0 encoding of \fIreq\fR using -the \s-1ASN.1\s0 template \fIit\fR to do the encoding (which does not support streaming). -The \s-1HTTP\s0 header \f(CW\*(C`Content\-Length\*(C'\fR is filled out with the length of the request. -\&\fIcontent_type\fR must be \s-1NULL\s0 if \fIreq\fR is \s-1NULL.\s0 -If \fIcontent_type\fR isn't \s-1NULL,\s0 -the \s-1HTTP\s0 header \f(CW\*(C`Content\-Type\*(C'\fR is also added with the given string value. -The header lines are added to the internal memory \fB\s-1BIO\s0\fR for the request header. +and an ASN.1\-encoded request should be sent. +It must also be used when requesting "keep-alive", +even if a GET request is going to be sent, in which case \fIreq\fR must be NULL. +Unless \fIreq\fR is NULL, the function adds the DER encoding of \fIreq\fR using +the ASN.1 template \fIit\fR to do the encoding (which does not support streaming). +The HTTP header \f(CW\*(C`Content\-Length\*(C'\fR is filled out with the length of the request. +\&\fIcontent_type\fR must be NULL if \fIreq\fR is NULL. +If \fIcontent_type\fR isn't NULL, +the HTTP header \f(CW\*(C`Content\-Type\*(C'\fR is also added with the given string value. +The header lines are added to the internal memory \fBBIO\fR for the request header. .PP \&\fBOSSL_HTTP_REQ_CTX_nbio()\fR attempts to send the request prepared in \fIrctx\fR -and to gather the response via \s-1HTTP,\s0 using the \fIwbio\fR and \fIrbio\fR +and to gather the response via HTTP, using the \fIwbio\fR and \fIrbio\fR that were given when calling \fBOSSL_HTTP_REQ_CTX_new()\fR. The function may need to be called again if its result is \-1, which indicates \&\fBBIO_should_retry\fR\|(3). In such a case it is advisable to sleep a little in -between, using \fBBIO_wait\fR\|(3) on the read \s-1BIO\s0 to prevent a busy loop. +between, using \fBBIO_wait\fR\|(3) on the read BIO to prevent a busy loop. +See \fBOSSL_HTTP_REQ_CTX_set_expected()\fR how the response content type, +the response body, the HTTP transfer timeout, and "keep-alive" are treated. +Any error message body is consumed +if a \f(CW\*(C`Content\-Type\*(C'\fR header is not included or its value starts with \f(CW\*(C`text/\*(C'\fR. +This is used for tracing the body contents if HTTP tracing is enabled. +If the \f(CW\*(C`Content\-Length\*(C'\fR header is present in the response +and its value exceeds the maximum allowed response content length +or the response is an error message with its body length exceeding this value +or the content is an ASN.1\-encoded structure with a length exceeding this value +or both length indications are present but disagree then an error occurs. .PP \&\fBOSSL_HTTP_REQ_CTX_nbio_d2i()\fR is like \fBOSSL_HTTP_REQ_CTX_nbio()\fR but on success -in addition parses the response, which must be a DER-encoded \s-1ASN.1\s0 structure, -using the \s-1ASN.1\s0 template \fIit\fR and places the result in \fI*pval\fR. +in addition parses the response, which must be a DER-encoded ASN.1 structure, +using the ASN.1 template \fIit\fR and places the result in \fI*pval\fR. .PP \&\fBOSSL_HTTP_REQ_CTX_exchange()\fR calls \fBOSSL_HTTP_REQ_CTX_nbio()\fR as often as needed in order to exchange a request and response or until a timeout is reached. -On success it returns a pointer to the \s-1BIO\s0 that can be used to read the result. -If an \s-1ASN\s0.1\-encoded response was expected, this is the \s-1BIO\s0 +On success it returns a pointer to the BIO that can be used to read the result. +If an ASN.1\-encoded response was expected, this is the BIO returned by \fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR when called after the exchange. -This memory \s-1BIO\s0 does not support streaming. -Otherwise the returned \s-1BIO\s0 is the \fIrbio\fR given to \fBOSSL_HTTP_REQ_CTX_new()\fR, +This memory BIO does not support streaming. +Otherwise the returned BIO is the \fIrbio\fR given to \fBOSSL_HTTP_REQ_CTX_new()\fR, which may support streaming. -When this \s-1BIO\s0 is returned, it has been read past the end of the response header, +When this BIO is returned, it has been read past the end of the response header, such that the actual response body can be read from it. -The returned \s-1BIO\s0 pointer \s-1MUST NOT\s0 be freed by the caller. +The returned BIO pointer MUST NOT be freed by the caller. .PP -\&\fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR returns the internal memory \fB\s-1BIO\s0\fR. -Before the \s-1HTTP\s0 request is sent, this could be used to adapt its header lines. +\&\fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR returns the internal memory \fBBIO\fR. +Before the HTTP request is sent, this could be used to adapt its header lines. \&\fIUse with caution!\fR -After receiving a response via \s-1HTTP,\s0 the \s-1BIO\s0 represents the current state of -reading the response header. If the response was expected to be \s-1ASN.1\s0 encoded, -its contents can be read via this \s-1BIO,\s0 which does not support streaming. -The returned \s-1BIO\s0 pointer must not be freed by the caller. +After receiving a response via HTTP, the BIO represents the current state of +reading the response header. If the response was expected to be ASN.1 encoded, +its contents can be read via this BIO, which does not support streaming. +The returned BIO pointer must not be freed by the caller. .PP \&\fBOSSL_HTTP_REQ_CTX_get_resp_len()\fR returns the size of the response contents -in \fIrctx\fR if provided by the server as <Content\-Length> header field, else 0. +in \fIrctx\fR if provided by the server as \f(CW\*(C`Content\-Length\*(C'\fR header field, else 0. .PP \&\fBOSSL_HTTP_REQ_CTX_set_max_response_length()\fR sets the maximum allowed response content length for \fIrctx\fR to \fIlen\fR. If not set or \fIlen\fR is 0 -then the \fB\s-1OSSL_HTTP_DEFAULT_MAX_RESP_LEN\s0\fR is used, which currently is 100 KiB. -If the \f(CW\*(C`Content\-Length\*(C'\fR header is present and exceeds this value or -the content is an \s-1ASN.1\s0 encoded structure with a length exceeding this value -or both length indications are present but disagree then an error occurs. +then the \fBOSSL_HTTP_DEFAULT_MAX_RESP_LEN\fR is used, which currently is 100 KiB. +.PP +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR changes the limit for +the number of HTTP header lines allowed to be received in a response. +The default limit is \fBOSSL_HTTP_DEFAULT_MAX_RESP_HDR_LINES\fR, currently 256. +If the limit is not 0 and the number of lines exceeds the limit, +then the HTTP_R_RESPONSE_TOO_MANY_HDRLINES error is indicated. +Setting the limit to 0 disables the check. .PP -\&\fBOSSL_HTTP_is_alive()\fR can be used to query if the \s-1HTTP\s0 connection +\&\fBOSSL_HTTP_is_alive()\fR can be used to query if the HTTP connection given by \fIrctx\fR is still alive, i.e., has not been closed. -It returns 0 if \fIrctx\fR is \s-1NULL.\s0 +It returns 0 if \fIrctx\fR is NULL. .PP If the client application requested or required a persistent connection and this was granted by the server, it can keep \fIrctx\fR as long as it wants @@ -319,36 +272,42 @@ else it should call \fIOSSL_HTTP_REQ_CTX_free(rctx)\fR or \fBOSSL_HTTP_close\fR\ In case the client application keeps \fIrctx\fR but the connection then dies for any reason at the server side, it will notice this obtaining an I/O error when trying to send the next request via \fIrctx\fR. -.SH "WARNINGS" +.SH WARNINGS .IX Header "WARNINGS" The server's response may be unexpected if the hostname that was used to create the \fIwbio\fR, any \f(CW\*(C`Host\*(C'\fR header, and the host specified in the -request \s-1URL\s0 do not match. +request URL do not match. .PP Many of these functions must be called in a certain order. .PP -First, the \s-1HTTP\s0 request context must be allocated: +First, the HTTP request context must be allocated: \&\fBOSSL_HTTP_REQ_CTX_new()\fR. .PP -Then, the \s-1HTTP\s0 request must be prepared with request data: -.IP "1." 4 +Then, the HTTP request must be prepared with request data: +.IP 1. 4 Calling \fBOSSL_HTTP_REQ_CTX_set_request_line()\fR. -.IP "2." 4 +.IP 2. 4 Adding extra header lines with \fBOSSL_HTTP_REQ_CTX_add1_header()\fR. This is optional and may be done multiple times with different names. -.IP "3." 4 +.IP 3. 4 Finalize the request using \fBOSSL_HTTP_REQ_CTX_set1_req()\fR. -This may be omitted if the \s-1GET\s0 method is used and \*(L"keep-alive\*(R" is not requested. +This may be omitted if the GET method is used and "keep-alive" is not requested. .PP -When the request context is fully prepared, the \s-1HTTP\s0 exchange may be performed +When the request context is fully prepared, the HTTP exchange may be performed with \fBOSSL_HTTP_REQ_CTX_nbio()\fR or \fBOSSL_HTTP_REQ_CTX_exchange()\fR. +.SH NOTES +.IX Header "NOTES" +When built with tracing enabled, \fBOSSL_HTTP_REQ_CTX_nbio()\fR and all functions +using it, such as \fBOSSL_HTTP_REQ_CTX_exchange()\fR and \fBOSSL_HTTP_transfer\fR\|(3), +may be traced using \fBOSSL_TRACE_CATEGORY_HTTP\fR. +See also \fBOSSL_trace_enabled\fR\|(3) and \fBopenssl\-env\fR\|(7). .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fBOSSL_HTTP_REQ_CTX_new()\fR returns a pointer to a \fB\s-1OSSL_HTTP_REQ_CTX\s0\fR, or \s-1NULL\s0 +\&\fBOSSL_HTTP_REQ_CTX_new()\fR returns a pointer to a \fBOSSL_HTTP_REQ_CTX\fR, or NULL on error. .PP -\&\fBOSSL_HTTP_REQ_CTX_free()\fR and \fBOSSL_HTTP_REQ_CTX_set_max_response_length()\fR -do not return values. +\&\fBOSSL_HTTP_REQ_CTX_free()\fR, \fBOSSL_HTTP_REQ_CTX_set_max_response_length()\fR, and +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR do not return values. .PP \&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR, \fBOSSL_HTTP_REQ_CTX_add1_header()\fR, \&\fBOSSL_HTTP_REQ_CTX_set1_req()\fR, and \fBOSSL_HTTP_REQ_CTX_set_expected()\fR @@ -358,8 +317,8 @@ return 1 for success and 0 for failure. return 1 for success, 0 on error or redirection, \-1 if retry is needed. .PP \&\fBOSSL_HTTP_REQ_CTX_exchange()\fR and \fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR -return a pointer to a \fB\s-1BIO\s0\fR on success as described above or \s-1NULL\s0 on failure. -The returned \s-1BIO\s0 must not be freed by the caller. +return a pointer to a \fBBIO\fR on success as described above or NULL on failure. +The returned BIO must not be freed by the caller. .PP \&\fBOSSL_HTTP_REQ_CTX_get_resp_len()\fR returns the size of the response contents or 0 if not available or an error occurred. @@ -376,15 +335,18 @@ and the server did not disagree on keeping the connection open, else 0. \&\fBOSSL_HTTP_open\fR\|(3), \&\fBOSSL_HTTP_get\fR\|(3), \&\fBOSSL_HTTP_transfer\fR\|(3), -\&\fBOSSL_HTTP_close\fR\|(3) -.SH "HISTORY" +\&\fBOSSL_HTTP_close\fR\|(3), +\&\fBOSSL_trace_enabled\fR\|(3), and \fBopenssl\-env\fR\|(7). +.SH HISTORY .IX Header "HISTORY" -The functions described here were added in OpenSSL 3.0. -.SH "COPYRIGHT" +\&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR was added in OpenSSL 3.3. +.PP +All other functions described here were added in OpenSSL 3.0. +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2015\-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015\-2025 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>. |