qemu/roms/ipxe/src/include/ipxe/http.h

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