/*

 *   This program is free software; you can redistribute it and/or modify

 *   it under the terms of the GNU General Public License as published by

 *   the Free Software Foundation; either version 2 of the License, or

 *   (at your option) any later version.

 *

 *   This program 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 General Public License for more details.

 *

 *   You should have received a copy of the GNU General Public License

 *   along with this program; if not, write to the Free Software

 *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA

 */

/**

 * $Id: 2024e63690676be1101c2b4bc5e3dfcca370311c $

 *

 * @file lib/tls/dtls.c

 * @brief Datagram Transport Layer Security (DTLS)

 *

 * @copyright 2026 Network RADIUS SAS (legal@networkradius.com)

 */

RCSID("$Id: 2024e63690676be1101c2b4bc5e3dfcca370311c $")

USES_APPLE_DEPRECATED_API /* OpenSSL API has been deprecated by Apple */

#ifdef WITH_TLS

#define LOG_PREFIX "tls"

#include <openssl/hmac.h>

#include <openssl/rand.h>

#include <freeradius-devel/protocol/tls/freeradius.h>

#include "base.h"

#include "dtls.h"

#include "log.h"

#include "strerror.h"

/** The key the DTLS cookies are generated with

 *

 * One per process, generated at startup.  Rotating it would invalidate

 * outstanding cookies, which costs a client one extra round trip, and nothing

 * yet needs that.

 */

static uint8_t    dtls_cookie_key[32];

/** Build the cookie from #fr_socket_t in the #fr_tls_connection_t

 *

 * RFC 6347 section 4.2.1 suggests this construction:

 *

 *  Cookie = HMAC(Secret, Client-IP, Client-Parameters)

 *

 * The application hands DTLS a #fr_socket_t, which identifies a particular network connection.  This should

 * be the same for all DTLS calls, and should point to something which has a lifetime shared with the DTLS

 * connection.

 *

 * OpenSSL does not do this work itself.  It's two pairs of cookie callbacks differ.  For the stateless pair,

 * used by SSL_stateless(), "the integrity of the entire cookie ... is automatically verified by HMAC", while

 * for this pair (used for the DTLS HelloVerifyRequest), "the integrity of the cookie is not verified by

 * OpenSSL.  This is an application responsibility."

 *

 * @param[in] ssl the cookie is for.

 * @param[out] out  buffer of at least EVP_MAX_MD_SIZE octets.

 * @param[out] out_len  how much of `out` was written.

 * @return

 *  - 0 on success.

 *  - -1 on failure.

 */

static int dtls_cookie_hmac(SSL *ssl, uint8_t *out, unsigned int *out_len)

{

  fr_tls_session_t  *tls_session = fr_tls_session(ssl);

  /*

   *  Nothing identifies the peer, so there is nothing to bind the

   *  cookie to, and a cookie which proves nothing is worse than

   *  refusing to make one.

   */

  if (!tls_session->cookie) {

    fr_strerror_const("No cookie value set on the session");

    return -1;

  }

#ifdef __COVERITY__

  /*

   *  Coverity doesn't see HMAC() write the digest.  Without the

   *  memset, Coverity reports out as uninitialised in the callers.

   */

  memset(out, 0, EVP_MAX_MD_SIZE);

#endif

  /*

   *  Hash the entire #fr_socket_t, as the application should set this once, and then never change

   *  it.  This method means that we do exactly the same work for IPv4, Ipv6, and (potentially) Unix

   *  sockets with datagrams.

   */

  if (!HMAC(EVP_sha256(), dtls_cookie_key, sizeof(dtls_cookie_key),

      (uint8_t const *) tls_session->cookie, sizeof(*tls_session->cookie),

      out, out_len)) {

    fr_tls_strerror_printf(NULL);

    return -1;

  }

  return 0;

}

/** Generate the cookie which goes into a HelloVerifyRequest

 *

 * @param[in] ssl   the cookie is for.

 * @param[out] cookie   to write.  At most DTLS1_COOKIE_LENGTH octets.

 * @param[out] cookie_len how much was written.

 * @return

 *  - 1 on success, which is what OpenSSL wants.

 *  - 0 on failure, which aborts the handshake.

 */

int fr_dtls_cookie_generate_cb(SSL *ssl, unsigned char *cookie, unsigned int *cookie_len)

{

  uint8_t   hmac[EVP_MAX_MD_SIZE];

  unsigned int  hmac_len;

  static_assert(EVP_MAX_MD_SIZE <= DTLS1_COOKIE_LENGTH,

          "A SHA256 digest has to fit in a DTLS cookie");

  if (dtls_cookie_hmac(ssl, hmac, &hmac_len) < 0) return 0;

  memcpy(cookie, hmac, hmac_len);

  *cookie_len = hmac_len;

  return 1;

}

/** Check the cookie which came back in the second ClientHello

 *

 * @param[in] ssl   the cookie is for.

 * @param[in] cookie    the client echoed back.

 * @param[in] cookie_len  its length.

 * @return

 *  - 1 when the cookie is ours and is for this peer.

 *  - 0 otherwise, which makes OpenSSL ask for another one.

 */

int fr_dtls_cookie_verify_cb(SSL *ssl, unsigned char const *cookie, unsigned int cookie_len)

{

  uint8_t   hmac[EVP_MAX_MD_SIZE];

  unsigned int  hmac_len;

  if (dtls_cookie_hmac(ssl, hmac, &hmac_len) < 0) return 0;

  if (cookie_len != hmac_len) return 0;

  /*

   *  A constant time compare, so that a wrong cookie says only

   *  that it was wrong.

   */

  return CRYPTO_memcmp(cookie, hmac, hmac_len) == 0;

}

/** Generate the per-process cookie key

 *

 * Called once from fr_openssl_init().

 *

 * @return

 *  - 0 on success.

 *  - -1 on failure.

 */

int fr_dtls_cookie_init(void)

{

  if (RAND_bytes(dtls_cookie_key, sizeof(dtls_cookie_key)) != 1) {

    fr_tls_strerror_printf(NULL);

    return -1;

  }

  return 0;

}

/** Set up the parts of a session which only a datagram transport needs

 *

 * Called once per session, after the session knows its MTU, and only when the

 * context was built with DTLS_method().

 *

 * @param[in] tls_session to configure.

 * @param[in] conf    the configuration

 * @return

 *  - 0 on success.

 *  - -1 on failure.

 */

int fr_dtls_session_init(fr_tls_session_t *tls_session, fr_tls_conf_t const *conf)

{

  fr_assert(tls_session->socket_type == SOCK_DGRAM);

  /*

   *  OpenSSL asks the BIO for the MTU of the socket underneath

   *  it.  There is no socket under a memory BIO, so the question

   *  has no answer, and OpenSSL has to be told not to ask and

   *  given the figure instead.

   *

   <* Without both of these the handshake does not complete.

   */

  SSL_set_options(tls_session->ssl, SSL_OP_NO_QUERY_MTU);

  /*

   *  @todo - we should have a way for the application to update the MTU based on expected headers.

   *  i.e. the MTU here should be the "raw" full-packet MTU, not the MTU of the application-layer

   *  contents.

   *

   *  That's because the admin often can find out the raw MTU, or even guess, but knowing how large

   *  the application MTU is depends on IP version, etc.

   */

  tls_session->mtu = conf->fragment_size;

  SSL_set_mtu(tls_session->ssl, tls_session->mtu);

  /*

   *  OpenSSL writes one datagram per BIO_write(), sized to the

   *  MTU above.  The buffer those writes land in is a byte

   *  stream, so without this the boundaries between them are

   *  lost, and the application would send a whole flight as one

   *  oversized datagram.

   */

  if (fr_tls_bio_dbuff_datagram_init(tls_session->from_ssl) < 0) {

    fr_strerror_const("Failed initialising the datagram queue");

    return -1;

  }

  return 0;

}

/** The retransmission timer has fired

 *

 * OpenSSL holds the flight it last sent, and DTLSv1_handle_timeout() puts it

 * back into the outgoing buffer with fresh record sequence numbers.  Writing

 * it is just like any other write.

 *

 * @param[in] tl  the timer fired on.  Unused.

 * @param[in] now Unused.

 * @param[in] uctx  the fr_tls_connection_t.

 */

static void _fr_dtls_timer_expired(UNUSED fr_timer_list_t *tl, UNUSED fr_time_t now, void *uctx)

{

  fr_tls_connection_t *conn = talloc_get_type_abort(uctx, fr_tls_connection_t);

  request_t   *request = conn->request;

  int     ret;

  fr_assert(request != NULL);

  RDEBUG2("(TLS) %s - DTLS retransmission timer fired", conn->name);

  /*

   *  DTLSv1_handle_timeout() asks OpenSSL to retransmit the pending data, and writes those records

   *  via fr_tls_session_msg_cb().  That callback reads the request back off the SSL *, which means

   *  that the request has to be bound across the call.  Without the bind, the callback logs the

   *  retransmitted flight with no request.

   *

   *  A return of < 0 means the handshake has given up, which

   *  OpenSSL reports rather than this code deciding it.

   */

  fr_tls_session_request_bind(conn->tls_session->ssl, request);

  ret = DTLSv1_handle_timeout(conn->tls_session->ssl);

  fr_tls_session_request_unbind(conn->tls_session->ssl);

  if (ret < 0) {

    fr_tls_log_perror(request, "DTLS handshake timed out");

    fr_tls_session_error_add(request, FR_ERROR_VALUE_DTLS_HANDSHAKE_TIMEOUT);

    fr_tls_connection_failed(conn, TLS_CONNECTION_FAIL_TLS);

    return;

  }

  if (fr_tls_connection_write(conn) < 0) {

    fr_tls_connection_failed(conn, TLS_CONNECTION_FAIL_APPLICATION);

    return;

  }

  /*

   *  The interval doubles on each retransmission, so the next one

   *  is not the same as the last one.

   */

  fr_dtls_timer_update(conn);

}

/** Arm or disarm the retransmission timer

 *

 * OpenSSL changes the timer value on every round.  When there's

 * nothing outstanding, the timer is disarmed.

 *

 * @param[in] conn  to update the timer for.

 */

void fr_dtls_timer_update(fr_tls_connection_t *conn)

{

  request_t *request = conn->request;

  struct timeval  tv;

  /*

   *  A stream connection has no timer list, and nothing to time.

   */

  if (!conn->tl) return;

  /*

   *  Anything other than 1 means no timer is wanted.

   */

  if (DTLSv1_get_timeout(conn->tls_session->ssl, &tv) != 1) {

    FR_TIMER_DELETE(&conn->timer_ev);

    return;

  }

  FR_TIMER_DELETE(&conn->timer_ev);

  if (fr_timer_in(conn, conn->tl, &conn->timer_ev, fr_time_delta_from_timeval(&tv),

      false, _fr_dtls_timer_expired, conn) < 0) {

    REDEBUG("(TLS) %s - Failed arming the DTLS retransmission timer", conn->name);

    fr_tls_connection_failed(conn, TLS_CONNECTION_FAIL_APPLICATION);

  }

}

#endif /* WITH_TLS */