iPXE
Data Structures | Defines | Enumerations | Functions | Variables
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...

Defines

#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)
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.


Define Documentation

#define HTTP_PORT   80

HTTP default port.

Definition at line 33 of file http.h.

#define HTTPS_PORT   443

HTTPS default port.

Definition at line 36 of file http.h.

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

HTTP scheme table.

Definition at line 56 of file http.h.

Referenced by http_scheme().

Declare an HTTP scheme.

Definition at line 59 of file http.h.

#define HTTP_DIGEST_NC   "00000001"

HTTP Digest authentication client nonce count.

We choose to generate a new client nonce each time.

Definition at line 121 of file http.h.

Referenced by http_digest_authenticate(), and http_format_digest_auth().

#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 127 of file http.h.

#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 134 of file http.h.

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

HTTP request header table.

Definition at line 243 of file http.h.

Referenced by http_format_headers().

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 247 of file http.h.

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

HTTP response header table.

Definition at line 379 of file http.h.

Referenced by http_parse_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 383 of file http.h.

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

HTTP transfer encoding table.

Definition at line 472 of file http.h.

Referenced by http_parse_transfer_encoding().

Declare an HTTP transfer encoding.

Definition at line 476 of file http.h.

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

HTTP content encoding table.

Definition at line 504 of file http.h.

Referenced by http_format_accept_encoding(), and http_parse_content_encoding().

Declare an HTTP content encoding.

Definition at line 508 of file http.h.

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

HTTP authentication scheme table.

Definition at line 546 of file http.h.

Referenced by http_authentication().

Declare an HTTP authentication scheme.

HTTP NTLM authentication scheme.

Definition at line 550 of file http.h.


Enumeration Type Documentation

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 356 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 ( GPL2_OR_LATER_OR_UBDL  )
char* http_token ( char **  line,
char **  value 
)

Get HTTP response token.

Parameters:
lineLine position
valueToken value to fill in (if any)
Return values:
tokenToken, or NULL

Definition at line 190 of file httpcore.c.

References isspace(), NULL, and token.

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

                                                {
        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;
}
int http_connect ( struct interface xfer,
struct uri uri 
)

Connect to an HTTP server.

Parameters:
xferData transfer interface
uriConnection URI
Return values:
rcReturn status code

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

Definition at line 235 of file httpconn.c.

References assert, DBGC2, EINVAL, ENOMEM, ENOTSUP, http_scheme::filter, uri::host, htons, http_conn_close(), http_conn_expired(), http_conn_free(), http_scheme(), intf_init(), intf_plug_plug(), list_for_each_entry_reverse, memset(), http_scheme::name, NULL, http_connection::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().

                                                             {
        struct http_connection *conn;
        struct http_scheme *scheme;
        struct sockaddr_tcpip server;
        struct interface *socket;
        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 );
        socket = &conn->socket;
        if ( scheme->filter &&
             ( ( rc = scheme->filter ( socket, uri->host, &socket ) ) != 0 ) )
                goto err_filter;
        if ( ( rc = xfer_open_named_socket ( socket, SOCK_STREAM,
                                             ( struct sockaddr * ) &server,
                                             uri->host, NULL ) ) != 0 )
                goto err_open;

        /* 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_open:
 err_filter:
        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;
}
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.

Parameters:
xferData transfer interface
methodRequest method
uriRequest URI
rangeContent range (if any)
contentRequest content (if any)
Return values:
rcReturn status code

Definition at line 586 of file httpcore.c.

References http_transaction::conn, http_request::content, http_transaction::content, http_request_content::data, DBGC, DBGC2, ENOMEM, format_uri(), uri::host, http_request::host, http_close(), http_connect(), http_expired(), http_free(), http_request, intf_init(), intf_plug_plug(), http_request_content::len, memcpy(), memset(), http_request::method, method, NULL, uri::path, uri::port, http_transaction::process, process_init(), uri::query, http_request::range, rc, ref_init, ref_put, http_transaction::refcnt, http_transaction::request, uri::scheme, http_transaction::state, strerror(), http_transaction::timer, http_transaction::transfer, http_request_content::type, http_request::uri, http_transaction::uri, uri_get(), http_transaction::xfer, and zalloc().

Referenced by http_block_read(), http_block_read_capacity(), http_open_get_uri(), http_open_post_uri(), peerblk_raw_open(), and peerblk_retrieval_open().

                                                       {
        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.path = ( uri->path ? uri->path : "/" );
        request_uri.query = uri->query;
        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->timer, http_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;
        }

        /* 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;
}
int http_open_uri ( struct interface xfer,
struct uri uri 
)

Open HTTP transaction for simple URI.

Parameters:
xferData transfer interface
uriRequest URI
Return values:
rcReturn status code

Definition at line 1954 of file httpcore.c.

References http_open_get_uri(), http_open_post_uri(), and uri::params.

                                                              {

        /* Open GET/POST URI as applicable */
        if ( uri->params ) {
                return http_open_post_uri ( xfer, uri );
        } else {
                return http_open_get_uri ( xfer, uri );
        }
}

Variable Documentation

HTTP HEAD method.

Definition at line 133 of file httpcore.c.

Referenced by http_block_read_capacity().

HTTP GET method.

Definition at line 138 of file httpcore.c.

Referenced by http_block_read(), and peerblk_raw_open().

HTTP POST method.

Definition at line 143 of file httpcore.c.

Referenced by peerblk_retrieval_open().