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