1 #ifndef _IPXE_HTTP_H 2 #define _IPXE_HTTP_H 3 4 /** @file 5 * 6 * Hyper Text Transport Protocol 7 * 8 */ 9 10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL ); 11 12 #include <stdint.h> 13 #include <ipxe/refcnt.h> 14 #include <ipxe/interface.h> 15 #include <ipxe/iobuf.h> 16 #include <ipxe/process.h> 17 #include <ipxe/retry.h> 18 #include <ipxe/linebuf.h> 19 #include <ipxe/pool.h> 20 #include <ipxe/tables.h> 21 #include <ipxe/ntlm.h> 22 23 struct http_transaction; 24 struct http_connection; 25 26 /****************************************************************************** 27 * 28 * HTTP URI schemes 29 * 30 ****************************************************************************** 31 */ 32 33 /** HTTP default port */ 34 #define HTTP_PORT 80 35 36 /** HTTPS default port */ 37 #define HTTPS_PORT 443 38 39 /** An HTTP URI scheme */ 40 struct http_scheme { 41 /** Scheme name (e.g. "http" or "https") */ 42 const char *name; 43 /** Default port */ 44 unsigned int port; 45 /** Transport-layer filter (if any) 46 * 47 * @v conn HTTP connection 48 * @ret rc Return status code 49 */ 50 int ( * filter ) ( struct http_connection *conn ); 51 }; 52 53 /** HTTP scheme table */ 54 #define HTTP_SCHEMES __table ( struct http_scheme, "http_schemes" ) 55 56 /** Declare an HTTP scheme */ 57 #define __http_scheme __table_entry ( HTTP_SCHEMES, 01 ) 58 59 /****************************************************************************** 60 * 61 * Connections 62 * 63 ****************************************************************************** 64 */ 65 66 /** An HTTP connection 67 * 68 * This represents a potentially reusable connection to an HTTP 69 * server. 70 */ 71 struct http_connection { 72 /** Reference count */ 73 struct refcnt refcnt; 74 /** Connection URI 75 * 76 * This encapsulates the server (and protocol) used for the 77 * connection. This may be the origin server or a proxy 78 * server. 79 */ 80 struct uri *uri; 81 /** HTTP scheme */ 82 struct http_scheme *scheme; 83 /** Transport layer interface */ 84 struct interface socket; 85 /** Data transfer interface */ 86 struct interface xfer; 87 /** Pooled connection */ 88 struct pooled_connection pool; 89 }; 90 91 /****************************************************************************** 92 * 93 * HTTP methods 94 * 95 ****************************************************************************** 96 */ 97 98 /** An HTTP method */ 99 struct http_method { 100 /** Method name (e.g. "GET" or "POST") */ 101 const char *name; 102 }; 103 104 extern struct http_method http_head; 105 extern struct http_method http_get; 106 extern struct http_method http_post; 107 108 /****************************************************************************** 109 * 110 * Requests 111 * 112 ****************************************************************************** 113 */ 114 115 /** HTTP Digest authentication client nonce count 116 * 117 * We choose to generate a new client nonce each time. 118 */ 119 #define HTTP_DIGEST_NC "00000001" 120 121 /** HTTP Digest authentication client nonce length 122 * 123 * We choose to use a 32-bit hex client nonce. 124 */ 125 #define HTTP_DIGEST_CNONCE_LEN 8 126 127 /** HTTP Digest authentication response length 128 * 129 * The Digest authentication response is a Base16-encoded 16-byte MD5 130 * checksum. 131 */ 132 #define HTTP_DIGEST_RESPONSE_LEN 32 133 134 /** HTTP request range descriptor */ 135 struct http_request_range { 136 /** Range start */ 137 size_t start; 138 /** Range length, or zero for no range request */ 139 size_t len; 140 }; 141 142 /** HTTP request content descriptor */ 143 struct http_request_content { 144 /** Content type (if any) */ 145 const char *type; 146 /** Content data (if any) */ 147 const void *data; 148 /** Content length */ 149 size_t len; 150 }; 151 152 /** HTTP request Basic authentication descriptor */ 153 struct http_request_auth_basic { 154 /** Username */ 155 const char *username; 156 /** Password */ 157 const char *password; 158 }; 159 160 /** HTTP request Digest authentication descriptor */ 161 struct http_request_auth_digest { 162 /** Username */ 163 const char *username; 164 /** Quality of protection */ 165 const char *qop; 166 /** Algorithm */ 167 const char *algorithm; 168 /** Client nonce */ 169 char cnonce[ HTTP_DIGEST_CNONCE_LEN + 1 /* NUL */ ]; 170 /** Response */ 171 char response[ HTTP_DIGEST_RESPONSE_LEN + 1 /* NUL */ ]; 172 }; 173 174 /** HTTP request NTLM authentication descriptor */ 175 struct http_request_auth_ntlm { 176 /** Username */ 177 const char *username; 178 /** LAN Manager response */ 179 struct ntlm_lm_response lm; 180 /** NT response */ 181 struct ntlm_nt_response nt; 182 /** Authenticate message length */ 183 size_t len; 184 }; 185 186 /** HTTP request authentication descriptor */ 187 struct http_request_auth { 188 /** Authentication scheme (if any) */ 189 struct http_authentication *auth; 190 /** Per-scheme information */ 191 union { 192 /** Basic authentication descriptor */ 193 struct http_request_auth_basic basic; 194 /** Digest authentication descriptor */ 195 struct http_request_auth_digest digest; 196 /** NTLM authentication descriptor */ 197 struct http_request_auth_ntlm ntlm; 198 }; 199 }; 200 201 /** An HTTP request 202 * 203 * This represents a single request to be sent to a server, including 204 * the values required to construct all headers. 205 * 206 * Pointers within this structure must point to storage which is 207 * guaranteed to remain valid for the lifetime of the containing HTTP 208 * transaction. 209 */ 210 struct http_request { 211 /** Method */ 212 struct http_method *method; 213 /** Request URI string */ 214 const char *uri; 215 /** Server host name */ 216 const char *host; 217 /** Range descriptor */ 218 struct http_request_range range; 219 /** Content descriptor */ 220 struct http_request_content content; 221 /** Authentication descriptor */ 222 struct http_request_auth auth; 223 }; 224 225 /** An HTTP request header */ 226 struct http_request_header { 227 /** Header name (e.g. "User-Agent") */ 228 const char *name; 229 /** Construct remaining header line 230 * 231 * @v http HTTP transaction 232 * @v buf Buffer 233 * @v len Length of buffer 234 * @ret len Header length if present, or negative error 235 */ 236 int ( * format ) ( struct http_transaction *http, char *buf, 237 size_t len ); 238 }; 239 240 /** HTTP request header table */ 241 #define HTTP_REQUEST_HEADERS \ 242 __table ( struct http_request_header, "http_request_headers" ) 243 244 /** Declare an HTTP request header */ 245 #define __http_request_header __table_entry ( HTTP_REQUEST_HEADERS, 01 ) 246 247 /****************************************************************************** 248 * 249 * Responses 250 * 251 ****************************************************************************** 252 */ 253 254 /** HTTP response transfer descriptor */ 255 struct http_response_transfer { 256 /** Transfer encoding */ 257 struct http_transfer_encoding *encoding; 258 }; 259 260 /** HTTP response content descriptor */ 261 struct http_response_content { 262 /** Content length (may be zero) */ 263 size_t len; 264 /** Content encoding */ 265 struct http_content_encoding *encoding; 266 }; 267 268 /** HTTP response Basic authorization descriptor */ 269 struct http_response_auth_basic { 270 }; 271 272 /** HTTP response Digest authorization descriptor */ 273 struct http_response_auth_digest { 274 /** Realm */ 275 const char *realm; 276 /** Quality of protection */ 277 const char *qop; 278 /** Algorithm */ 279 const char *algorithm; 280 /** Nonce */ 281 const char *nonce; 282 /** Opaque */ 283 const char *opaque; 284 }; 285 286 /** HTTP response NTLM authorization descriptor */ 287 struct http_response_auth_ntlm { 288 /** Challenge message */ 289 struct ntlm_challenge *challenge; 290 /** Challenge information */ 291 struct ntlm_challenge_info info; 292 }; 293 294 /** HTTP response authorization descriptor */ 295 struct http_response_auth { 296 /** Authentication scheme (if any) */ 297 struct http_authentication *auth; 298 /** Per-scheme information */ 299 union { 300 /** Basic authorization descriptor */ 301 struct http_response_auth_basic basic; 302 /** Digest authorization descriptor */ 303 struct http_response_auth_digest digest; 304 /** NTLM authorization descriptor */ 305 struct http_response_auth_ntlm ntlm; 306 }; 307 }; 308 309 /** An HTTP response 310 * 311 * This represents a single response received from the server, 312 * including all values parsed from headers. 313 * 314 * Pointers within this structure may point into the raw response 315 * buffer, and so should be invalidated when the response buffer is 316 * modified or discarded. 317 */ 318 struct http_response { 319 /** Raw response header lines 320 * 321 * This is the raw response data received from the server, up 322 * to and including the terminating empty line. String 323 * pointers within the response may point into this data 324 * buffer; NUL terminators will be added (overwriting the 325 * original terminating characters) as needed. 326 */ 327 struct line_buffer headers; 328 /** Status code 329 * 330 * This is the raw HTTP numeric status code (e.g. 404). 331 */ 332 unsigned int status; 333 /** Return status code 334 * 335 * This is the iPXE return status code corresponding to the 336 * HTTP status code (e.g. -ENOENT). 337 */ 338 int rc; 339 /** Redirection location */ 340 const char *location; 341 /** Transfer descriptor */ 342 struct http_response_transfer transfer; 343 /** Content descriptor */ 344 struct http_response_content content; 345 /** Authorization descriptor */ 346 struct http_response_auth auth; 347 /** Retry delay (in seconds) */ 348 unsigned int retry_after; 349 /** Flags */ 350 unsigned int flags; 351 }; 352 353 /** HTTP response flags */ 354 enum http_response_flags { 355 /** Keep connection alive after close */ 356 HTTP_RESPONSE_KEEPALIVE = 0x0001, 357 /** Content length specified */ 358 HTTP_RESPONSE_CONTENT_LEN = 0x0002, 359 /** Transaction may be retried on failure */ 360 HTTP_RESPONSE_RETRY = 0x0004, 361 }; 362 363 /** An HTTP response header */ 364 struct http_response_header { 365 /** Header name (e.g. "Transfer-Encoding") */ 366 const char *name; 367 /** Parse header line 368 * 369 * @v http HTTP transaction 370 * @v line Remaining header line 371 * @ret rc Return status code 372 */ 373 int ( * parse ) ( struct http_transaction *http, char *line ); 374 }; 375 376 /** HTTP response header table */ 377 #define HTTP_RESPONSE_HEADERS \ 378 __table ( struct http_response_header, "http_response_headers" ) 379 380 /** Declare an HTTP response header */ 381 #define __http_response_header __table_entry ( HTTP_RESPONSE_HEADERS, 01 ) 382 383 /****************************************************************************** 384 * 385 * Transactions 386 * 387 ****************************************************************************** 388 */ 389 390 /** HTTP transaction state */ 391 struct http_state { 392 /** Transmit data 393 * 394 * @v http HTTP transaction 395 * @ret rc Return status code 396 */ 397 int ( * tx ) ( struct http_transaction *http ); 398 /** Receive data 399 * 400 * @v http HTTP transaction 401 * @v iobuf I/O buffer (may be claimed) 402 * @ret rc Return status code 403 */ 404 int ( * rx ) ( struct http_transaction *http, 405 struct io_buffer **iobuf ); 406 /** Server connection closed 407 * 408 * @v http HTTP transaction 409 * @v rc Reason for close 410 */ 411 void ( * close ) ( struct http_transaction *http, int rc ); 412 }; 413 414 /** An HTTP transaction */ 415 struct http_transaction { 416 /** Reference count */ 417 struct refcnt refcnt; 418 /** Data transfer interface */ 419 struct interface xfer; 420 /** Content-decoded interface */ 421 struct interface content; 422 /** Transfer-decoded interface */ 423 struct interface transfer; 424 /** Server connection */ 425 struct interface conn; 426 /** Transmit process */ 427 struct process process; 428 /** Reconnection timer */ 429 struct retry_timer timer; 430 431 /** Request URI */ 432 struct uri *uri; 433 /** Request */ 434 struct http_request request; 435 /** Response */ 436 struct http_response response; 437 /** Temporary line buffer */ 438 struct line_buffer linebuf; 439 440 /** Transaction state */ 441 struct http_state *state; 442 /** Accumulated transfer-decoded length */ 443 size_t len; 444 /** Chunk length remaining */ 445 size_t remaining; 446 }; 447 448 /****************************************************************************** 449 * 450 * Transfer encoding 451 * 452 ****************************************************************************** 453 */ 454 455 /** An HTTP transfer encoding */ 456 struct http_transfer_encoding { 457 /** Name */ 458 const char *name; 459 /** Initialise transfer encoding 460 * 461 * @v http HTTP transaction 462 * @ret rc Return status code 463 */ 464 int ( * init ) ( struct http_transaction *http ); 465 /** Receive data state */ 466 struct http_state state; 467 }; 468 469 /** HTTP transfer encoding table */ 470 #define HTTP_TRANSFER_ENCODINGS \ 471 __table ( struct http_transfer_encoding, "http_transfer_encodings" ) 472 473 /** Declare an HTTP transfer encoding */ 474 #define __http_transfer_encoding __table_entry ( HTTP_TRANSFER_ENCODINGS, 01 ) 475 476 /****************************************************************************** 477 * 478 * Content encoding 479 * 480 ****************************************************************************** 481 */ 482 483 /** An HTTP content encoding */ 484 struct http_content_encoding { 485 /** Name */ 486 const char *name; 487 /** Check if content encoding is supported for this request 488 * 489 * @v http HTTP transaction 490 * @ret supported Content encoding is supported for this request 491 */ 492 int ( * supported ) ( struct http_transaction *http ); 493 /** Initialise content encoding 494 * 495 * @v http HTTP transaction 496 * @ret rc Return status code 497 */ 498 int ( * init ) ( struct http_transaction *http ); 499 }; 500 501 /** HTTP content encoding table */ 502 #define HTTP_CONTENT_ENCODINGS \ 503 __table ( struct http_content_encoding, "http_content_encodings" ) 504 505 /** Declare an HTTP content encoding */ 506 #define __http_content_encoding __table_entry ( HTTP_CONTENT_ENCODINGS, 01 ) 507 508 /****************************************************************************** 509 * 510 * Authentication 511 * 512 ****************************************************************************** 513 */ 514 515 /** An HTTP authentication scheme */ 516 struct http_authentication { 517 /** Name (e.g. "Digest") */ 518 const char *name; 519 /** Parse remaining "WWW-Authenticate" header line 520 * 521 * @v http HTTP transaction 522 * @v line Remaining header line 523 * @ret rc Return status code 524 */ 525 int ( * parse ) ( struct http_transaction *http, char *line ); 526 /** Perform authentication 527 * 528 * @v http HTTP transaction 529 * @ret rc Return status code 530 */ 531 int ( * authenticate ) ( struct http_transaction *http ); 532 /** Construct remaining "Authorization" header line 533 * 534 * @v http HTTP transaction 535 * @v buf Buffer 536 * @v len Length of buffer 537 * @ret len Header length if present, or negative error 538 */ 539 int ( * format ) ( struct http_transaction *http, char *buf, 540 size_t len ); 541 }; 542 543 /** HTTP authentication scheme table */ 544 #define HTTP_AUTHENTICATIONS \ 545 __table ( struct http_authentication, "http_authentications" ) 546 547 /** Declare an HTTP authentication scheme */ 548 #define __http_authentication __table_entry ( HTTP_AUTHENTICATIONS, 01 ) 549 550 /****************************************************************************** 551 * 552 * General 553 * 554 ****************************************************************************** 555 */ 556 557 extern char * http_token ( char **line, char **value ); 558 extern int http_connect ( struct interface *xfer, struct uri *uri ); 559 extern int http_open ( struct interface *xfer, struct http_method *method, 560 struct uri *uri, struct http_request_range *range, 561 struct http_request_content *content ); 562 extern int http_open_uri ( struct interface *xfer, struct uri *uri ); 563 564 #endif /* _IPXE_HTTP_H */ 565