http.h File Reference

Hyper Text Transport Protocol. More...

#include <stdint.h>
#include <ipxe/refcnt.h>
#include <ipxe/interface.h>
#include <ipxe/iobuf.h>
#include <ipxe/process.h>
#include <ipxe/retry.h>
#include <ipxe/linebuf.h>
#include <ipxe/pool.h>
#include <ipxe/tables.h>
#include <ipxe/ntlm.h>

Go to the source code of this file.

Data Structures
struct	http_scheme
	An HTTP URI scheme. More...
struct	http_connection
	An HTTP connection. More...
struct	http_method
	An HTTP method. More...
struct	http_request_range
	HTTP request range descriptor. More...
struct	http_request_content
	HTTP request content descriptor. More...
struct	http_request_auth_basic
	HTTP request Basic authentication descriptor. More...
struct	http_request_auth_digest
	HTTP request Digest authentication descriptor. More...
struct	http_request_auth_ntlm
	HTTP request NTLM authentication descriptor. More...
struct	http_request_auth
	HTTP request authentication descriptor. More...
struct	http_request
	An HTTP request. More...
struct	http_request_header
	An HTTP request header. More...
struct	http_response_transfer
	HTTP response transfer descriptor. More...
struct	http_response_content
	HTTP response content descriptor. More...
struct	http_response_auth_basic
	HTTP response Basic authorization descriptor. More...
struct	http_response_auth_digest
	HTTP response Digest authorization descriptor. More...
struct	http_response_auth_ntlm
	HTTP response NTLM authorization descriptor. More...
struct	http_response_auth
	HTTP response authorization descriptor. More...
struct	http_response
	An HTTP response. More...
struct	http_response_header
	An HTTP response header. More...
struct	http_state
	HTTP transaction state. More...
struct	http_transaction
	An HTTP transaction. More...
struct	http_transfer_encoding
	An HTTP transfer encoding. More...
struct	http_content_encoding
	An HTTP content encoding. More...
struct	http_authentication
	An HTTP authentication scheme. More...

Macros
#define	HTTP_PORT   80
	HTTP default port.
#define	HTTPS_PORT   443
	HTTPS default port.
#define	HTTP_SCHEMES   __table ( struct http_scheme, "http_schemes" )
	HTTP scheme table.
#define	__http_scheme   __table_entry ( HTTP_SCHEMES, 01 )
	Declare an HTTP scheme.
#define	HTTP_DIGEST_NC   "00000001"
	HTTP Digest authentication client nonce count.
#define	HTTP_DIGEST_CNONCE_LEN   8
	HTTP Digest authentication client nonce length.
#define	HTTP_DIGEST_RESPONSE_LEN   32
	HTTP Digest authentication response length.
#define	HTTP_REQUEST_HEADERS    __table ( struct http_request_header, "http_request_headers" )
	HTTP request header table.
#define	__http_request_header   __table_entry ( HTTP_REQUEST_HEADERS, 01 )
	Declare an HTTP request header.
#define	HTTP_RESPONSE_HEADERS    __table ( struct http_response_header, "http_response_headers" )
	HTTP response header table.
#define	__http_response_header   __table_entry ( HTTP_RESPONSE_HEADERS, 01 )
	Declare an HTTP response header.
#define	HTTP_TRANSFER_ENCODINGS    __table ( struct http_transfer_encoding, "http_transfer_encodings" )
	HTTP transfer encoding table.
#define	__http_transfer_encoding   __table_entry ( HTTP_TRANSFER_ENCODINGS, 01 )
	Declare an HTTP transfer encoding.
#define	HTTP_CONTENT_ENCODINGS    __table ( struct http_content_encoding, "http_content_encodings" )
	HTTP content encoding table.
#define	__http_content_encoding   __table_entry ( HTTP_CONTENT_ENCODINGS, 01 )
	Declare an HTTP content encoding.
#define	HTTP_AUTHENTICATIONS    __table ( struct http_authentication, "http_authentications" )
	HTTP authentication scheme table.
#define	__http_authentication   __table_entry ( HTTP_AUTHENTICATIONS, 01 )
	Declare an HTTP authentication scheme.

Enumerations
enum	http_response_flags { HTTP_RESPONSE_KEEPALIVE = 0x0001 , HTTP_RESPONSE_CONTENT_LEN = 0x0002 , HTTP_RESPONSE_RETRY = 0x0004 }
	HTTP response flags. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
char *	http_token (char **line, char **value)
	Get HTTP response token.
int	http_connect (struct interface *xfer, struct uri *uri)
	Connect to an HTTP server.
int	http_open (struct interface *xfer, struct http_method *method, struct uri *uri, struct http_request_range *range, struct http_request_content *content)
	Open HTTP transaction.
int	http_open_uri (struct interface *xfer, struct uri *uri)
	Open HTTP transaction for simple URI.

Variables
struct http_method	http_head
	HTTP HEAD method.
struct http_method	http_get
	HTTP GET method.
struct http_method	http_post
	HTTP POST method.

Detailed Description

Hyper Text Transport Protocol.

Definition in file http.h.

Macro Definition Documentation

HTTP_PORT

#define HTTP_PORT   80

HTTP default port.

Definition at line 35 of file http.h.

HTTPS_PORT

#define HTTPS_PORT   443

HTTPS default port.

Definition at line 38 of file http.h.

HTTP_SCHEMES

#define HTTP_SCHEMES   __table ( struct http_scheme, "http_schemes" )

HTTP scheme table.

Definition at line 55 of file http.h.

Referenced by http_scheme().

__http_scheme

#define __http_scheme   __table_entry ( HTTP_SCHEMES, 01 )

Declare an HTTP scheme.

Definition at line 58 of file http.h.

HTTP_DIGEST_NC

#define HTTP_DIGEST_NC   "00000001"

HTTP Digest authentication client nonce count.

We choose to generate a new client nonce each time.

Definition at line 120 of file http.h.

Referenced by http_digest_authenticate(), and http_format_digest_auth().

HTTP_DIGEST_CNONCE_LEN

#define HTTP_DIGEST_CNONCE_LEN   8

HTTP Digest authentication client nonce length.

We choose to use a 32-bit hex client nonce.

Definition at line 126 of file http.h.

HTTP_DIGEST_RESPONSE_LEN

#define HTTP_DIGEST_RESPONSE_LEN   32

HTTP Digest authentication response length.

The Digest authentication response is a Base16-encoded 16-byte MD5 checksum.

Definition at line 133 of file http.h.

HTTP_REQUEST_HEADERS

#define HTTP_REQUEST_HEADERS    __table ( struct http_request_header, "http_request_headers" )

HTTP request header table.

Definition at line 242 of file http.h.

#define HTTP_REQUEST_HEADERS \
        __table ( struct http_request_header, "http_request_headers" )

Referenced by http_format_headers().

__http_request_header

struct http_request_header http_request_accept_encoding __http_request_header   __table_entry ( HTTP_REQUEST_HEADERS, 01 )

Declare an HTTP request header.

HTTP "Accept-Encoding" header.

HTTP "Content-Length" header.

HTTP "Content-Type" header.

HTTP "Range" header.

HTTP "Connection" header.

HTTP "User-Agent" header.

HTTP "X-P2P-PeerDist" header.

Definition at line 246 of file http.h.

HTTP_RESPONSE_HEADERS

#define HTTP_RESPONSE_HEADERS    __table ( struct http_response_header, "http_response_headers" )

HTTP response header table.

Definition at line 378 of file http.h.

#define HTTP_RESPONSE_HEADERS \
        __table ( struct http_response_header, "http_response_headers" )

Referenced by http_parse_header().

__http_response_header

struct http_response_header http_response_retry_after __http_response_header   __table_entry ( HTTP_RESPONSE_HEADERS, 01 )

Declare an HTTP response header.

HTTP "Retry-After" header.

HTTP "Content-Encoding" header.

HTTP "Content-Length" header.

HTTP "Connection" header.

HTTP "Transfer-Encoding" header.

Definition at line 382 of file http.h.

HTTP_TRANSFER_ENCODINGS

#define HTTP_TRANSFER_ENCODINGS    __table ( struct http_transfer_encoding, "http_transfer_encodings" )

HTTP transfer encoding table.

Definition at line 473 of file http.h.

#define HTTP_TRANSFER_ENCODINGS \
        __table ( struct http_transfer_encoding, "http_transfer_encodings" )

Referenced by http_parse_transfer_encoding().

__http_transfer_encoding

#define __http_transfer_encoding   __table_entry ( HTTP_TRANSFER_ENCODINGS, 01 )

Declare an HTTP transfer encoding.

Definition at line 477 of file http.h.

HTTP_CONTENT_ENCODINGS

#define HTTP_CONTENT_ENCODINGS    __table ( struct http_content_encoding, "http_content_encodings" )

HTTP content encoding table.

Definition at line 505 of file http.h.

#define HTTP_CONTENT_ENCODINGS \
        __table ( struct http_content_encoding, "http_content_encodings" )

Referenced by http_format_accept_encoding(), and http_parse_content_encoding().

__http_content_encoding

#define __http_content_encoding   __table_entry ( HTTP_CONTENT_ENCODINGS, 01 )

Declare an HTTP content encoding.

Definition at line 509 of file http.h.

HTTP_AUTHENTICATIONS

#define HTTP_AUTHENTICATIONS    __table ( struct http_authentication, "http_authentications" )

HTTP authentication scheme table.

Definition at line 547 of file http.h.

#define HTTP_AUTHENTICATIONS \
        __table ( struct http_authentication, "http_authentications" )

Referenced by http_authentication().

__http_authentication

struct http_authentication http_ntlm_auth __http_authentication   __table_entry ( HTTP_AUTHENTICATIONS, 01 )

Declare an HTTP authentication scheme.

HTTP NTLM authentication scheme.

Definition at line 551 of file http.h.

Enumeration Type Documentation

http_response_flags

enum http_response_flags

HTTP response flags.

Enumerator
HTTP_RESPONSE_KEEPALIVE	Keep connection alive after close.
HTTP_RESPONSE_CONTENT_LEN	Content length specified.
HTTP_RESPONSE_RETRY	Transaction may be retried on failure.

Definition at line 355 of file http.h.

                         {
        /** Keep connection alive after close */
        HTTP_RESPONSE_KEEPALIVE = 0x0001,
        /** Content length specified */
        HTTP_RESPONSE_CONTENT_LEN = 0x0002,
        /** Transaction may be retried on failure */
        HTTP_RESPONSE_RETRY = 0x0004,
};

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

http_token()

char * http_token ( char ** line, char ** value )

extern

Get HTTP response token.

Parameters

line	Line position
value	Token value to fill in (if any)

Return values

token

Token, or NULL

Definition at line 196 of file httpcore.c.

                                                {
        char *token;
        char quote = '\0';
        char c;
 
        /* Avoid returning uninitialised data */
        if ( value )
                *value = NULL;
 
        /* Skip any initial whitespace or commas */
        while ( ( isspace ( **line ) ) || ( **line == ',' ) )
                (*line)++;
 
        /* Check for end of line and record token position */
        if ( ! **line )
                return NULL;
        token = *line;
 
        /* Scan for end of token */
        while ( ( c = **line ) ) {
 
                /* Terminate if we hit an unquoted whitespace or comma */
                if ( ( isspace ( c ) || ( c == ',' ) ) && ! quote )
                        break;
 
                /* Terminate if we hit a closing quote */
                if ( c == quote )
                        break;
 
                /* Check for value separator */
                if ( value && ( ! *value ) && ( c == '=' ) ) {
 
                        /* Terminate key portion of token */
                        *((*line)++) = '\0';
 
                        /* Check for quote character */
                        c = **line;
                        if ( ( c == '"' ) || ( c == '\'' ) ) {
                                quote = c;
                                (*line)++;
                        }
 
                        /* Record value portion of token */
                        *value = *line;
 
                } else {
 
                        /* Move to next character */
                        (*line)++;
                }
        }
 
        /* Terminate token, if applicable */
        if ( c )
                *((*line)++) = '\0';
 
        return token;
}

References isspace(), NULL, token, and value.

Referenced by http_parse_connection(), http_parse_digest_auth(), http_parse_status(), and http_parse_www_authenticate().

http_connect()

int http_connect ( struct interface * xfer, struct uri * uri )

extern

Connect to an HTTP server.

Parameters

xfer	Data transfer interface
uri	Connection URI

Return values

rc	Return status code

HTTP connections are pooled. The caller should be prepared to receive a pool_reopen() message.

Definition at line 237 of file httpconn.c.

                                                             {
        struct http_connection *conn;
        struct http_scheme *scheme;
        struct sockaddr_tcpip server;
        unsigned int port;
        int rc;
 
        /* Identify scheme */
        scheme = http_scheme ( uri );
        if ( ! scheme )
                return -ENOTSUP;
 
        /* Sanity check */
        if ( ! uri->host )
                return -EINVAL;
 
        /* Identify port */
        port = uri_port ( uri, scheme->port );
 
        /* Look for a reusable connection in the pool.  Reuse the most
         * recent connection in order to accommodate authentication
         * schemes that break the stateless nature of HTTP and rely on
         * the same connection being reused for authentication
         * responses.
         */
        list_for_each_entry_reverse ( conn, &http_connection_pool, pool.list ) {
 
                /* Sanity checks */
                assert ( conn->uri != NULL );
                assert ( conn->uri->host != NULL );
 
                /* Reuse connection, if possible */
                if ( ( scheme == conn->scheme ) &&
                     ( strcmp ( uri->host, conn->uri->host ) == 0 ) &&
                     ( port == uri_port ( conn->uri, scheme->port ) ) ) {
 
                        /* Remove from connection pool, stop timer,
                         * attach to parent interface, and return.
                         */
                        pool_del ( &conn->pool );
                        intf_plug_plug ( &conn->xfer, xfer );
                        DBGC2 ( conn, "HTTPCONN %p reused %s://%s:%d\n", conn,
                                conn->scheme->name, conn->uri->host, port );
                        return 0;
                }
        }
 
        /* Allocate and initialise structure */
        conn = zalloc ( sizeof ( *conn ) );
        if ( ! conn ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
        ref_init ( &conn->refcnt, http_conn_free );
        conn->uri = uri_get ( uri );
        conn->scheme = scheme;
        intf_init ( &conn->socket, &http_conn_socket_desc, &conn->refcnt );
        intf_init ( &conn->xfer, &http_conn_xfer_desc, &conn->refcnt );
        pool_init ( &conn->pool, http_conn_expired, &conn->refcnt );
 
        /* Open socket */
        memset ( &server, 0, sizeof ( server ) );
        server.st_port = htons ( port );
        if ( ( rc = xfer_open_named_socket ( &conn->socket, SOCK_STREAM,
                                             ( struct sockaddr * ) &server,
                                             uri->host, NULL ) ) != 0 )
                goto err_open;
 
        /* Add filter, if any */
        if ( scheme->filter && ( ( rc = scheme->filter ( conn ) ) != 0 ) )
                goto err_filter;
 
        /* Attach to parent interface, mortalise self, and return */
        intf_plug_plug ( &conn->xfer, xfer );
        ref_put ( &conn->refcnt );
 
        DBGC2 ( conn, "HTTPCONN %p created %s://%s:%d\n", conn,
                conn->scheme->name, conn->uri->host, port );
        return 0;
 
 err_filter:
 err_open:
        DBGC2 ( conn, "HTTPCONN %p could not create %s://%s:%d: %s\n", conn,
                conn->scheme->name, conn->uri->host, port, strerror ( rc ) );
        http_conn_close ( conn, rc );
        ref_put ( &conn->refcnt );
 err_alloc:
        return rc;
}

References assert, DBGC2, EINVAL, ENOMEM, ENOTSUP, http_scheme::filter, uri::host, htons, http_conn_close(), http_conn_expired(), http_conn_free(), http_conn_socket_desc, http_conn_xfer_desc, http_scheme(), intf_init(), intf_plug_plug(), list_for_each_entry_reverse, memset(), http_scheme::name, NULL, http_connection::pool, pool, pool_del(), http_scheme::port, port, rc, ref_init, ref_put, http_connection::refcnt, http_connection::scheme, SOCK_STREAM, http_connection::socket, sockaddr_tcpip::st_port, strcmp(), strerror(), http_connection::uri, uri_get(), uri_port(), http_connection::xfer, xfer_open_named_socket(), and zalloc().

Referenced by http_open(), and http_reopen().

http_open()

int http_open ( struct interface * xfer, struct http_method * method, struct uri * uri, struct http_request_range * range, struct http_request_content * content )

extern

Open HTTP transaction.

Parameters

xfer	Data transfer interface
method	Request method
uri	Request URI
range	Content range (if any)
content	Request content (if any)

Return values

rc	Return status code

Definition at line 642 of file httpcore.c.

                                                       {
        struct http_transaction *http;
        struct uri request_uri;
        struct uri request_host;
        size_t request_uri_len;
        size_t request_host_len;
        size_t content_len;
        char *request_uri_string;
        char *request_host_string;
        void *content_data;
        int rc;
 
        /* Calculate request URI length */
        memset ( &request_uri, 0, sizeof ( request_uri ) );
        request_uri.epath = ( uri->epath ? uri->epath : "/" );
        request_uri.equery = uri->equery;
        request_uri_len =
                ( format_uri ( &request_uri, NULL, 0 ) + 1 /* NUL */);
 
        /* Calculate host name length */
        memset ( &request_host, 0, sizeof ( request_host ) );
        request_host.host = uri->host;
        request_host.port = uri->port;
        request_host_len =
                ( format_uri ( &request_host, NULL, 0 ) + 1 /* NUL */ );
 
        /* Calculate request content length */
        content_len = ( content ? content->len : 0 );
 
        /* Allocate and initialise structure */
        http = zalloc ( sizeof ( *http ) + request_uri_len + request_host_len +
                        content_len );
        if ( ! http ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
        request_uri_string = ( ( ( void * ) http ) + sizeof ( *http ) );
        request_host_string = ( request_uri_string + request_uri_len );
        content_data = ( request_host_string + request_host_len );
        format_uri ( &request_uri, request_uri_string, request_uri_len );
        format_uri ( &request_host, request_host_string, request_host_len );
        ref_init ( &http->refcnt, http_free );
        intf_init ( &http->xfer, &http_xfer_desc, &http->refcnt );
        intf_init ( &http->content, &http_content_desc, &http->refcnt );
        intf_init ( &http->transfer, &http_transfer_desc, &http->refcnt );
        intf_init ( &http->conn, &http_conn_desc, &http->refcnt );
        intf_plug_plug ( &http->transfer, &http->content );
        process_init ( &http->process, &http_process_desc, &http->refcnt );
        timer_init ( &http->retry, http_retry_expired, &http->refcnt );
        timer_init ( &http->watchdog, http_watchdog_expired, &http->refcnt );
        http->uri = uri_get ( uri );
        http->request.method = method;
        http->request.uri = request_uri_string;
        http->request.host = request_host_string;
        if ( range ) {
                memcpy ( &http->request.range, range,
                         sizeof ( http->request.range ) );
        }
        if ( content ) {
                http->request.content.type = content->type;
                http->request.content.data = content_data;
                http->request.content.len = content_len;
                memcpy ( content_data, content->data, content_len );
        }
        http->state = &http_request;
        DBGC2 ( http, "HTTP %p %s://%s%s\n", http, http->uri->scheme,
                http->request.host, http->request.uri );
 
        /* Open connection */
        if ( ( rc = http_connect ( &http->conn, uri ) ) != 0 ) {
                DBGC ( http, "HTTP %p could not connect: %s\n",
                       http, strerror ( rc ) );
                goto err_connect;
        }
 
        /* Start watchdog timer */
        http_watchdog ( http );
 
        /* Attach to parent interface, mortalise self, and return */
        intf_plug_plug ( &http->xfer, xfer );
        ref_put ( &http->refcnt );
        return 0;
 
 err_connect:
        http_close ( http, rc );
        ref_put ( &http->refcnt );
 err_alloc:
        return rc;
}

References http_transaction::conn, http_request::content, http_transaction::content, http_request_content::data, DBGC, DBGC2, ENOMEM, uri::epath, uri::equery, format_uri(), http_request::host, uri::host, http_close(), http_conn_desc, http_connect(), http_content_desc, http_free(), http_process_desc, http_retry_expired(), http_transfer_desc, http_watchdog(), http_watchdog_expired(), http_xfer_desc, intf_init(), intf_plug_plug(), http_request_content::len, memcpy(), memset(), http_request::method, method, NULL, uri::port, http_transaction::process, process_init(), http_request::range, range, rc, ref_init, ref_put, http_transaction::refcnt, http_transaction::request, http_transaction::retry, uri::scheme, http_transaction::state, strerror(), http_transaction::transfer, http_request_content::type, http_request::uri, http_transaction::uri, uri_get(), http_transaction::watchdog, http_transaction::xfer, and zalloc().

Referenced by http_block_read(), http_block_read_capacity(), http_open_uri(), peerblk_raw_open(), peerblk_retrieval_open(), and REQUIRING_SYMBOL().

http_open_uri()

int http_open_uri ( struct interface * xfer, struct uri * uri )

extern

Open HTTP transaction for simple URI.

Parameters

xfer	Data transfer interface
uri	Request URI

Return values

rc	Return status code

Definition at line 1984 of file httpcore.c.

                                                              {
        struct parameters *params = uri->params;
        struct http_request_content content;
        struct http_method *method;
        const char *type;
        void *data;
        size_t len;
        size_t check_len;
        int rc;
 
        /* Calculate length of form parameter list, if any */
        len = ( params ? http_form_params ( params, NULL, 0 ) : 0 );
 
        /* Use POST if and only if there are form parameters */
        if ( len ) {
 
                /* Use POST */
                method = &http_post;
                type = "application/x-www-form-urlencoded";
 
                /* Allocate temporary form parameter list */
                data = zalloc ( len + 1 /* NUL */ );
                if ( ! data ) {
                        rc = -ENOMEM;
                        goto err_alloc;
                }
 
                /* Construct temporary form parameter list */
                check_len = http_form_params ( params, data,
                                               ( len + 1 /* NUL */ ) );
                assert ( check_len == len );
 
        } else {
 
                /* Use GET */
                method = &http_get;
                type = NULL;
                data = NULL;
        }
 
        /* Construct request content */
        content.type = type;
        content.data = data;
        content.len = len;
 
        /* Open HTTP transaction */
        if ( ( rc = http_open ( xfer, method, uri, NULL, &content ) ) != 0 )
                goto err_open;
 
 err_open:
        free ( data );
 err_alloc:
        return rc;
}

References assert, data, http_request_content::data, ENOMEM, free, http_form_params(), http_get, http_open(), http_post, http_request_content::len, len, method, NULL, uri::params, rc, http_request_content::type, type, and zalloc().

Variable Documentation

http_head

struct http_method http_head

extern

HTTP HEAD method.

Definition at line 139 of file httpcore.c.

                               {
        .name = "HEAD",
};

Referenced by http_block_read_capacity(), and http_rx_headers().

http_get

struct http_method http_get

extern

HTTP GET method.

Definition at line 144 of file httpcore.c.

                              {
        .name = "GET",
};

Referenced by http_block_read(), http_open_uri(), and peerblk_raw_open().

http_post

struct http_method http_post

extern

HTTP POST method.

Definition at line 149 of file httpcore.c.

                               {
        .name = "POST",
};

Referenced by http_open_uri(), and peerblk_retrieval_open().