NULL, else by connecting to a given I<server> optionally via a I<proxy>.
Typically the OpenSSL build supports sockets and the I<bio> parameter is NULL.
-In this case I<rbio> must be NULL as well, and the
-library creates a network BIO internally for connecting to the given I<server>
-at the specified I<port> if any, defaulting to 80 for HTTP or 443 for HTTPS.
+In this case I<rbio> must be NULL as well and the I<server> must be non-NULL.
+The function creates a network BIO internally using L<BIO_new_connect(3)>
+for connecting to the given server and the optionally given I<port>,
+defaulting to 80 for HTTP or 443 for HTTPS.
Then this internal BIO is used for setting up a connection
and for exchanging one or more request and response.
If I<bio> is given and I<rbio> is NULL then this I<bio> is used instead.
As soon as the client has flushed I<bio> the server must be ready to provide
a response or indicate a waiting condition via I<rbio>.
+If I<bio> is given, it is an error to provide I<proxy> or I<no_proxy> arguments,
+while I<server> and I<port> arguments may be given to support diagnostic output.
If I<bio> is NULL the optional I<proxy> parameter can be used to set an
HTTP(S) proxy to use (unless overridden by "no_proxy" settings).
If TLS is not used this defaults to the environment variable C<http_proxy>
BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
-The callback may modify the HTTP BIO provided in the I<bio> argument,
+The callback function may modify the BIO provided in the I<bio> argument,
whereby it may make use of a custom defined argument I<arg>,
-which may for instance refer to an I<SSL_CTX> structure.
-During connection establishment, just after calling BIO_do_connect_retry(),
-the function is invoked with the I<connect> argument being 1 and the I<detail>
-argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled, else 0.
+which may for instance point to an B<SSL_CTX> structure.
+During connection establishment, just after calling BIO_do_connect_retry(), the
+callback function is invoked with the I<connect> argument being 1 and
+I<detail> being 1 if I<use_ssl> is nonzero (i.e., HTTPS is requested), else 0.
On disconnect I<connect> is 0 and I<detail> is 1 if no error occurred, else 0.
-For instance, on connect the function may prepend a TLS BIO to implement HTTPS;
-after disconnect it may do some diagnostic output and/or specific cleanup.
-The function should return NULL to indicate failure.
+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.
+
+The callback function must return either the potentially modified BIO I<bio>.
+or NULL to indicate failure, in which case it should not modify the BIO.
+
Here is a simple example that supports TLS connections (but not via a proxy):
- BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail)
+ BIO *http_tls_cb(BIO *bio, void *arg, int connect, int detail)
{
if (connect && detail) { /* connecting with TLS */
SSL_CTX *ctx = (SSL_CTX *)arg;
BIO *sbio = BIO_new_ssl(ctx, 1);
- hbio = sbio != NULL ? BIO_push(sbio, hbio) : NULL;
- } else if (!connect && !detail) { /* disconnecting after error */
- /* optionally add diagnostics here */
+ bio = sbio != NULL ? BIO_push(sbio, bio) : NULL;
+ } else if (!connect) { /* disconnecting */
+ BIO *hbio;
+
+ if (!detail) { /* an error has occurred */
+ /* optionally add diagnostics here */
+ }
+ BIO_ssl_shutdown(bio);
+ hbio = BIO_pop(bio);
+ BIO_free(bio); /* SSL BIO */
+ bio = hbio;
}
- return hbio;
+ return bio;
}
After disconnect the modified BIO will be deallocated using BIO_free_all().
OSSL_HTTP_set1_request() sets up in I<rctx> the request header and content data
and expectations on the response using the following parameters.
+If <rctx> indicates using a proxy for HTTP (but not HTTPS), the server host
+(and optionally port) needs to be placed in the header; thus it must be present
+in I<rctx>.
+For backward compatibility, the server (and optional port) may also be given in
+the I<path> argument beginning with C<http://> (thus giving an absoluteURI).
If I<path> is NULL it defaults to "/".
If I<req> is NULL the HTTP GET method will be used to send the request
else HTTP POST with the contents of I<req> and optional I<content_type>, where
the length of the data in I<req> 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 I<headers> may contain additional custom HTTP header lines.
-If the parameter I<expected_content_type>
-is not NULL then the client will check that the given content type string
+
+If the I<expected_content_type> 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 C<;> character,
+it is sufficient that the specified string appears as a prefix
+in the header line, followed by a C<;> character and any further text.
+For instance, if I<expected_content_type> specifies C<text/html>,
+this is matched by C<text/html>, C<text/html; charset=UTF-8>, etc.
+
If the I<expect_asn1> parameter is nonzero,
a structure in ASN.1 encoding will be expected as response content.
The I<max_resp_len> parameter specifies the maximum allowed
an ASN.1-encoded response is expected, which should include a total length,
the length indications received are checked for consistency
and for not exceeding any given maximum response length.
-On receiving a response, the function returns the contents as a memory BIO,
-which does not support streaming, in case an ASN.1-encoded response is expected.
-Else it returns directly the read BIO that holds the response contents,
+If an ASN.1-encoded response is expected, the function returns on success
+the contents buffered in a memory BIO, which does not support streaming.
+Otherwise it returns directly the read BIO that holds the response contents,
which allows a response of indefinite length and may support streaming.
+The caller is responsible for freeing the BIO pointer obtained.
OSSL_HTTP_get() uses HTTP GET to obtain data from I<bio> if non-NULL,
else from the server contained in the I<url>, and returns it as a BIO.
and the I<bio_update_fn>, as described for OSSL_HTTP_open(), must be provided.
Also the remaining parameters are interpreted as described for OSSL_HTTP_open()
and OSSL_HTTP_set1_request(), respectively.
+The caller is responsible for freeing the BIO pointer obtained.
OSSL_HTTP_transfer() exchanges an HTTP request and response
over a connection managed via I<prctx> without supporting redirection.
and assigns NULL to I<*prctx>.
The remaining parameters are interpreted as described for OSSL_HTTP_open()
and OSSL_HTTP_set1_request(), respectively.
+The caller is responsible for freeing the BIO pointer obtained.
OSSL_HTTP_close() closes the connection and releases I<rctx>.
The I<ok> parameter is passed to any BIO update function
given during setup as described above for OSSL_HTTP_open().
+It must be 1 if no error occurred during the HTTP transfer and 0 otherwise.
=head1 NOTES
C<NO_PROXY>, have been chosen for maximal compatibility with
other HTTP client implementations such as wget, curl, and git.
+When built with tracing enabled, OSSL_HTTP_transfer() and all functions using it
+may be traced using B<OSSL_TRACE_CATEGORY_HTTP>.
+See also L<OSSL_trace_enabled(3)> and L<openssl(1)/ENVIRONMENT>.
+
=head1 RETURN VALUES
OSSL_HTTP_open() returns on success a B<OSSL_HTTP_REQ_CTX>, else NULL.
return 1 on success, 0 on error.
On success, OSSL_HTTP_exchange(), OSSL_HTTP_get(), and OSSL_HTTP_transfer()
-return a memory BIO containing the data received if an ASN.1-encoded response
-is expected, else a BIO that may support streaming.
+return a memory BIO that buffers all the data received if an ASN.1-encoded
+response is expected, otherwise a BIO that may support streaming.
The BIO must be freed by the caller.
On failure, they return NULL.
Failure conditions include connection/transfer timeout, parse errors, etc.
+The caller is responsible for freeing the BIO pointer obtained.
OSSL_HTTP_close() returns 0 if anything went wrong while disconnecting, else 1.
=head1 SEE ALSO
-L<OSSL_HTTP_parse_url(3)>, L<BIO_set_conn_port(3)>
+L<OSSL_HTTP_parse_url(3)>, L<BIO_new_connect(3)>,
L<ASN1_item_i2d_mem_bio(3)>, L<ASN1_item_d2i_bio(3)>,
-L<OSSL_HTTP_is_alive(3)>
+L<OSSL_HTTP_is_alive(3)>,
+L<OSSL_trace_enabled(3)>
=head1 HISTORY
=head1 COPYRIGHT
-Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
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
projects / thirdparty / openssl.git / blobdiff