iPXE
http.h
Go to the documentation of this file.
00001 #ifndef _IPXE_HTTP_H
00002 #define _IPXE_HTTP_H
00003 
00004 /** @file
00005  *
00006  * Hyper Text Transport Protocol
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <stdint.h>
00013 #include <ipxe/refcnt.h>
00014 #include <ipxe/interface.h>
00015 #include <ipxe/iobuf.h>
00016 #include <ipxe/process.h>
00017 #include <ipxe/retry.h>
00018 #include <ipxe/linebuf.h>
00019 #include <ipxe/pool.h>
00020 #include <ipxe/tables.h>
00021 #include <ipxe/ntlm.h>
00022 
00023 struct http_transaction;
00024 
00025 /******************************************************************************
00026  *
00027  * HTTP URI schemes
00028  *
00029  ******************************************************************************
00030  */
00031 
00032 /** HTTP default port */
00033 #define HTTP_PORT 80
00034 
00035 /** HTTPS default port */
00036 #define HTTPS_PORT 443
00037 
00038 /** An HTTP URI scheme */
00039 struct http_scheme {
00040         /** Scheme name (e.g. "http" or "https") */
00041         const char *name;
00042         /** Default port */
00043         unsigned int port;
00044         /** Transport-layer filter (if any)
00045          *
00046          * @v xfer              Data transfer interface
00047          * @v name              Host name
00048          * @v next              Next interface
00049          * @ret rc              Return status code
00050          */
00051         int ( * filter ) ( struct interface *xfer, const char *name,
00052                            struct interface **next );
00053 };
00054 
00055 /** HTTP scheme table */
00056 #define HTTP_SCHEMES __table ( struct http_scheme, "http_schemes" )
00057 
00058 /** Declare an HTTP scheme */
00059 #define __http_scheme __table_entry ( HTTP_SCHEMES, 01 )
00060 
00061 /******************************************************************************
00062  *
00063  * Connections
00064  *
00065  ******************************************************************************
00066  */
00067 
00068 /** An HTTP connection
00069  *
00070  * This represents a potentially reusable connection to an HTTP
00071  * server.
00072  */
00073 struct http_connection {
00074         /** Reference count */
00075         struct refcnt refcnt;
00076         /** Connection URI
00077          *
00078          * This encapsulates the server (and protocol) used for the
00079          * connection.  This may be the origin server or a proxy
00080          * server.
00081          */
00082         struct uri *uri;
00083         /** HTTP scheme */
00084         struct http_scheme *scheme;
00085         /** Transport layer interface */
00086         struct interface socket;
00087         /** Data transfer interface */
00088         struct interface xfer;
00089         /** Pooled connection */
00090         struct pooled_connection pool;
00091 };
00092 
00093 /******************************************************************************
00094  *
00095  * HTTP methods
00096  *
00097  ******************************************************************************
00098  */
00099 
00100 /** An HTTP method */
00101 struct http_method {
00102         /** Method name (e.g. "GET" or "POST") */
00103         const char *name;
00104 };
00105 
00106 extern struct http_method http_head;
00107 extern struct http_method http_get;
00108 extern struct http_method http_post;
00109 
00110 /******************************************************************************
00111  *
00112  * Requests
00113  *
00114  ******************************************************************************
00115  */
00116 
00117 /** HTTP Digest authentication client nonce count
00118  *
00119  * We choose to generate a new client nonce each time.
00120  */
00121 #define HTTP_DIGEST_NC "00000001"
00122 
00123 /** HTTP Digest authentication client nonce length
00124  *
00125  * We choose to use a 32-bit hex client nonce.
00126  */
00127 #define HTTP_DIGEST_CNONCE_LEN 8
00128 
00129 /** HTTP Digest authentication response length
00130  *
00131  * The Digest authentication response is a Base16-encoded 16-byte MD5
00132  * checksum.
00133  */
00134 #define HTTP_DIGEST_RESPONSE_LEN 32
00135 
00136 /** HTTP request range descriptor */
00137 struct http_request_range {
00138         /** Range start */
00139         size_t start;
00140         /** Range length, or zero for no range request */
00141         size_t len;
00142 };
00143 
00144 /** HTTP request content descriptor */
00145 struct http_request_content {
00146         /** Content type (if any) */
00147         const char *type;
00148         /** Content data (if any) */
00149         const void *data;
00150         /** Content length */
00151         size_t len;
00152 };
00153 
00154 /** HTTP request Basic authentication descriptor */
00155 struct http_request_auth_basic {
00156         /** Username */
00157         const char *username;
00158         /** Password */
00159         const char *password;
00160 };
00161 
00162 /** HTTP request Digest authentication descriptor */
00163 struct http_request_auth_digest {
00164         /** Username */
00165         const char *username;
00166         /** Quality of protection */
00167         const char *qop;
00168         /** Algorithm */
00169         const char *algorithm;
00170         /** Client nonce */
00171         char cnonce[ HTTP_DIGEST_CNONCE_LEN + 1 /* NUL */ ];
00172         /** Response */
00173         char response[ HTTP_DIGEST_RESPONSE_LEN + 1 /* NUL */ ];
00174 };
00175 
00176 /** HTTP request NTLM authentication descriptor */
00177 struct http_request_auth_ntlm {
00178         /** Username */
00179         const char *username;
00180         /** LAN Manager response */
00181         struct ntlm_lm_response lm;
00182         /** NT response */
00183         struct ntlm_nt_response nt;
00184         /** Authenticate message length */
00185         size_t len;
00186 };
00187 
00188 /** HTTP request authentication descriptor */
00189 struct http_request_auth {
00190         /** Authentication scheme (if any) */
00191         struct http_authentication *auth;
00192         /** Per-scheme information */
00193         union {
00194                 /** Basic authentication descriptor */
00195                 struct http_request_auth_basic basic;
00196                 /** Digest authentication descriptor */
00197                 struct http_request_auth_digest digest;
00198                 /** NTLM authentication descriptor */
00199                 struct http_request_auth_ntlm ntlm;
00200         };
00201 };
00202 
00203 /** An HTTP request
00204  *
00205  * This represents a single request to be sent to a server, including
00206  * the values required to construct all headers.
00207  *
00208  * Pointers within this structure must point to storage which is
00209  * guaranteed to remain valid for the lifetime of the containing HTTP
00210  * transaction.
00211  */
00212 struct http_request {
00213         /** Method */
00214         struct http_method *method;
00215         /** Request URI string */
00216         const char *uri;
00217         /** Server host name */
00218         const char *host;
00219         /** Range descriptor */
00220         struct http_request_range range;
00221         /** Content descriptor */
00222         struct http_request_content content;
00223         /** Authentication descriptor */
00224         struct http_request_auth auth;
00225 };
00226 
00227 /** An HTTP request header */
00228 struct http_request_header {
00229         /** Header name (e.g. "User-Agent") */
00230         const char *name;
00231         /** Construct remaining header line
00232          *
00233          * @v http              HTTP transaction
00234          * @v buf               Buffer
00235          * @v len               Length of buffer
00236          * @ret len             Header length if present, or negative error
00237          */
00238         int ( * format ) ( struct http_transaction *http, char *buf,
00239                            size_t len );
00240 };
00241 
00242 /** HTTP request header table */
00243 #define HTTP_REQUEST_HEADERS \
00244         __table ( struct http_request_header, "http_request_headers" )
00245 
00246 /** Declare an HTTP request header */
00247 #define __http_request_header __table_entry ( HTTP_REQUEST_HEADERS, 01 )
00248 
00249 /******************************************************************************
00250  *
00251  * Responses
00252  *
00253  ******************************************************************************
00254  */
00255 
00256 /** HTTP response transfer descriptor */
00257 struct http_response_transfer {
00258         /** Transfer encoding */
00259         struct http_transfer_encoding *encoding;
00260 };
00261 
00262 /** HTTP response content descriptor */
00263 struct http_response_content {
00264         /** Content length (may be zero) */
00265         size_t len;
00266         /** Content encoding */
00267         struct http_content_encoding *encoding;
00268 };
00269 
00270 /** HTTP response Basic authorization descriptor */
00271 struct http_response_auth_basic {
00272 };
00273 
00274 /** HTTP response Digest authorization descriptor */
00275 struct http_response_auth_digest {
00276         /** Realm */
00277         const char *realm;
00278         /** Quality of protection */
00279         const char *qop;
00280         /** Algorithm */
00281         const char *algorithm;
00282         /** Nonce */
00283         const char *nonce;
00284         /** Opaque */
00285         const char *opaque;
00286 };
00287 
00288 /** HTTP response NTLM authorization descriptor */
00289 struct http_response_auth_ntlm {
00290         /** Challenge message */
00291         struct ntlm_challenge *challenge;
00292         /** Challenge information */
00293         struct ntlm_challenge_info info;
00294 };
00295 
00296 /** HTTP response authorization descriptor */
00297 struct http_response_auth {
00298         /** Authentication scheme (if any) */
00299         struct http_authentication *auth;
00300         /** Per-scheme information */
00301         union {
00302                 /** Basic authorization descriptor */
00303                 struct http_response_auth_basic basic;
00304                 /** Digest authorization descriptor */
00305                 struct http_response_auth_digest digest;
00306                 /** NTLM authorization descriptor */
00307                 struct http_response_auth_ntlm ntlm;
00308         };
00309 };
00310 
00311 /** An HTTP response
00312  *
00313  * This represents a single response received from the server,
00314  * including all values parsed from headers.
00315  *
00316  * Pointers within this structure may point into the raw response
00317  * buffer, and so should be invalidated when the response buffer is
00318  * modified or discarded.
00319  */
00320 struct http_response {
00321         /** Raw response header lines
00322          *
00323          * This is the raw response data received from the server, up
00324          * to and including the terminating empty line.  String
00325          * pointers within the response may point into this data
00326          * buffer; NUL terminators will be added (overwriting the
00327          * original terminating characters) as needed.
00328          */
00329         struct line_buffer headers;
00330         /** Status code
00331          *
00332          * This is the raw HTTP numeric status code (e.g. 404).
00333          */
00334         unsigned int status;
00335         /** Return status code
00336          *
00337          * This is the iPXE return status code corresponding to the
00338          * HTTP status code (e.g. -ENOENT).
00339          */
00340         int rc;
00341         /** Redirection location */
00342         const char *location;
00343         /** Transfer descriptor */
00344         struct http_response_transfer transfer;
00345         /** Content descriptor */
00346         struct http_response_content content;
00347         /** Authorization descriptor */
00348         struct http_response_auth auth;
00349         /** Retry delay (in seconds) */
00350         unsigned int retry_after;
00351         /** Flags */
00352         unsigned int flags;
00353 };
00354 
00355 /** HTTP response flags */
00356 enum http_response_flags {
00357         /** Keep connection alive after close */
00358         HTTP_RESPONSE_KEEPALIVE = 0x0001,
00359         /** Content length specified */
00360         HTTP_RESPONSE_CONTENT_LEN = 0x0002,
00361         /** Transaction may be retried on failure */
00362         HTTP_RESPONSE_RETRY = 0x0004,
00363 };
00364 
00365 /** An HTTP response header */
00366 struct http_response_header {
00367         /** Header name (e.g. "Transfer-Encoding") */
00368         const char *name;
00369         /** Parse header line
00370          *
00371          * @v http              HTTP transaction
00372          * @v line              Remaining header line
00373          * @ret rc              Return status code
00374          */
00375         int ( * parse ) ( struct http_transaction *http, char *line );
00376 };
00377 
00378 /** HTTP response header table */
00379 #define HTTP_RESPONSE_HEADERS \
00380         __table ( struct http_response_header, "http_response_headers" )
00381 
00382 /** Declare an HTTP response header */
00383 #define __http_response_header __table_entry ( HTTP_RESPONSE_HEADERS, 01 )
00384 
00385 /******************************************************************************
00386  *
00387  * Transactions
00388  *
00389  ******************************************************************************
00390  */
00391 
00392 /** HTTP transaction state */
00393 struct http_state {
00394         /** Transmit data
00395          *
00396          * @v http              HTTP transaction
00397          * @ret rc              Return status code
00398          */
00399         int ( * tx ) ( struct http_transaction *http );
00400         /** Receive data
00401          *
00402          * @v http              HTTP transaction
00403          * @v iobuf             I/O buffer (may be claimed)
00404          * @ret rc              Return status code
00405          */
00406         int ( * rx ) ( struct http_transaction *http,
00407                        struct io_buffer **iobuf );
00408         /** Server connection closed
00409          *
00410          * @v http              HTTP transaction
00411          * @v rc                Reason for close
00412          */
00413         void ( * close ) ( struct http_transaction *http, int rc );
00414 };
00415 
00416 /** An HTTP transaction */
00417 struct http_transaction {
00418         /** Reference count */
00419         struct refcnt refcnt;
00420         /** Data transfer interface */
00421         struct interface xfer;
00422         /** Content-decoded interface */
00423         struct interface content;
00424         /** Transfer-decoded interface */
00425         struct interface transfer;
00426         /** Server connection */
00427         struct interface conn;
00428         /** Transmit process */
00429         struct process process;
00430         /** Reconnection timer */
00431         struct retry_timer timer;
00432 
00433         /** Request URI */
00434         struct uri *uri;
00435         /** Request */
00436         struct http_request request;
00437         /** Response */
00438         struct http_response response;
00439         /** Temporary line buffer */
00440         struct line_buffer linebuf;
00441 
00442         /** Transaction state */
00443         struct http_state *state;
00444         /** Accumulated transfer-decoded length */
00445         size_t len;
00446         /** Chunk length remaining */
00447         size_t remaining;
00448 };
00449 
00450 /******************************************************************************
00451  *
00452  * Transfer encoding
00453  *
00454  ******************************************************************************
00455  */
00456 
00457 /** An HTTP transfer encoding */
00458 struct http_transfer_encoding {
00459         /** Name */
00460         const char *name;
00461         /** Initialise transfer encoding
00462          *
00463          * @v http              HTTP transaction
00464          * @ret rc              Return status code
00465          */
00466         int ( * init ) ( struct http_transaction *http );
00467         /** Receive data state */
00468         struct http_state state;
00469 };
00470 
00471 /** HTTP transfer encoding table */
00472 #define HTTP_TRANSFER_ENCODINGS \
00473         __table ( struct http_transfer_encoding, "http_transfer_encodings" )
00474 
00475 /** Declare an HTTP transfer encoding */
00476 #define __http_transfer_encoding __table_entry ( HTTP_TRANSFER_ENCODINGS, 01 )
00477 
00478 /******************************************************************************
00479  *
00480  * Content encoding
00481  *
00482  ******************************************************************************
00483  */
00484 
00485 /** An HTTP content encoding */
00486 struct http_content_encoding {
00487         /** Name */
00488         const char *name;
00489         /** Check if content encoding is supported for this request
00490          *
00491          * @v http              HTTP transaction
00492          * @ret supported       Content encoding is supported for this request
00493          */
00494         int ( * supported ) ( struct http_transaction *http );
00495         /** Initialise content encoding
00496          *
00497          * @v http              HTTP transaction
00498          * @ret rc              Return status code
00499          */
00500         int ( * init ) ( struct http_transaction *http );
00501 };
00502 
00503 /** HTTP content encoding table */
00504 #define HTTP_CONTENT_ENCODINGS \
00505         __table ( struct http_content_encoding, "http_content_encodings" )
00506 
00507 /** Declare an HTTP content encoding */
00508 #define __http_content_encoding __table_entry ( HTTP_CONTENT_ENCODINGS, 01 )
00509 
00510 /******************************************************************************
00511  *
00512  * Authentication
00513  *
00514  ******************************************************************************
00515  */
00516 
00517 /** An HTTP authentication scheme */
00518 struct http_authentication {
00519         /** Name (e.g. "Digest") */
00520         const char *name;
00521         /** Parse remaining "WWW-Authenticate" header line
00522          *
00523          * @v http              HTTP transaction
00524          * @v line              Remaining header line
00525          * @ret rc              Return status code
00526          */
00527         int ( * parse ) ( struct http_transaction *http, char *line );
00528         /** Perform authentication
00529          *
00530          * @v http              HTTP transaction
00531          * @ret rc              Return status code
00532          */
00533         int ( * authenticate ) ( struct http_transaction *http );
00534         /** Construct remaining "Authorization" header line
00535          *
00536          * @v http              HTTP transaction
00537          * @v buf               Buffer
00538          * @v len               Length of buffer
00539          * @ret len             Header length if present, or negative error
00540          */
00541         int ( * format ) ( struct http_transaction *http, char *buf,
00542                            size_t len );
00543 };
00544 
00545 /** HTTP authentication scheme table */
00546 #define HTTP_AUTHENTICATIONS \
00547         __table ( struct http_authentication, "http_authentications" )
00548 
00549 /** Declare an HTTP authentication scheme */
00550 #define __http_authentication __table_entry ( HTTP_AUTHENTICATIONS, 01 )
00551 
00552 /******************************************************************************
00553  *
00554  * General
00555  *
00556  ******************************************************************************
00557  */
00558 
00559 extern char * http_token ( char **line, char **value );
00560 extern int http_connect ( struct interface *xfer, struct uri *uri );
00561 extern int http_open ( struct interface *xfer, struct http_method *method,
00562                        struct uri *uri, struct http_request_range *range,
00563                        struct http_request_content *content );
00564 extern int http_open_uri ( struct interface *xfer, struct uri *uri );
00565 
00566 #endif /* _IPXE_HTTP_H */