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