123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566 |
- #ifndef _IPXE_HTTP_H
- #define _IPXE_HTTP_H
-
- /** @file
- *
- * Hyper Text Transport Protocol
- *
- */
-
- FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
-
- #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>
-
- struct http_transaction;
-
- /******************************************************************************
- *
- * HTTP URI schemes
- *
- ******************************************************************************
- */
-
- /** HTTP default port */
- #define HTTP_PORT 80
-
- /** HTTPS default port */
- #define HTTPS_PORT 443
-
- /** An HTTP URI scheme */
- struct http_scheme {
- /** Scheme name (e.g. "http" or "https") */
- const char *name;
- /** Default port */
- unsigned int port;
- /** Transport-layer filter (if any)
- *
- * @v xfer Data transfer interface
- * @v name Host name
- * @v next Next interface
- * @ret rc Return status code
- */
- int ( * filter ) ( struct interface *xfer, const char *name,
- struct interface **next );
- };
-
- /** HTTP scheme table */
- #define HTTP_SCHEMES __table ( struct http_scheme, "http_schemes" )
-
- /** Declare an HTTP scheme */
- #define __http_scheme __table_entry ( HTTP_SCHEMES, 01 )
-
- /******************************************************************************
- *
- * Connections
- *
- ******************************************************************************
- */
-
- /** An HTTP connection
- *
- * This represents a potentially reusable connection to an HTTP
- * server.
- */
- struct http_connection {
- /** Reference count */
- struct refcnt refcnt;
- /** Connection URI
- *
- * This encapsulates the server (and protocol) used for the
- * connection. This may be the origin server or a proxy
- * server.
- */
- struct uri *uri;
- /** HTTP scheme */
- struct http_scheme *scheme;
- /** Transport layer interface */
- struct interface socket;
- /** Data transfer interface */
- struct interface xfer;
- /** Pooled connection */
- struct pooled_connection pool;
- };
-
- /******************************************************************************
- *
- * HTTP methods
- *
- ******************************************************************************
- */
-
- /** An HTTP method */
- struct http_method {
- /** Method name (e.g. "GET" or "POST") */
- const char *name;
- };
-
- extern struct http_method http_head;
- extern struct http_method http_get;
- extern struct http_method http_post;
-
- /******************************************************************************
- *
- * Requests
- *
- ******************************************************************************
- */
-
- /** HTTP Digest authentication client nonce count
- *
- * We choose to generate a new client nonce each time.
- */
- #define HTTP_DIGEST_NC "00000001"
-
- /** HTTP Digest authentication client nonce length
- *
- * We choose to use a 32-bit hex client nonce.
- */
- #define HTTP_DIGEST_CNONCE_LEN 8
-
- /** HTTP Digest authentication response length
- *
- * The Digest authentication response is a Base16-encoded 16-byte MD5
- * checksum.
- */
- #define HTTP_DIGEST_RESPONSE_LEN 32
-
- /** HTTP request range descriptor */
- struct http_request_range {
- /** Range start */
- size_t start;
- /** Range length, or zero for no range request */
- size_t len;
- };
-
- /** HTTP request content descriptor */
- struct http_request_content {
- /** Content type (if any) */
- const char *type;
- /** Content data (if any) */
- const void *data;
- /** Content length */
- size_t len;
- };
-
- /** HTTP request Basic authentication descriptor */
- struct http_request_auth_basic {
- /** Username */
- const char *username;
- /** Password */
- const char *password;
- };
-
- /** HTTP request Digest authentication descriptor */
- struct http_request_auth_digest {
- /** Username */
- const char *username;
- /** Quality of protection */
- const char *qop;
- /** Algorithm */
- const char *algorithm;
- /** Client nonce */
- char cnonce[ HTTP_DIGEST_CNONCE_LEN + 1 /* NUL */ ];
- /** Response */
- char response[ HTTP_DIGEST_RESPONSE_LEN + 1 /* NUL */ ];
- };
-
- /** HTTP request NTLM authentication descriptor */
- struct http_request_auth_ntlm {
- /** Username */
- const char *username;
- /** LAN Manager response */
- struct ntlm_lm_response lm;
- /** NT response */
- struct ntlm_nt_response nt;
- /** Authenticate message length */
- size_t len;
- };
-
- /** HTTP request authentication descriptor */
- struct http_request_auth {
- /** Authentication scheme (if any) */
- struct http_authentication *auth;
- /** Per-scheme information */
- union {
- /** Basic authentication descriptor */
- struct http_request_auth_basic basic;
- /** Digest authentication descriptor */
- struct http_request_auth_digest digest;
- /** NTLM authentication descriptor */
- struct http_request_auth_ntlm ntlm;
- };
- };
-
- /** An HTTP request
- *
- * This represents a single request to be sent to a server, including
- * the values required to construct all headers.
- *
- * Pointers within this structure must point to storage which is
- * guaranteed to remain valid for the lifetime of the containing HTTP
- * transaction.
- */
- struct http_request {
- /** Method */
- struct http_method *method;
- /** Request URI string */
- const char *uri;
- /** Server host name */
- const char *host;
- /** Range descriptor */
- struct http_request_range range;
- /** Content descriptor */
- struct http_request_content content;
- /** Authentication descriptor */
- struct http_request_auth auth;
- };
-
- /** An HTTP request header */
- struct http_request_header {
- /** Header name (e.g. "User-Agent") */
- const char *name;
- /** Construct remaining header line
- *
- * @v http HTTP transaction
- * @v buf Buffer
- * @v len Length of buffer
- * @ret len Header length if present, or negative error
- */
- int ( * format ) ( struct http_transaction *http, char *buf,
- size_t len );
- };
-
- /** HTTP request header table */
- #define HTTP_REQUEST_HEADERS \
- __table ( struct http_request_header, "http_request_headers" )
-
- /** Declare an HTTP request header */
- #define __http_request_header __table_entry ( HTTP_REQUEST_HEADERS, 01 )
-
- /******************************************************************************
- *
- * Responses
- *
- ******************************************************************************
- */
-
- /** HTTP response transfer descriptor */
- struct http_response_transfer {
- /** Transfer encoding */
- struct http_transfer_encoding *encoding;
- };
-
- /** HTTP response content descriptor */
- struct http_response_content {
- /** Content length (may be zero) */
- size_t len;
- /** Content encoding */
- struct http_content_encoding *encoding;
- };
-
- /** HTTP response Basic authorization descriptor */
- struct http_response_auth_basic {
- };
-
- /** HTTP response Digest authorization descriptor */
- struct http_response_auth_digest {
- /** Realm */
- const char *realm;
- /** Quality of protection */
- const char *qop;
- /** Algorithm */
- const char *algorithm;
- /** Nonce */
- const char *nonce;
- /** Opaque */
- const char *opaque;
- };
-
- /** HTTP response NTLM authorization descriptor */
- struct http_response_auth_ntlm {
- /** Challenge message */
- struct ntlm_challenge *challenge;
- /** Challenge information */
- struct ntlm_challenge_info info;
- };
-
- /** HTTP response authorization descriptor */
- struct http_response_auth {
- /** Authentication scheme (if any) */
- struct http_authentication *auth;
- /** Per-scheme information */
- union {
- /** Basic authorization descriptor */
- struct http_response_auth_basic basic;
- /** Digest authorization descriptor */
- struct http_response_auth_digest digest;
- /** NTLM authorization descriptor */
- struct http_response_auth_ntlm ntlm;
- };
- };
-
- /** An HTTP response
- *
- * This represents a single response received from the server,
- * including all values parsed from headers.
- *
- * Pointers within this structure may point into the raw response
- * buffer, and so should be invalidated when the response buffer is
- * modified or discarded.
- */
- struct http_response {
- /** Raw response header lines
- *
- * This is the raw response data received from the server, up
- * to and including the terminating empty line. String
- * pointers within the response may point into this data
- * buffer; NUL terminators will be added (overwriting the
- * original terminating characters) as needed.
- */
- struct line_buffer headers;
- /** Status code
- *
- * This is the raw HTTP numeric status code (e.g. 404).
- */
- unsigned int status;
- /** Return status code
- *
- * This is the iPXE return status code corresponding to the
- * HTTP status code (e.g. -ENOENT).
- */
- int rc;
- /** Redirection location */
- const char *location;
- /** Transfer descriptor */
- struct http_response_transfer transfer;
- /** Content descriptor */
- struct http_response_content content;
- /** Authorization descriptor */
- struct http_response_auth auth;
- /** Retry delay (in seconds) */
- unsigned int retry_after;
- /** Flags */
- unsigned int flags;
- };
-
- /** HTTP response flags */
- enum http_response_flags {
- /** 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,
- };
-
- /** An HTTP response header */
- struct http_response_header {
- /** Header name (e.g. "Transfer-Encoding") */
- const char *name;
- /** Parse header line
- *
- * @v http HTTP transaction
- * @v line Remaining header line
- * @ret rc Return status code
- */
- int ( * parse ) ( struct http_transaction *http, char *line );
- };
-
- /** HTTP response header table */
- #define HTTP_RESPONSE_HEADERS \
- __table ( struct http_response_header, "http_response_headers" )
-
- /** Declare an HTTP response header */
- #define __http_response_header __table_entry ( HTTP_RESPONSE_HEADERS, 01 )
-
- /******************************************************************************
- *
- * Transactions
- *
- ******************************************************************************
- */
-
- /** HTTP transaction state */
- struct http_state {
- /** Transmit data
- *
- * @v http HTTP transaction
- * @ret rc Return status code
- */
- int ( * tx ) ( struct http_transaction *http );
- /** Receive data
- *
- * @v http HTTP transaction
- * @v iobuf I/O buffer (may be claimed)
- * @ret rc Return status code
- */
- int ( * rx ) ( struct http_transaction *http,
- struct io_buffer **iobuf );
- /** Server connection closed
- *
- * @v http HTTP transaction
- * @v rc Reason for close
- */
- void ( * close ) ( struct http_transaction *http, int rc );
- };
-
- /** An HTTP transaction */
- struct http_transaction {
- /** Reference count */
- struct refcnt refcnt;
- /** Data transfer interface */
- struct interface xfer;
- /** Content-decoded interface */
- struct interface content;
- /** Transfer-decoded interface */
- struct interface transfer;
- /** Server connection */
- struct interface conn;
- /** Transmit process */
- struct process process;
- /** Reconnection timer */
- struct retry_timer timer;
-
- /** Request URI */
- struct uri *uri;
- /** Request */
- struct http_request request;
- /** Response */
- struct http_response response;
- /** Temporary line buffer */
- struct line_buffer linebuf;
-
- /** Transaction state */
- struct http_state *state;
- /** Accumulated transfer-decoded length */
- size_t len;
- /** Chunk length remaining */
- size_t remaining;
- };
-
- /******************************************************************************
- *
- * Transfer encoding
- *
- ******************************************************************************
- */
-
- /** An HTTP transfer encoding */
- struct http_transfer_encoding {
- /** Name */
- const char *name;
- /** Initialise transfer encoding
- *
- * @v http HTTP transaction
- * @ret rc Return status code
- */
- int ( * init ) ( struct http_transaction *http );
- /** Receive data state */
- struct http_state state;
- };
-
- /** HTTP transfer encoding table */
- #define HTTP_TRANSFER_ENCODINGS \
- __table ( struct http_transfer_encoding, "http_transfer_encodings" )
-
- /** Declare an HTTP transfer encoding */
- #define __http_transfer_encoding __table_entry ( HTTP_TRANSFER_ENCODINGS, 01 )
-
- /******************************************************************************
- *
- * Content encoding
- *
- ******************************************************************************
- */
-
- /** An HTTP content encoding */
- struct http_content_encoding {
- /** Name */
- const char *name;
- /** Check if content encoding is supported for this request
- *
- * @v http HTTP transaction
- * @ret supported Content encoding is supported for this request
- */
- int ( * supported ) ( struct http_transaction *http );
- /** Initialise content encoding
- *
- * @v http HTTP transaction
- * @ret rc Return status code
- */
- int ( * init ) ( struct http_transaction *http );
- };
-
- /** HTTP content encoding table */
- #define HTTP_CONTENT_ENCODINGS \
- __table ( struct http_content_encoding, "http_content_encodings" )
-
- /** Declare an HTTP content encoding */
- #define __http_content_encoding __table_entry ( HTTP_CONTENT_ENCODINGS, 01 )
-
- /******************************************************************************
- *
- * Authentication
- *
- ******************************************************************************
- */
-
- /** An HTTP authentication scheme */
- struct http_authentication {
- /** Name (e.g. "Digest") */
- const char *name;
- /** Parse remaining "WWW-Authenticate" header line
- *
- * @v http HTTP transaction
- * @v line Remaining header line
- * @ret rc Return status code
- */
- int ( * parse ) ( struct http_transaction *http, char *line );
- /** Perform authentication
- *
- * @v http HTTP transaction
- * @ret rc Return status code
- */
- int ( * authenticate ) ( struct http_transaction *http );
- /** Construct remaining "Authorization" header line
- *
- * @v http HTTP transaction
- * @v buf Buffer
- * @v len Length of buffer
- * @ret len Header length if present, or negative error
- */
- int ( * format ) ( struct http_transaction *http, char *buf,
- size_t len );
- };
-
- /** HTTP authentication scheme table */
- #define HTTP_AUTHENTICATIONS \
- __table ( struct http_authentication, "http_authentications" )
-
- /** Declare an HTTP authentication scheme */
- #define __http_authentication __table_entry ( HTTP_AUTHENTICATIONS, 01 )
-
- /******************************************************************************
- *
- * General
- *
- ******************************************************************************
- */
-
- extern char * http_token ( char **line, char **value );
- extern int http_connect ( struct interface *xfer, struct uri *uri );
- extern int http_open ( struct interface *xfer, struct http_method *method,
- struct uri *uri, struct http_request_range *range,
- struct http_request_content *content );
- extern int http_open_uri ( struct interface *xfer, struct uri *uri );
-
- #endif /* _IPXE_HTTP_H */
|