ESP32 HTTPS Server

Classes | Typedefs | Enumerations | Functions
httpsserver Namespace Reference

## Classes
class | ConnectionContext
| Internal class to handle the state of a connection. More...
class | HTTPConnection
| Represents a single open connection for the plain HTTPServer, without TLS. More...
class | HTTPHeader
| Represents a single name/value pair of an HTTP header. More...
class | HTTPHeaders
| Groups and manages a set of HTTPHeader instances. More...
class | HTTPNode
| Base class for a URL/route-handler in the server. More...
class | HTTPRequest
| Represents the request stream for an HTTP request. More...
class | HTTPResponse
| Represents the response stream of an HTTP request. More...
class | HTTPSConnection
| Connection class for an open TLS-enabled connection to an HTTPSServer. More...
class | HTTPServer
| Main implementation for the plain HTTP server. Use HTTPSServer for TLS support. More...
class | HTTPSServer
| Main implementation of the HTTP Server with TLS support. Use HTTPServer for plain HTTP. More...
class | HTTPValidator
| Internal representation of a validator function. More...
struct | requestparam_t
class | ResolvedResource
| This class represents a resolved resource, meaning the result of mapping a string URL to an HTTPNode. More...
class | ResourceNode
| This HTTPNode represents a route that maps to a regular HTTP request for a resource (static or dynamic) More...
class | ResourceParameters
| Class used to handle access to the URL parameters. More...
class | ResourceResolver
| This class is used internally to resolve a string URL to the corresponding HTTPNode. More...
class | SSLCert
| Certificate and private key that can be passed to the HTTPSServer. More...
struct | WebsocketFrame
class | WebsocketHandler
class | WebsocketInputStreambuf
class | WebsocketNode

## Typedefs
typedef void() | HTTPSMiddlewareFunction(HTTPRequest *req, HTTPResponse *res, std::function< void()> next)
| A middleware function that can be registered at the server. More...
typedef void() | HTTPSCallbackFunction(HTTPRequest *req, HTTPResponse *res)
| A callback function that will be called by the server to handle a request.
typedef bool() | HTTPValidationFunction(std::string)
typedef WebsocketHandler *() | WebsocketHandlerCreator()

## Enumerations
enum | HTTPNodeType { HANDLER_CALLBACK, WEBSOCKET }
enum | SSLKeySize { KEYSIZE_1024 = 1024, KEYSIZE_2048 = 2048, KEYSIZE_4096 = 4096 }
| Defines the key size for key generation. More...

## Functions
void | validationMiddleware (HTTPRequest *req, HTTPResponse *res, std::function< void()> next)
void | handleWebsocketHandshake (HTTPRequest *req, HTTPResponse *res)
std::string | websocketKeyResponseHash (std::string const &key)
int | createSelfSignedCert (SSLCert &certCtx, SSLKeySize keySize, std::string dn, std::string validFrom="20190101000000", std::string validUntil="20300101000000")
| Creates a self-signed certificate on the ESP32. More...
uint32_t | parseUInt (std::string const &s, uint32_t max=0xffffffff)
| Utility function: Parse an unsigned integer from a string More...
int32_t | parseInt (std::string const &s)
| Utility function: Parse a signed integer from a string
std::string | intToString (int i)
| Utility function: Transform an int to a std::string
bool | validateNotEmpty (std::string s)
| Built-in validator function: Checks that a string is not empty.
bool | validateUnsignedInteger (std::string s)
| Built-in validator function: Checks that a value is a positive int More...

## Detailed Description

This file contains some validator functions that can be used to validate URL parameters.

They covor common cases like checking for integer, non-empty, ..., so the user of this library does not need to write them on his own.

## Typedef Documentation

## ◆ HTTPSMiddlewareFunction

typedef void() httpsserver::HTTPSMiddlewareFunction(HTTPRequest *req, HTTPResponse *res, std::function< void()> next)

A middleware function that can be registered at the server.

It will be called before an incoming request is passed to any HTTPSCallbackFunction and may perform operations like redirects or authentication.

It receives the request and response object as well as a function pointer ("next") to pass on processing. This allows chaining those functions. If next() is not called, the HTTPSCallbackFunction that would match the request url will not be invoked. This might become handy if you want to intercept request handling in case of missing authentication. Don't forget to call next in case you want to access your resources, though.

## Enumeration Type Documentation

## ◆ HTTPNodeType

enum httpsserver::HTTPNodeType

Enumerator
HANDLER_CALLBACK | Node with a handler callback function (class ResourceNode)
WEBSOCKET | Node with a websocket handler (class WebsocketNode)

## ◆ SSLKeySize

enum httpsserver::SSLKeySize

Defines the key size for key generation.

Not available if the `HTTPS_DISABLE_SELFSIGNING` compiler flag is set

Enumerator
KEYSIZE_1024 | RSA key with 1024 bit.
KEYSIZE_2048 | RSA key with 2048 bit.
KEYSIZE_4096 | RSA key with 4096 bit.

## Function Documentation

## ◆ createSelfSignedCert()

int httpsserver::createSelfSignedCert | ( | SSLCert & | certCtx,
|  | SSLKeySize | keySize,
|  | std::string | dn,
|  | std::string | validFrom = `"20190101000000"`,
|  | std::string | validUntil = `"20300101000000"`
| ) |  |

Creates a self-signed certificate on the ESP32.

This function creates a new self-signed certificate for the given hostname on the heap. Make sure to clear() it before you delete it.

The distinguished name (dn) parameter has to follow the x509 specifications. An example would be: CN=myesp.local,O=acme,C=US

The strings validFrom and validUntil have to be formatted like this: "20190101000000", "20300101000000"

This will take some time, so you should probably write the certificate data to non-volatile storage when you are done.

Setting the `HTTPS_DISABLE_SELFSIGNING` compiler flag will remove this function from the library

## ◆ handleWebsocketHandshake()

void httpsserver::handleWebsocketHandshake | ( | HTTPRequest * | req,
|  | HTTPResponse * | res
| ) |  |

Handler function for the websocket handshake. Will be used by HTTPConnection if a websocket is detected

## ◆ parseUInt()

uint32_t httpsserver::parseUInt | ( | std::string const & | s,
|  | uint32_t | max = `0xffffffff`
| ) |  |

Utility function: Parse an unsigned integer from a string

The second parameter can be used to define the maximum value that is acceptable

## ◆ validateUnsignedInteger()

bool httpsserver::validateUnsignedInteger | ( | std::string | s | ) |

Built-in validator function: Checks that a value is a positive int

Checks that the value is a positive integer (combine it with newValidateUnsignedIntegerMax if you have constraints regarding the size of that number)

## ◆ validationMiddleware()

void httpsserver::validationMiddleware | ( | HTTPRequest * | req,
|  | HTTPResponse * | res,
|  | std::function< void()> | next
| ) |  |

Middleware function that handles the validation of parameters

## ◆ websocketKeyResponseHash()

std::string httpsserver::websocketKeyResponseHash | ( | std::string const & | key | ) |

Function used to compute the value of the Sec-WebSocket-Accept during Websocket handshake