path: root/lib/ext/heartbeat.c

/*
 * Copyright (C) 2012,2013 Free Software Foundation, Inc.
 * Copyright (C) 2013 Nikos Mavrogiannopoulos
 *
 * Author: Nikos Mavrogiannopoulos
 *
 * This file is part of GnuTLS.
 *
 * The GnuTLS is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>
 *
 */

/* This file implements the TLS heartbeat extension.
 */

#include "errors.h"
#include "gnutls_int.h"
#include <dtls.h>
#include <record.h>
#include <ext/heartbeat.h>
#include <hello_ext.h>
#include <random.h>

#ifdef ENABLE_HEARTBEAT
/**
  * gnutls_heartbeat_enable:
  * @session: is a #gnutls_session_t type.
  * @type: one of the GNUTLS_HB_* flags
  *
  * If this function is called with the %GNUTLS_HB_PEER_ALLOWED_TO_SEND
  * @type, GnuTLS will allow heartbeat messages to be received. Moreover it also
  * request the peer to accept heartbeat messages. This function
  * must be called prior to TLS handshake.
  *
  * If the @type used is %GNUTLS_HB_LOCAL_ALLOWED_TO_SEND, then the peer
  * will be asked to accept heartbeat messages but not send ones.
  *
  * The function gnutls_heartbeat_allowed() can be used to test Whether
  * locally generated heartbeat messages can be accepted by the peer.
  *
  * Since: 3.1.2
  **/
void gnutls_heartbeat_enable(gnutls_session_t session, unsigned int type)
{
	gnutls_ext_priv_data_t epriv;

	epriv = (void*)(intptr_t)type;
	_gnutls_hello_ext_set_priv(session, GNUTLS_EXTENSION_HEARTBEAT,
				     epriv);
}

/**
  * gnutls_heartbeat_allowed:
  * @session: is a #gnutls_session_t type.
  * @type: one of %GNUTLS_HB_LOCAL_ALLOWED_TO_SEND and %GNUTLS_HB_PEER_ALLOWED_TO_SEND
  *
  * This function will check whether heartbeats are allowed
  * to be sent or received in this session. 
  *
  * Returns: Non zero if heartbeats are allowed.
  *
  * Since: 3.1.2
  **/
unsigned gnutls_heartbeat_allowed(gnutls_session_t session, unsigned int type)
{
	gnutls_ext_priv_data_t epriv;

	if (session->internals.handshake_in_progress != 0)
		return 0; /* not allowed */

	if (_gnutls_hello_ext_get_priv
	    (session, GNUTLS_EXTENSION_HEARTBEAT, &epriv) < 0)
		return 0;	/* Not enabled */

	if (type == GNUTLS_HB_LOCAL_ALLOWED_TO_SEND) {
		if (((intptr_t)epriv) & LOCAL_ALLOWED_TO_SEND)
			return 1;
	} else if (((intptr_t)epriv) & GNUTLS_HB_PEER_ALLOWED_TO_SEND)
		return 1;

	return 0;
}

#define DEFAULT_PADDING_SIZE 16

/*
 * Sends heartbeat data.
 */
static int
heartbeat_send_data(gnutls_session_t session, const void *data,
		    size_t data_size, uint8_t type)
{
	int ret, pos;
	uint8_t *response;

	response = gnutls_malloc(1 + 2 + data_size + DEFAULT_PADDING_SIZE);
	if (response == NULL)
		return gnutls_assert_val(GNUTLS_E_MEMORY_ERROR);

	pos = 0;
	response[pos++] = type;

	_gnutls_write_uint16(data_size, &response[pos]);
	pos += 2;

	memcpy(&response[pos], data, data_size);
	pos += data_size;

	ret =
	    gnutls_rnd(GNUTLS_RND_NONCE, &response[pos],
		       DEFAULT_PADDING_SIZE);
	if (ret < 0) {
		gnutls_assert();
		goto cleanup;
	}
	pos += DEFAULT_PADDING_SIZE;

	ret =
	    _gnutls_send_int(session, GNUTLS_HEARTBEAT, -1,
			     EPOCH_WRITE_CURRENT, response, pos,
			     MBUFFER_FLUSH);

      cleanup:
	gnutls_free(response);
	return ret;
}

/**
 * gnutls_heartbeat_ping:
 * @session: is a #gnutls_session_t type.
 * @data_size: is the length of the ping payload.
 * @max_tries: if flags is %GNUTLS_HEARTBEAT_WAIT then this sets the number of retransmissions. Use zero for indefinite (until timeout).
 * @flags: if %GNUTLS_HEARTBEAT_WAIT then wait for pong or timeout instead of returning immediately.
 *
 * This function sends a ping to the peer. If the @flags is set
 * to %GNUTLS_HEARTBEAT_WAIT then it waits for a reply from the peer.
 * 
 * Note that it is highly recommended to use this function with the
 * flag %GNUTLS_HEARTBEAT_WAIT, or you need to handle retransmissions
 * and timeouts manually.
 *
 * The total TLS data transmitted as part of the ping message are given by
 * the following formula: MAX(16, @data_size)+gnutls_record_overhead_size()+3.
 *
 * Returns: %GNUTLS_E_SUCCESS on success, otherwise a negative error code.
 *
 * Since: 3.1.2
 **/
int
gnutls_heartbeat_ping(gnutls_session_t session, size_t data_size,
		      unsigned int max_tries, unsigned int flags)
{
	int ret;
	unsigned int retries = 1, diff;
	struct timespec now;

	if (data_size > MAX_HEARTBEAT_LENGTH)
		return
		    gnutls_assert_val(GNUTLS_E_UNEXPECTED_PACKET_LENGTH);

	if (gnutls_heartbeat_allowed
	    (session, GNUTLS_HB_LOCAL_ALLOWED_TO_SEND) == 0)
		return gnutls_assert_val(GNUTLS_E_INVALID_REQUEST);

	/* resume previous call if interrupted */
	if (session->internals.record_send_buffer.byte_length > 0 &&
	    session->internals.record_send_buffer.head != NULL &&
	    session->internals.record_send_buffer.head->type ==
	    GNUTLS_HEARTBEAT)
		return _gnutls_io_write_flush(session);

	switch (session->internals.hb_state) {
	case SHB_SEND1:
		if (data_size > DEFAULT_PADDING_SIZE)
			data_size -= DEFAULT_PADDING_SIZE;
		else
			data_size = 0;

		_gnutls_buffer_reset(&session->internals.hb_local_data);

		ret =
		    _gnutls_buffer_resize(&session->internals.
					  hb_local_data, data_size);
		if (ret < 0)
			return gnutls_assert_val(ret);

		ret =
		    gnutls_rnd(GNUTLS_RND_NONCE,
				session->internals.hb_local_data.data,
				data_size);
		if (ret < 0)
			return gnutls_assert_val(ret);

		gnutls_gettime(&session->internals.hb_ping_start);
		session->internals.hb_local_data.length = data_size;
		session->internals.hb_state = SHB_SEND2;

		FALLTHROUGH;
	case SHB_SEND2:
		session->internals.hb_actual_retrans_timeout_ms =
		    session->internals.hb_retrans_timeout_ms;
	      retry:
		ret =
		    heartbeat_send_data(session,
					session->internals.hb_local_data.
					data,
					session->internals.hb_local_data.
					length, HEARTBEAT_REQUEST);
		if (ret < 0)
			return gnutls_assert_val(ret);

		gnutls_gettime(&session->internals.hb_ping_sent);

		if (!(flags & GNUTLS_HEARTBEAT_WAIT)) {
			session->internals.hb_state = SHB_SEND1;
			break;
		}

		session->internals.hb_state = SHB_RECV;
		FALLTHROUGH;

	case SHB_RECV:
		ret =
		    _gnutls_recv_int(session, GNUTLS_HEARTBEAT,
				     NULL, 0, NULL,
				     session->internals.
				     hb_actual_retrans_timeout_ms);
		if (ret == GNUTLS_E_HEARTBEAT_PONG_RECEIVED) {
			session->internals.hb_state = SHB_SEND1;
			break;
		} else if (ret == GNUTLS_E_TIMEDOUT) {
			retries++;
			if (max_tries > 0 && retries > max_tries) {
				session->internals.hb_state = SHB_SEND1;
				return gnutls_assert_val(ret);
			}

			gnutls_gettime(&now);
			diff =
			    timespec_sub_ms(&now,
					    &session->internals.
					    hb_ping_start);
			if (diff > session->internals.hb_total_timeout_ms) {
				session->internals.hb_state = SHB_SEND1;
				return
				    gnutls_assert_val(GNUTLS_E_TIMEDOUT);
			}

			session->internals.hb_actual_retrans_timeout_ms *=
			    2;
			session->internals.hb_actual_retrans_timeout_ms %=
			    MAX_DTLS_TIMEOUT;

			session->internals.hb_state = SHB_SEND2;
			goto retry;
		} else if (ret < 0) {
			session->internals.hb_state = SHB_SEND1;
			return gnutls_assert_val(ret);
		}
	}

	return 0;
}

/**
 * gnutls_heartbeat_pong:
 * @session: is a #gnutls_session_t type.
 * @flags: should be zero
 *
 * This function replies to a ping by sending a pong to the peer.
 *
 * Returns: %GNUTLS_E_SUCCESS on success, otherwise a negative error code.
 *
 * Since: 3.1.2
 **/
int gnutls_heartbeat_pong(gnutls_session_t session, unsigned int flags)
{
	int ret;

	if (session->internals.record_send_buffer.byte_length > 0 &&
	    session->internals.record_send_buffer.head != NULL &&
	    session->internals.record_send_buffer.head->type ==
	    GNUTLS_HEARTBEAT)
		return _gnutls_io_write_flush(session);

	if (session->internals.hb_remote_data.length == 0)
		return gnutls_assert_val(GNUTLS_E_INVALID_REQUEST);

	ret =
	    heartbeat_send_data(session,
				session->internals.hb_remote_data.data,
				session->internals.hb_remote_data.length,
				HEARTBEAT_RESPONSE);

	_gnutls_buffer_reset(&session->internals.hb_remote_data);

	if (ret < 0)
		return gnutls_assert_val(ret);

	return 0;
}

/*
 * Processes a heartbeat message. 
 */
int _gnutls_heartbeat_handle(gnutls_session_t session, mbuffer_st * bufel)
{
	int ret;
	unsigned type;
	unsigned pos;
	uint8_t *msg = _mbuffer_get_udata_ptr(bufel);
	size_t hb_len, len = _mbuffer_get_udata_size(bufel);

	if (gnutls_heartbeat_allowed
	    (session, GNUTLS_HB_PEER_ALLOWED_TO_SEND) == 0)
		return gnutls_assert_val(GNUTLS_E_UNEXPECTED_PACKET);

	if (len < 3 + DEFAULT_PADDING_SIZE)
		return
		    gnutls_assert_val(GNUTLS_E_UNEXPECTED_PACKET_LENGTH);

	pos = 0;
	type = msg[pos++];

	hb_len = _gnutls_read_uint16(&msg[pos]);
	if (hb_len > len - 3 - DEFAULT_PADDING_SIZE)
		return
		    gnutls_assert_val(GNUTLS_E_UNEXPECTED_PACKET_LENGTH);

	pos += 2;

	switch (type) {
	case HEARTBEAT_REQUEST:
		_gnutls_buffer_reset(&session->internals.hb_remote_data);

		ret =
		    _gnutls_buffer_resize(&session->internals.
					  hb_remote_data, hb_len);
		if (ret < 0)
			return gnutls_assert_val(ret);

		if (hb_len > 0)
			memcpy(session->internals.hb_remote_data.data,
			       &msg[pos], hb_len);
		session->internals.hb_remote_data.length = hb_len;

		return gnutls_assert_val(GNUTLS_E_HEARTBEAT_PING_RECEIVED);

	case HEARTBEAT_RESPONSE:

		if (hb_len != session->internals.hb_local_data.length)
			return
			    gnutls_assert_val(GNUTLS_E_UNEXPECTED_PACKET);

		if (hb_len > 0 &&
		    memcmp(&msg[pos],
			   session->internals.hb_local_data.data,
			   hb_len) != 0) {
			if (IS_DTLS(session))
				return gnutls_assert_val(GNUTLS_E_AGAIN);	/* ignore it */
			else
				return
				    gnutls_assert_val
				    (GNUTLS_E_UNEXPECTED_PACKET);
		}

		_gnutls_buffer_reset(&session->internals.hb_local_data);

		return gnutls_assert_val(GNUTLS_E_HEARTBEAT_PONG_RECEIVED);
	default:
		_gnutls_record_log
		    ("REC[%p]: HB: received unknown type %u\n", session,
		     type);
		return gnutls_assert_val(GNUTLS_E_UNEXPECTED_PACKET);
	}
}

/**
 * gnutls_heartbeat_get_timeout:
 * @session: is a #gnutls_session_t type.
 *
 * This function will return the milliseconds remaining
 * for a retransmission of the previously sent ping
 * message. This function is useful when ping is used in
 * non-blocking mode, to estimate when to call gnutls_heartbeat_ping()
 * if no packets have been received.
 *
 * Returns: the remaining time in milliseconds.
 *
 * Since: 3.1.2
 **/
unsigned int gnutls_heartbeat_get_timeout(gnutls_session_t session)
{
	struct timespec now;
	unsigned int diff;

	gnutls_gettime(&now);
	diff = timespec_sub_ms(&now, &session->internals.hb_ping_sent);
	if (diff >= session->internals.hb_actual_retrans_timeout_ms)
		return 0;
	else
		return session->internals.hb_actual_retrans_timeout_ms -
		    diff;
}

/**
 * gnutls_heartbeat_set_timeouts:
 * @session: is a #gnutls_session_t type.
 * @retrans_timeout: The time at which a retransmission will occur in milliseconds
 * @total_timeout: The time at which the connection will be aborted, in milliseconds.
 *
 * This function will override the timeouts for the DTLS heartbeat
 * protocol. The retransmission timeout is the time after which a
 * message from the peer is not received, the previous request will
 * be retransmitted. The total timeout is the time after which the
 * handshake will be aborted with %GNUTLS_E_TIMEDOUT.
 *
 * Since: 3.1.2
 **/
void gnutls_heartbeat_set_timeouts(gnutls_session_t session,
				   unsigned int retrans_timeout,
				   unsigned int total_timeout)
{
	session->internals.hb_retrans_timeout_ms = retrans_timeout;
	session->internals.hb_total_timeout_ms = total_timeout;
}


static int
_gnutls_heartbeat_recv_params(gnutls_session_t session,
			      const uint8_t * data, size_t _data_size)
{
	unsigned policy;
	gnutls_ext_priv_data_t epriv;

	if (_gnutls_hello_ext_get_priv
	    (session, GNUTLS_EXTENSION_HEARTBEAT, &epriv) < 0) {
		if (session->security_parameters.entity == GNUTLS_CLIENT)
			return
			    gnutls_assert_val
			    (GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER);
		return 0;	/* Not enabled */
	}

	if (_data_size == 0)
		return GNUTLS_E_UNEXPECTED_PACKET_LENGTH;

	policy = (intptr_t)epriv;

	if (data[0] == 1)
		policy |= LOCAL_ALLOWED_TO_SEND;
	else if (data[0] == 2)
		policy |= LOCAL_NOT_ALLOWED_TO_SEND;
	else
		return
		    gnutls_assert_val(GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER);

	epriv = (void*)(intptr_t)policy;
	_gnutls_hello_ext_set_priv(session, GNUTLS_EXTENSION_HEARTBEAT,
				     epriv);

	return 0;
}

static int
_gnutls_heartbeat_send_params(gnutls_session_t session,
			      gnutls_buffer_st * extdata)
{
	gnutls_ext_priv_data_t epriv;
	uint8_t p;

	if (_gnutls_hello_ext_get_priv
	    (session, GNUTLS_EXTENSION_HEARTBEAT, &epriv) < 0)
		return 0;	/* nothing to send - not enabled */

	if (((intptr_t)epriv) & GNUTLS_HB_PEER_ALLOWED_TO_SEND)
		p = 1;
	else			/*if (epriv.num & GNUTLS_HB_PEER_NOT_ALLOWED_TO_SEND) */
		p = 2;

	if (_gnutls_buffer_append_data(extdata, &p, 1) < 0)
		return gnutls_assert_val(GNUTLS_E_MEMORY_ERROR);

	return 1;
}

static int
_gnutls_heartbeat_pack(gnutls_ext_priv_data_t epriv, gnutls_buffer_st * ps)
{
	int ret;

	BUFFER_APPEND_NUM(ps, (intptr_t)epriv);

	return 0;

}

static int
_gnutls_heartbeat_unpack(gnutls_buffer_st * ps,
			 gnutls_ext_priv_data_t * _priv)
{
	gnutls_ext_priv_data_t epriv;
	int ret;

	BUFFER_POP_CAST_NUM(ps, epriv);

	*_priv = epriv;

	ret = 0;
      error:
	return ret;
}

const hello_ext_entry_st ext_mod_heartbeat = {
	.name = "Heartbeat",
	.tls_id = 15,
	.gid = GNUTLS_EXTENSION_HEARTBEAT,
	.client_parse_point = GNUTLS_EXT_TLS,
	.server_parse_point = GNUTLS_EXT_TLS,
	.validity = GNUTLS_EXT_FLAG_TLS | GNUTLS_EXT_FLAG_DTLS | GNUTLS_EXT_FLAG_CLIENT_HELLO |
		    GNUTLS_EXT_FLAG_EE | GNUTLS_EXT_FLAG_TLS12_SERVER_HELLO,
	.recv_func = _gnutls_heartbeat_recv_params,
	.send_func = _gnutls_heartbeat_send_params,
	.pack_func = _gnutls_heartbeat_pack,
	.unpack_func = _gnutls_heartbeat_unpack,
	.deinit_func = NULL,
	.cannot_be_overriden = 1
};

#else
void gnutls_heartbeat_enable(gnutls_session_t session, unsigned int type)
{
}

unsigned gnutls_heartbeat_allowed(gnutls_session_t session, unsigned int type)
{
	return 0;
}

int
gnutls_heartbeat_ping(gnutls_session_t session, size_t data_size,
		      unsigned int max_tries, unsigned int flags)
{
	return gnutls_assert_val(GNUTLS_E_INVALID_REQUEST);
}

int gnutls_heartbeat_pong(gnutls_session_t session, unsigned int flags)
{
	return gnutls_assert_val(GNUTLS_E_INVALID_REQUEST);
}

unsigned int gnutls_heartbeat_get_timeout(gnutls_session_t session)
{
	return 0;
}

void gnutls_heartbeat_set_timeouts(gnutls_session_t session,
				   unsigned int retrans_timeout,
				   unsigned int total_timeout)
{
	return;
}
#endif