• NAME
• SYNOPSIS
• DESCRIPTION
• RETURN VALUES
• HISTORY
• COPYRIGHT

NAME

OSSL_HTTP_get, OSSL_HTTP_get_asn1, OSSL_HTTP_post_asn1, OSSL_HTTP_transfer, OSSL_HTTP_bio_cb_t, OSSL_HTTP_proxy_connect, OSSL_HTTP_parse_url - http client functions

SYNOPSIS

 #include <openssl/http.h>

 typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg,
                                    int connect, int detail);
 BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *proxy_port,
                    BIO *bio, BIO *rbio,
                    OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
                    const STACK_OF(CONF_VALUE) *headers,
                    int maxline, unsigned long max_resp_len, int timeout,
                    const char *expected_content_type, int expect_asn1);
 ASN1_VALUE *OSSL_HTTP_get_asn1(const char *url,
                                const char *proxy, const char *proxy_port,
                                BIO *bio, BIO *rbio,
                                OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
                                const STACK_OF(CONF_VALUE) *headers,
                                int maxline, unsigned long max_resp_len,
                                int timeout, const char *expected_content_type,
                                const ASN1_ITEM *it);
 ASN1_VALUE *OSSL_HTTP_post_asn1(const char *server, const char *port,
                                 const char *path, int use_ssl,
                                 const char *proxy, const char *proxy_port,
                                 BIO *bio, BIO *rbio,
                                 OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
                                 const STACK_OF(CONF_VALUE) *headers,
                                 const char *content_type,
                                 ASN1_VALUE *req, const ASN1_ITEM *req_it,
                                 int maxline, unsigned long max_resp_len,
                                 int timeout, const char *expected_ct,
                                 const ASN1_ITEM *rsp_it);
 BIO *OSSL_HTTP_transfer(const char *server, const char *port, const char *path,
                         int use_ssl, const char *proxy, const char *proxy_port,
                         BIO *bio, BIO *rbio,
                         OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
                         const STACK_OF(CONF_VALUE) *headers,
                         const char *content_type, BIO *req_mem,
                         int maxline, unsigned long max_resp_len, int timeout,
                         const char *expected_ct, int expect_asn1,
                         char **redirection_url);
 int OSSL_HTTP_proxy_connect(BIO *bio, const char *server, const char *port,
                             const char *proxyuser, const char *proxypass,
                             int timeout, BIO *bio_err, const char *prog);
 int OSSL_HTTP_parse_url(const char *url, char **phost, char **pport,
                         char **ppath, int *pssl);

DESCRIPTION

OSSL_HTTP_get() uses HTTP GET to obtain data (of any type) from the given url and returns it as a memory BIO.

OSSL_HTTP_get_asn1() uses HTTP GET to obtain an ASN.1-encoded value (e.g., an X.509 certificate) with the expected structure specified by it (e.g., ASN1_ITEM_rptr(X509)) from the given url and returns it on success as a pointer to ASN1_VALUE.

OSSL_HTTP_post_asn1() uses the HTTP POST method to send a request req with the ASN.1 structure defined in req_it and the given content_type to the given server and optional port and path, which defaults to "/". If use_ssl is nonzero a TLS connection is requested and the bio_update_fn parameter, described below, must be provided. The optional list headers may contain additional custom HTTP header lines. The expected structure of the response is specified by rsp_it. On success it returns the response as a pointer to ASN1_VALUE.

OSSL_HTTP_transfer() exchanges an HTTP request and response with the given server and optional port and path, which defaults to "/". If use_ssl is nonzero a TLS connection is requested and the bio_update_fn parameter, described below, must be provided. If req_mem is NULL it uses the HTTP GET method, else it uses HTTP POST to send a request with the contents of the memory BIO and optional content_type. The optional list headers may contain additional custom HTTP header lines. If req_mem is NULL (i.e., the HTTP method is GET) and redirection_url is not NULL the latter pointer is used to provide any new location that the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND). In this case the caller is responsible for deallocating this URL with openssl-s_client(1) it uses the bio_err and prog parameters (unless NULL) to print additional diagnostic information in a user-oriented way.

OSSL_HTTP_parse_url() parses its input string url as a URL and splits it up into host, port and path components and a flag whether it begins with 'https'. The host component may be a DNS name or an IPv4 or an IPv6 address. The port component is optional and defaults to "443" for HTTPS, else "80". The path component is also optional and defaults to "/". As far as the result pointer arguments are not NULL it assigns via them copies of the respective string components. The strings returned this way must be deallocated by the caller using RETURN VALUES

OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and OSSL_HTTP_transfer() return on success the data received via HTTP, else NULL. Error conditions include connection/transfer timeout, parse errors, etc.

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 LICENSE in the source distribution or at https://www.openssl.org/source/license.html.