iPXE
http.h
Go to the documentation of this file.
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  */
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 */
83  /** Transport layer interface */
84  struct interface socket;
85  /** Data transfer interface */
86  struct interface xfer;
87  /** Pooled connection */
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 */
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 */
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 */
154  /** Username */
155  const char *username;
156  /** Password */
157  const char *password;
158 };
159 
160 /** HTTP request Digest authentication descriptor */
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 */
176  /** Username */
177  const char *username;
178  /** LAN Manager response */
180  /** NT response */
182  /** Authenticate message length */
183  size_t len;
184 };
185 
186 /** HTTP request authentication descriptor */
188  /** Authentication scheme (if any) */
190  /** Per-scheme information */
191  union {
192  /** Basic authentication descriptor */
194  /** Digest authentication descriptor */
196  /** NTLM authentication descriptor */
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 */
213  /** Request URI string */
214  const char *uri;
215  /** Server host name */
216  const char *host;
217  /** Range descriptor */
219  /** Content descriptor */
221  /** Authentication descriptor */
223 };
224 
225 /** An 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 */
256  /** Transfer encoding */
258 };
259 
260 /** HTTP response content descriptor */
262  /** Content length (may be zero) */
263  size_t len;
264  /** Content encoding */
266 };
267 
268 /** HTTP response Basic authorization descriptor */
270 };
271 
272 /** HTTP response Digest authorization descriptor */
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 */
288  /** Challenge message */
290  /** Challenge information */
292 };
293 
294 /** HTTP response authorization descriptor */
296  /** Authentication scheme (if any) */
298  /** Per-scheme information */
299  union {
300  /** Basic authorization descriptor */
302  /** Digest authorization descriptor */
304  /** NTLM authorization descriptor */
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  */
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  */
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 */
343  /** Content descriptor */
345  /** Authorization descriptor */
347  /** Retry delay (in seconds) */
348  unsigned int retry_after;
349  /** Flags */
350  unsigned int flags;
351 };
352 
353 /** HTTP response flags */
355  /** Keep connection alive after close */
357  /** Content length specified */
359  /** Transaction may be retried on failure */
361 };
362 
363 /** An 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 */
416  /** Reference count */
417  struct refcnt refcnt;
418  /** Data transfer interface */
419  struct interface xfer;
420  /** Content-decoded interface */
422  /** Transfer-decoded interface */
424  /** Server connection */
425  struct interface conn;
426  /** Transmit process */
427  struct process process;
428  /** Reconnection timer */
430 
431  /** Request URI */
432  struct uri *uri;
433  /** Request */
435  /** Response */
437  /** Temporary line buffer */
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 */
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 */
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 */
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 */
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 */
struct interface xfer
Data transfer interface.
Definition: http.h:419
A process.
Definition: process.h:17
const char * qop
Quality of protection.
Definition: http.h:165
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
const char * username
Username.
Definition: http.h:163
struct http_response_auth_digest digest
Digest authorization descriptor.
Definition: http.h:303
Content length specified.
Definition: http.h:358
static __always_inline void struct pci_range * range
Definition: efi_pci_api.h:43
struct http_method http_get
HTTP GET method.
Definition: httpcore.c:139
unsigned int flags
Flags.
Definition: http.h:350
struct http_response_auth_basic basic
Basic authorization descriptor.
Definition: http.h:301
void(* close)(struct http_transaction *http, int rc)
Server connection closed.
Definition: http.h:411
size_t start
Range start.
Definition: http.h:137
int(* format)(struct http_transaction *http, char *buf, size_t len)
Construct remaining "Authorization" header line.
Definition: http.h:539
const char * host
Server host name.
Definition: http.h:216
struct ntlm_challenge * challenge
Challenge message.
Definition: http.h:289
HTTP request range descriptor.
Definition: http.h:135
Pooled connections.
int(* format)(struct http_transaction *http, char *buf, size_t len)
Construct remaining header line.
Definition: http.h:236
struct interface conn
Server connection.
Definition: http.h:425
unsigned int port
Default port.
Definition: http.h:44
I/O buffers.
int(* filter)(struct http_connection *conn)
Transport-layer filter (if any)
Definition: http.h:50
const char * name
Header name (e.g.
Definition: http.h:228
Retry timers.
HTTP transaction state.
Definition: http.h:391
struct line_buffer linebuf
Temporary line buffer.
Definition: http.h:438
int(* tx)(struct http_transaction *http)
Transmit data.
Definition: http.h:397
HTTP response NTLM authorization descriptor.
Definition: http.h:287
int(* parse)(struct http_transaction *http, char *line)
Parse header line.
Definition: http.h:373
struct uri * uri
Request URI.
Definition: http.h:432
A retry timer.
Definition: retry.h:21
const char * location
Redirection location.
Definition: http.h:340
An HTTP method.
Definition: http.h:99
struct http_state * state
Transaction state.
Definition: http.h:441
An HTTP authentication scheme.
Definition: http.h:516
#define HTTP_DIGEST_RESPONSE_LEN
HTTP Digest authentication response length.
Definition: http.h:132
A pooled connection.
Definition: pool.h:17
uint8_t method
Definition: ib_mad.h:14
An HTTP request header.
Definition: http.h:226
struct interface socket
Transport layer interface.
Definition: http.h:84
An HTTP content encoding.
Definition: http.h:484
struct http_response_auth auth
Authorization descriptor.
Definition: http.h:346
struct http_request_range range
Range descriptor.
Definition: http.h:218
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
int(* rx)(struct http_transaction *http, struct io_buffer **iobuf)
Receive data.
Definition: http.h:404
struct ntlm_nt_response nt
NT response.
Definition: http.h:181
struct interface xfer
Data transfer interface.
Definition: http.h:86
A reference counter.
Definition: refcnt.h:26
A timer.
Definition: timer.h:28
struct http_request request
Request.
Definition: http.h:434
int(* authenticate)(struct http_transaction *http)
Perform authentication.
Definition: http.h:531
struct http_transfer_encoding * encoding
Transfer encoding.
Definition: http.h:257
Keep connection alive after close.
Definition: http.h:356
struct http_method http_post
HTTP POST method.
Definition: httpcore.c:144
size_t len
Authenticate message length.
Definition: http.h:183
struct http_response response
Response.
Definition: http.h:436
An HTTP transaction.
Definition: http.h:415
char * http_token(char **line, char **value)
Get HTTP response token.
Definition: httpcore.c:191
const char * username
Username.
Definition: http.h:155
HTTP response transfer descriptor.
Definition: http.h:255
const char * uri
Request URI string.
Definition: http.h:214
An object interface.
Definition: interface.h:124
const char * algorithm
Algorithm.
Definition: http.h:279
const char * algorithm
Algorithm.
Definition: http.h:167
size_t len
Accumulated transfer-decoded length.
Definition: http.h:443
Object interfaces.
struct http_request_auth auth
Authentication descriptor.
Definition: http.h:222
struct http_response_content content
Content descriptor.
Definition: http.h:344
HTTP response Basic authorization descriptor.
Definition: http.h:269
HTTP request Digest authentication descriptor.
Definition: http.h:161
const char * name
Name.
Definition: http.h:486
int http_open_uri(struct interface *xfer, struct uri *uri)
Open HTTP transaction for simple URI.
Definition: httpcore.c:1969
#define HTTP_DIGEST_CNONCE_LEN
HTTP Digest authentication client nonce length.
Definition: http.h:125
struct http_request_content content
Content descriptor.
Definition: http.h:220
const char * name
Scheme name (e.g.
Definition: http.h:42
const char * name
Method name (e.g.
Definition: http.h:101
struct http_method http_head
HTTP HEAD method.
Definition: httpcore.c:134
HTTP request content descriptor.
Definition: http.h:143
pseudo_bit_t value[0x00020]
Definition: arbel.h:13
struct ntlm_challenge_info info
Challenge information.
Definition: http.h:291
struct http_content_encoding * encoding
Content encoding.
Definition: http.h:265
struct http_authentication * auth
Authentication scheme (if any)
Definition: http.h:189
const char * name
Header name (e.g.
Definition: http.h:366
size_t len
Content length (may be zero)
Definition: http.h:263
struct interface content
Content-decoded interface.
Definition: http.h:421
int rc
Return status code.
Definition: http.h:338
unsigned int status
Status code.
Definition: http.h:332
struct interface transfer
Transfer-decoded interface.
Definition: http.h:423
const char * type
Content type (if any)
Definition: http.h:145
Processes.
int http_connect(struct interface *xfer, struct uri *uri)
Connect to an HTTP server.
Definition: httpconn.c:236
struct line_buffer headers
Raw response header lines.
Definition: http.h:327
struct http_response_auth_ntlm ntlm
NTLM authorization descriptor.
Definition: http.h:305
const char * nonce
Nonce.
Definition: http.h:281
const void * data
Content data (if any)
Definition: http.h:147
HTTP request NTLM authentication descriptor.
Definition: http.h:175
const char * realm
Realm.
Definition: http.h:275
struct http_scheme * scheme
HTTP scheme.
Definition: http.h:82
size_t len
Range length, or zero for no range request.
Definition: http.h:139
size_t len
Content length.
Definition: http.h:149
struct http_response_transfer transfer
Transfer descriptor.
Definition: http.h:342
An HTTP URI scheme.
Definition: http.h:40
uint32_t len
Length.
Definition: ena.h:14
A Challenge message.
Definition: ntlm.h:100
struct http_authentication * auth
Authentication scheme (if any)
Definition: http.h:297
const char * username
Username.
Definition: http.h:177
struct http_request_auth_ntlm ntlm
NTLM authentication descriptor.
Definition: http.h:197
A line buffer.
Definition: linebuf.h:16
const char * password
Password.
Definition: http.h:157
struct uri * uri
Connection URI.
Definition: http.h:80
struct http_method * method
Method.
Definition: http.h:212
Reference counting.
HTTP response Digest authorization descriptor.
Definition: http.h:273
const char * name
Name (e.g.
Definition: http.h:518
Linker tables.
char cnonce[HTTP_DIGEST_CNONCE_LEN+1]
Client nonce.
Definition: http.h:169
size_t remaining
Chunk length remaining.
Definition: http.h:445
A Uniform Resource Identifier.
Definition: uri.h:64
Transaction may be retried on failure.
Definition: http.h:360
An HTTP request.
Definition: http.h:210
NT LAN Manager (NTLM) authentication.
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.
Definition: httpcore.c:601
int(* parse)(struct http_transaction *http, char *line)
Parse remaining "WWW-Authenticate" header line.
Definition: http.h:525
HTTP request authentication descriptor.
Definition: http.h:187
NTLM challenge information.
Definition: ntlm.h:165
HTTP request Basic authentication descriptor.
Definition: http.h:153
int(* init)(struct http_transaction *http)
Initialise transfer encoding.
Definition: http.h:464
Line buffering.
int(* supported)(struct http_transaction *http)
Check if content encoding is supported for this request.
Definition: http.h:492
const char * name
Name.
Definition: http.h:458
struct http_state state
Receive data state.
Definition: http.h:466
An NT response.
Definition: ntlm.h:144
struct ntlm_lm_response lm
LAN Manager response.
Definition: http.h:179
An HTTP transfer encoding.
Definition: http.h:456
http_response_flags
HTTP response flags.
Definition: http.h:354
struct pooled_connection pool
Pooled connection.
Definition: http.h:88
A LAN Manager response.
Definition: ntlm.h:136
An HTTP response.
Definition: http.h:318
An HTTP connection.
Definition: http.h:71
HTTP response authorization descriptor.
Definition: http.h:295
int(* init)(struct http_transaction *http)
Initialise content encoding.
Definition: http.h:498
char response[HTTP_DIGEST_RESPONSE_LEN+1]
Response.
Definition: http.h:171
const char * opaque
Opaque.
Definition: http.h:283
unsigned int retry_after
Retry delay (in seconds)
Definition: http.h:348
struct http_request_auth_basic basic
Basic authentication descriptor.
Definition: http.h:193
An HTTP response header.
Definition: http.h:364
struct http_request_auth_digest digest
Digest authentication descriptor.
Definition: http.h:195
const char * qop
Quality of protection.
Definition: http.h:277
HTTP response content descriptor.
Definition: http.h:261
A persistent I/O buffer.
Definition: iobuf.h:33