Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-09-22 13:01:16 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'fix/esp_http_server-ws-frame-header-strictness' into 'master'

Browse Source 
Fix(esp http server): ws frame header strictness

Closes SEC-036 and SEC-230

See merge request espressif/esp-idf!48905
This commit is contained in:
Mahavir Jain
2026-07-31 11:56:15 +05:30
parent 3808652972 c4de8d52e7
commit 4090eeeea4
4 changed files with 505 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
components/esp_http_server/src/httpd_ws.c
View File

@@ -47,10 +47,17 @@ static const char *TAG="httpd_ws";
*/
#define HTTPD_WS_CONTINUE 0x00U
#define HTTPD_WS_FIN_BIT 0x80U
#define HTTPD_WS_RSV1_BIT 0x40U
#define HTTPD_WS_RSV2_BIT 0x20U
#define HTTPD_WS_RSV3_BIT 0x10U
#define HTTPD_WS_OPCODE_BITS 0x0fU
#define HTTPD_WS_MASK_BIT 0x80U
#define HTTPD_WS_LENGTH_BITS 0x7fU
/* RFC 6455 §7.4 close status codes used for protocol-error Close frames */
#define HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR 1002U
#define HTTPD_WS_CLOSE_CODE_TOO_BIG 1009U
/*
* The magic GUID string used for handshake
* Please refer to RFC6455 Section 1.3 for more details.
@@ -345,6 +352,66 @@ static esp_err_t httpd_ws_check_req(httpd_req_t *req)
return ESP_OK;
}
/* RFC 6455 §5.5: opcodes 0x8-0xA (CLOSE, PING, PONG) are control frames.
* Reserved control opcodes 0xB-0xF are rejected earlier in httpd_ws_get_frame_type,
* so an explicit whitelist is used here instead of a `>= CLOSE` range compare. */
static inline bool httpd_ws_is_control_opcode(httpd_ws_type_t type)
{
return type == HTTPD_WS_TYPE_CLOSE ||
type == HTTPD_WS_TYPE_PING ||
type == HTTPD_WS_TYPE_PONG;
}
/* Mark the session's pending frame as a CLOSE so the request layer tears the
* socket down after the current request completes. */
static inline void httpd_ws_mark_closing(struct httpd_req_aux *aux)
{
aux->ws_final = true;
aux->ws_type = HTTPD_WS_TYPE_CLOSE;
}
/* Send a Close frame with the given status code and mark the session as closing.
* Always returns ESP_FAIL so callers can write: return httpd_ws_fail_connection(...).
* RFC 6455 §7.1.7
*/
static esp_err_t httpd_ws_fail_connection(httpd_req_t *req, uint16_t close_code)
{
esp_err_t ret = ESP_FAIL;
if (!req || !req->aux) {
return ret;
}
struct httpd_req_aux *aux = req->aux;
if (!aux->sd) {
return ret;
}
httpd_ws_mark_closing(aux);
bool already_closing = aux->sd->ws_close;
aux->sd->ws_close = true;
if (aux->sd->ws_handshake_done && !already_closing) {
uint8_t close_payload[2] = {
(uint8_t)(close_code >> 8U),
(uint8_t)(close_code & 0xffU),
};
httpd_ws_frame_t close_frame = {
.final = true,
.fragmented = false,
.type = HTTPD_WS_TYPE_CLOSE,
.payload = close_payload,
.len = sizeof(close_payload),
};
esp_err_t ret = httpd_ws_send_frame(req, &close_frame);
if (ret != ESP_OK) {
ESP_LOGW(TAG, LOG_FMT("Failed to send CLOSE frame with code %u"), close_code);
}
}
return ret;
}
static esp_err_t httpd_ws_unmask_payload(uint8_t *payload, size_t len, const uint8_t *mask_key, size_t mask_offset)
{
if (len < 1 || !payload) {
@@ -396,6 +463,17 @@ static esp_err_t httpd_ws_recv_frame_internal(httpd_req_t *req, httpd_ws_frame_t
/* Interpret length */
uint8_t init_len = second_byte & HTTPD_WS_LENGTH_BITS;
#if CONFIG_HTTPD_WS_STRICTER_RFC6455
/* RFC 6455 §5.5: control frames MUST have payload <= 125 bytes and
* therefore MUST NOT use the 16- or 64-bit extended length encodings.
*/
if (httpd_ws_is_control_opcode(frame->type) && init_len > 125) {
ESP_LOGE(TAG, LOG_FMT("Invalid control frame length encoding"));
return httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR);
}
#endif /* CONFIG_HTTPD_WS_STRICTER_RFC6455 */
if (init_len < 126) {
/* Case 1: If length is 0-125, then this length bit is 7 bits */
frame->len = init_len;
@@ -408,7 +486,15 @@ static esp_err_t httpd_ws_recv_frame_internal(httpd_req_t *req, httpd_ws_frame_t
return ESP_FAIL;
}
frame->len = ((uint32_t)(length_bytes[0] << 8U) | (length_bytes[1]));
uint16_t length = ((uint16_t)(length_bytes[0] << 8U) | (length_bytes[1]));
#if CONFIG_HTTPD_WS_STRICTER_RFC6455
/* RFC 6455 §5.2: encodings must be minimal; a value < 126 MUST use 7-bit form. */
if (length < 126) {
ESP_LOGE(TAG, LOG_FMT("Invalid WS frame length: non-minimal 16-bit encoding"));
return httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR);
}
#endif /* CONFIG_HTTPD_WS_STRICTER_RFC6455 */
frame->len = length;
} else if (init_len == 127) {
/* Case 3: If length is byte 127, then this frame's length bit is 64 bits */
uint8_t length_bytes[8] = { 0 };
@@ -418,14 +504,34 @@ static esp_err_t httpd_ws_recv_frame_internal(httpd_req_t *req, httpd_ws_frame_t
return ESP_FAIL;
}
frame->len = (((uint64_t)length_bytes[0] << 56U) |
((uint64_t)length_bytes[1] << 48U) |
((uint64_t)length_bytes[2] << 40U) |
((uint64_t)length_bytes[3] << 32U) |
((uint64_t)length_bytes[4] << 24U) |
((uint64_t)length_bytes[5] << 16U) |
((uint64_t)length_bytes[6] << 8U) |
((uint64_t)length_bytes[7]));
#if CONFIG_HTTPD_WS_STRICTER_RFC6455
/* RFC 6455 §5.2: MSB must be 0 */
if (length_bytes[0] & 0x80) {
ESP_LOGE(TAG, LOG_FMT("Invalid WS frame length: MSB must be 0"));
return httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR);
}
#endif /* CONFIG_HTTPD_WS_STRICTER_RFC6455 */
uint64_t length = (uint64_t)length_bytes[0] << 56U |
(uint64_t)length_bytes[1] << 48U |
(uint64_t)length_bytes[2] << 40U |
(uint64_t)length_bytes[3] << 32U |
(uint64_t)length_bytes[4] << 24U |
(uint64_t)length_bytes[5] << 16U |
(uint64_t)length_bytes[6] << 8U |
(uint64_t)length_bytes[7];
#if CONFIG_HTTPD_WS_STRICTER_RFC6455
/* Encoding must be minimal; values <= UINT16_MAX MUST use 16-bit form */
if (length <= UINT16_MAX) {
ESP_LOGE(TAG, LOG_FMT("Invalid WS frame length: non-minimal 64-bit encoding"));
return httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR);
}
#endif /* CONFIG_HTTPD_WS_STRICTER_RFC6455 */
if (length > SIZE_MAX) {
ESP_LOGE(TAG, LOG_FMT("Invalid WS frame length: too large for platform"));
return httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_TOO_BIG);
}
frame->len = (size_t)length;
}
frame->left_len = frame->len;
@@ -439,7 +545,10 @@ static esp_err_t httpd_ws_recv_frame_internal(httpd_req_t *req, httpd_ws_frame_t
} else {
/* If the WS frame from client to server is not masked, it should be rejected.
* Please refer to RFC6455 Section 5.2 for more details. */
ESP_LOGW(TAG, LOG_FMT("WS frame is not properly masked."));
ESP_LOGE(TAG, LOG_FMT("WS frame is not properly masked."));
#if CONFIG_HTTPD_WS_STRICTER_RFC6455
httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR);
#endif /* CONFIG_HTTPD_WS_STRICTER_RFC6455 */
return ESP_ERR_INVALID_STATE;
}
}
@@ -516,6 +625,22 @@ esp_err_t httpd_ws_send_frame_async(httpd_handle_t hd, int fd, httpd_ws_frame_t
return ESP_ERR_INVALID_ARG;
}
struct sock_db *sess = httpd_sess_get(hd, fd);
if (!sess) {
return ESP_ERR_INVALID_ARG;
}
#if CONFIG_HTTPD_WS_STRICTER_RFC6455
/* RFC 6455 §1.4 / §5.5.1: once a CLOSE has been sent or received the
* endpoint MUST NOT transmit any further data frames. Only the CLOSE
* frame itself is permitted so that an in-progress fail-the-connection
* or close-handshake response can still be emitted. */
if (sess->ws_close && frame->type != HTTPD_WS_TYPE_CLOSE) {
ESP_LOGW(TAG, LOG_FMT("Session is closing; refusing non-CLOSE frame (type=0x%02X)"), frame->type);
return ESP_ERR_INVALID_STATE;
}
#endif /* CONFIG_HTTPD_WS_STRICTER_RFC6455 */
/* Prepare Tx buffer - maximum length is 14, which includes 2 bytes header, 8 bytes length, 4 bytes mask key */
uint8_t tx_len = 0;
uint8_t header_buf[10] = {0 };
@@ -526,7 +651,7 @@ esp_err_t httpd_ws_send_frame_async(httpd_handle_t hd, int fd, httpd_ws_frame_t
if (frame->len <= 125) {
header_buf[1] = frame->len & 0x7fU; /* Length for 7 bits */
tx_len = 2;
} else if (frame->len > 125 && frame->len < UINT16_MAX) {
} else if (frame->len > 125 && frame->len <= UINT16_MAX) {
header_buf[1] = 126; /* Length for 16 bits */
header_buf[2] = (frame->len >> 8U) & 0xffU;
header_buf[3] = frame->len & 0xffU;
@@ -547,11 +672,6 @@ esp_err_t httpd_ws_send_frame_async(httpd_handle_t hd, int fd, httpd_ws_frame_t
/* WebSocket server does not required to mask response payload, so leave the MASK bit as 0. */
header_buf[1] &= (~HTTPD_WS_MASK_BIT);
struct sock_db *sess = httpd_sess_get(hd, fd);
if (!sess) {
return ESP_ERR_INVALID_ARG;
}
/* Send off header */
if (sess->send_fn(hd, fd, (const char *)header_buf, tx_len, 0) < 0) {
ESP_LOGW(TAG, LOG_FMT("Failed to send WS header"));
@@ -596,8 +716,7 @@ esp_err_t httpd_ws_get_frame_type(httpd_req_t *req)
/* If we fail to read exactly one byte, this socket FD is invalid or the frame header is incomplete. */
/* Here we mark it as a Close message and close it later. */
ESP_LOGW(TAG, LOG_FMT("Failed to read header byte (socket FD invalid), closing socket now"));
aux->ws_final = true;
aux->ws_type = HTTPD_WS_TYPE_CLOSE;
httpd_ws_mark_closing(aux);
return ESP_OK;
}
@@ -607,6 +726,36 @@ esp_err_t httpd_ws_get_frame_type(httpd_req_t *req)
aux->ws_final = (first_byte & HTTPD_WS_FIN_BIT) != 0;
aux->ws_type = (first_byte & HTTPD_WS_OPCODE_BITS);
#if CONFIG_HTTPD_WS_STRICTER_RFC6455
/* RFC 6455 §5.2: RSV bits MUST be 0 unless an extension has been negotiated.
* This implementation does not support extensions, so any set RSV bit is an error.
*/
if (first_byte & (HTTPD_WS_RSV1_BIT | HTTPD_WS_RSV2_BIT | HTTPD_WS_RSV3_BIT)) {
ESP_LOGE(TAG, LOG_FMT("RSV1, RSV2 or RSV3 bits are set, closing connection"));
return httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR);
}
/* RFC 6455 §5.2: opcodes 0x3–0x7 and 0xB–0xF are reserved and must not be used. */
switch (aux->ws_type) {
case HTTPD_WS_TYPE_CONTINUE:
case HTTPD_WS_TYPE_TEXT:
case HTTPD_WS_TYPE_BINARY:
case HTTPD_WS_TYPE_CLOSE:
case HTTPD_WS_TYPE_PING:
case HTTPD_WS_TYPE_PONG:
break;
default:
ESP_LOGE(TAG, LOG_FMT("Invalid WS frame type: 0x%02X"), aux->ws_type);
return httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR);
}
/* RFC 6455 §5.5: control frames MUST NOT be fragmented (FIN bit must be set). */
if (httpd_ws_is_control_opcode(aux->ws_type) && !aux->ws_final) {
ESP_LOGE(TAG, LOG_FMT("Invalid fragmented control frame: 0x%02X"), aux->ws_type);
return httpd_ws_fail_connection(req, HTTPD_WS_CLOSE_CODE_PROTOCOL_ERROR);
}
#endif /* CONFIG_HTTPD_WS_STRICTER_RFC6455 */
/* If userspace requests control frames, do not deal with the control frames */
if (!sd->ws_control_frames) {
ESP_LOGD(TAG, LOG_FMT("Handler not requests control frames"));