/*

 *   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: 377e6b880f38e5236fda421b1065302ba4b18557 $

 *

 * @file tls/ticket_stateless.c

 * @brief Stateless TLS session tickets, and the `encode session` and `decode session` sections

 *

 * @copyright 2021 Arran Cudbard-Bell (a.cudbardb@freeradius.org)

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

 */

RCSID("$Id: 377e6b880f38e5236fda421b1065302ba4b18557 $")

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

#ifdef WITH_TLS

#define LOG_PREFIX "tls"

#define _TLS_PRIVATE 1

#include <freeradius-devel/internal/internal.h>

#include <freeradius-devel/server/pair.h>

#include <freeradius-devel/unlang/function.h>

#include <freeradius-devel/unlang/subrequest.h>

#include <freeradius-devel/util/debug.h>

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

#include "attrs.h"

#include "base.h"

#include "log.h"

#include "strerror.h"

#include "ticket.h"

#include "verify.h"

#include <openssl/ssl.h>

#include <openssl/kdf.h>

/** Resume after processing `encode session { ... }` or `decode session { ... }`

 *

 * Check the result and return success / fail depending.

 */

static unlang_action_t tls_ticket_stateless_resume(request_t *request, void *uctx)

{

  fr_tls_session_t  *tls_session = talloc_get_type_abort(uctx, fr_tls_session_t);

  fr_pair_t   *vp;

  fr_assert((tls_session->ticket == FR_TLS_TICKET_STATELESS_ENCODE_REQUESTED) ||

      (tls_session->ticket == FR_TLS_TICKET_STATELESS_DECODE_REQUESTED));

  vp = fr_pair_find_by_da(&request->reply_pairs, NULL, attr_tls_packet_type);

  if (!vp || (vp->vp_uint32 != enum_tls_packet_type_success->vb_uint32)) {

    tls_session->ticket = FR_TLS_TICKET_STATELESS_FAILED;

    return UNLANG_ACTION_CALCULATE_RESULT;

  }

  tls_session->ticket = FR_TLS_TICKET_STATELESS_SUCCESS;

  return UNLANG_ACTION_CALCULATE_RESULT;

}

/** Push `encode session { ... }` or `decode session { ... }`

 *

 * @param[in] request   The current request.

 * @param[in] tls_session The current TLS session.

 * @param[in] packet_type Which of the two sections to run.

 * @return

 *  - UNLANG_ACTION_PUSHED_CHILD on success.

 *  - UNLANG_ACTION_FAIL on failure.

 */

static unlang_action_t tls_ticket_stateless_push(request_t *request, fr_tls_session_t *tls_session,

               uint32_t packet_type)

{

  fr_tls_conf_t *conf = tls_session->conf;

  request_t *child;

  unlang_action_t ua;

  fr_assert(conf->virtual_server);

  MEM(child = tls_subrequest_alloc(request, packet_type, &tls_session->session_id));

  fr_tls_session_extra_pairs_copy_to_child(child, tls_session);

  ua = fr_tls_call_push(child, tls_ticket_stateless_resume, conf, tls_session, false);

  if (ua == UNLANG_ACTION_FAIL) {

    REDEBUG("(TLS) Failed calling TLS virtual server");

    talloc_free(child);

    return UNLANG_ACTION_FAIL;

  }

  return ua;

}

/** Push `encode session` or `decode session`, depending on what's needed.

 *

 * @param[in] request   The current request.

 * @param[in] tls_session The current TLS session.

 * @return

 *  - UNLANG_ACTION_CALCULATE_RESULT  - nothing was pending.

 *  - UNLANG_ACTION_PUSHED_CHILD    - a section is running.

 *  - UNLANG_ACTION_FAIL      - the frame could not be pushed.

 */

unlang_action_t fr_tls_ticket_stateless_pending_push(request_t *request, fr_tls_session_t *tls_session)

{

  switch (tls_session->ticket) {

  case FR_TLS_TICKET_STATELESS_ENCODE_REQUESTED:

    return tls_ticket_stateless_push(request, tls_session,

               enum_tls_packet_type_encode_session->vb_uint32);

  case FR_TLS_TICKET_STATELESS_DECODE_REQUESTED:

    return tls_ticket_stateless_push(request, tls_session,

               enum_tls_packet_type_decode_session->vb_uint32);

  default:

    return UNLANG_ACTION_CALCULATE_RESULT;

  }

}

/** Request `encode session { ... }`, and tell the handshake the section is pending

 */

static inline CC_HINT(always_inline) void tls_ticket_stateless_encode_request(fr_tls_session_t *tls_session)

{

  tls_session->ticket = FR_TLS_TICKET_STATELESS_ENCODE_REQUESTED;

  TLS_PENDING_SET(tls_session, FR_TLS_PENDING_STATELESS_TICKET);

}

/** Request `decode session { ... }`, and tell the handshake the section is pending

 */

static inline CC_HINT(always_inline) void tls_ticket_stateless_decode_request(fr_tls_session_t *tls_session)

{

  tls_session->ticket = FR_TLS_TICKET_STATELESS_DECODE_REQUESTED;

  TLS_PENDING_SET(tls_session, FR_TLS_PENDING_STATELESS_TICKET);

}

/** Pause the handshake for `encode session { ... }` or `decode session { ... }`, and read the result

 *

 * We can't run the interpreter inside of a callback, so the caller records

 * what we want to do, and this function tells OpenSSL to pause its

 * processing.  We then return to session.c, which determines that there's

 * work to do, pushes the section, runs it, and calls us again.  That resumes

 * after the ASYNC_pause_job() call.

 *

 * @param[in] request   bound to the session.

 * @param[in] tls_session the ticket belongs to.

 * @param[in] name    of the section, for the log.

 * @param[in] error   to record when the section does not return success.

 * @return

 *  - true if the section ran and approved the session-state list.

 *  - false if it did not, or if it could not be run at all.

 */

static inline CC_HINT(always_inline)

bool tls_ticket_stateless_section_run(request_t *request, fr_tls_session_t *tls_session,

              char const *name, uint32_t error)

{

  /*

   *  Sections are only allowed during the handshake, as

   *  with certificate re-validation.  See the FIXME in

   *  tls_ticket_stateless_app_data_get().

   */

  if (unlikely(!tls_session->can_pause)) {

    fr_assert_msg("Unexpected call to %s. "

            "tls_session_async_handshake_cont must be in call stack", __FUNCTION__);

    tls_session->ticket = FR_TLS_TICKET_STATELESS_INIT;

    return false;

  }

  ASYNC_pause_job();

  /*

   *  If the request was cancelled, reset the ticket state

   *  so that we don't do anything.

   */

  if (unlang_request_is_cancelled(request)) {

    tls_session->ticket = FR_TLS_TICKET_STATELESS_INIT;

    return false;

  }

  if (tls_session->ticket != FR_TLS_TICKET_STATELESS_SUCCESS) {

    REDEBUG("(TLS) `%s` did not return success", name);

    fr_tls_session_error_add(request, error);

    tls_session->ticket = FR_TLS_TICKET_STATELESS_INIT;

    return false;

  }

  tls_session->ticket = FR_TLS_TICKET_STATELESS_INIT;

  return true;

}

/** Run `encode session { ... }` from inside an OpenSSL callback

 *

 * @param[in] request   bound to the session.

 * @param[in] tls_session the ticket belongs to.

 * @return

 *  - true if the section ran and approved the session-state list.

 *  - false if it did not, or if it could not be run at all.

 */

static bool tls_ticket_stateless_encode_run(request_t *request, fr_tls_session_t *tls_session)

{

  fr_assert(tls_session->ticket == FR_TLS_TICKET_STATELESS_INIT);

  tls_ticket_stateless_encode_request(tls_session);

  return tls_ticket_stateless_section_run(request, tls_session, "encode session",

            FR_ERROR_VALUE_ENCODE_SESSION_FAILED);

}

/** Run `decode session { ... }` from inside an OpenSSL callback

 *

 * @param[in] request   bound to the session.

 * @param[in] tls_session the ticket belongs to.

 * @return

 *  - true if the section ran and approved the session-state list.

 *  - false if it did not, or if it could not be run at all.

 */

static bool tls_ticket_stateless_decode_run(request_t *request, fr_tls_session_t *tls_session)

{

  fr_assert(tls_session->ticket == FR_TLS_TICKET_STATELESS_INIT);

  tls_ticket_stateless_decode_request(tls_session);

  return tls_ticket_stateless_section_run(request, tls_session, "decode session",

            FR_ERROR_VALUE_DECODE_SESSION_FAILED);

}

/** Disable stateless session tickets for a given TLS ctx

 *

 * @param[in] ctx to disable session tickets for.

 * @param[in] stateful Are stateful tickets in use.

 */

void fr_tls_ticket_stateless_disable(SSL_CTX *ctx, bool stateful)

{

  long ctx_options = SSL_CTX_get_options(ctx);

  /*

   *  Disable session tickets for older TLS versions

   */

  ctx_options |= SSL_OP_NO_TICKET;

  SSL_CTX_set_options(ctx, ctx_options);

  /*

   *  This controls the number of stateful or stateless

   *  tickets generated with TLS 1.3.

   *  Set to 1 ticket if stateful tickets are in use.

   */

  SSL_CTX_set_num_tickets(ctx, stateful ? 1 : 0);

}

/** Called when new tickets are being generated

 *

 * This adds additional application data to the session ticket to

 * allow us to perform validation checks when the session is

 * resumed.

 */

static int tls_ticket_stateless_app_data_set(SSL *ssl, void *arg)

{

  fr_tls_session_t  *tls_session = fr_tls_session(ssl);

  fr_tls_ticket_conf_t  *tls_cache_conf = arg;  /* Not talloced */

  SSL_SESSION   *sess;

  request_t   *request;

  fr_tls_conf_t   *conf;

  int     ret;

  /*

   *  Check to see if we have a request bound

   *  to the session.  If we don't have a

   *  request there's no application data to

   *  add.

   */

  if (!fr_tls_session_request_bound(ssl)) return 1;

  /*

   *  If the client doesn't support session tickets then there is no

   *  point in adding the application data - it won't get sent.

   */

  if (!tls_session->session_ticket_supported) return 1;

  /*

   *  Encode the complete session state list

   *  as app data.  Then, when the session is

   *  resumed, the session-state list is

   *  repopulated.

   */

  request = fr_tls_session_request(ssl);

  /*

   *  Request was cancelled, don't do anything.

   */

  if (unlang_request_is_cancelled(request)) return 0;

  /*

   *  Fatal error - We definitely shouldn't be

   *      attempting to generate session tickets

   *      if it's not permitted.

   */

  if (!tls_session->allow_session_resumption ||

      (!(tls_cache_conf->mode & FR_TLS_TICKET_STATELESS))) {

    REDEBUG("(TLS) Generating session-tickets is not allowed");

    fr_tls_session_error_add(request, FR_ERROR_VALUE_SESSION_TICKET_NOT_ALLOWED);

    return 0;

  }

  sess = SSL_get_session(ssl);

  if (!sess) {

    REDEBUG("(TLS) Failed retrieving session in session generation callback");

    return 0;

  }

  /*

   *  Run `encode session` to allow the admin to update the

   *  `session-state` list, before we encode it into a

   *  stateless session ticket.

   */

  conf = fr_tls_session_conf(ssl);

  if (conf->encode_session && !tls_ticket_stateless_encode_run(request, tls_session)) {

    REDEBUG("(TLS) Not generating a session-ticket");

    return 0;

  }

  ret = tls_ticket_app_data_set(request, sess, &tls_session->session_id);

  if (ret == 1) tls_session->session_ticket_created = true;

  return ret;

}

/** Called when new tickets are being decoded

 *

 * This adds the session-state attributes back to the current request.

 */

static SSL_TICKET_RETURN tls_ticket_stateless_app_data_get(SSL *ssl, SSL_SESSION *sess,

                     UNUSED unsigned char const *keyname,

                     UNUSED size_t keyname_len,

                     SSL_TICKET_STATUS status,

                     void *arg)

{

  fr_tls_session_t  *tls_session = fr_tls_session(ssl);

  fr_tls_conf_t   *conf = tls_session->conf;

  fr_tls_ticket_conf_t  *tls_cache_conf = arg;  /* Not talloced */

  request_t   *request = NULL;

  if (fr_tls_session_request_bound(ssl)) {

    request = fr_tls_session_request(ssl);

    if (unlang_request_is_cancelled(request)) return SSL_TICKET_RETURN_ABORT;

  }

  if (!tls_session->allow_session_resumption ||

      (!(tls_cache_conf->mode & FR_TLS_TICKET_STATELESS))) {

    ROPTIONAL(RDEBUG2, DEBUG2, "(TLS) Session resumption not enabled for this TLS session, "

        "denying session resumption via session-ticket");

        return SSL_TICKET_RETURN_IGNORE;

  }

  switch (status) {

  case SSL_TICKET_EMPTY:

  case SSL_TICKET_NO_DECRYPT:

  case SSL_TICKET_FATAL_ERR_MALLOC:

  case SSL_TICKET_FATAL_ERR_OTHER:

  case SSL_TICKET_NONE:

#ifdef STATIC_ANALYZER

  default:

#endif

    return SSL_TICKET_RETURN_IGNORE_RENEW; /* Send a new ticket */

  case SSL_TICKET_SUCCESS:

    if (!request) return SSL_TICKET_RETURN_USE;

    break;

  case SSL_TICKET_SUCCESS_RENEW:

    if (!request) return SSL_TICKET_RETURN_USE_RENEW;

    break;

  }

  /*

   *  This restores the contents of &session-state[*]

   *  which hopefully still contains all the certificate

   *  pairs.

   *

   *  Although the SSL_SESSION does contain a copy of

   *  the peer's certificate, it does not contain the

   *  peer's certificate chain, and so isn't reliable

   *  for performing re-validation.

   *

   *  The session ticket includes a lifetime.  But we didn't

   *  generate it, so we don't trust it.  If the ticket has

   *  passed its lifetime, then we reject it and force full

   *  reauthentication.

   */

  if (!tls_ticket_session_resumable(request, &tls_session->session_id, conf, sess)) {

    REDEBUG("(TLS) Session-ticket has too little life left, denying session resumption");

    fr_tls_session_error_add(request, FR_ERROR_VALUE_SESSION_TICKET_EXPIRED);

    return SSL_TICKET_RETURN_IGNORE_RENEW;

  }

  if (tls_ticket_app_data_get(request, sess, &tls_session->session_id) < 0) {

    REDEBUG("(TLS) Denying session resumption via session-ticket");

    return SSL_TICKET_RETURN_IGNORE_RENEW;

  }

  /*

   *  The session-state list is back.  Give policy the chance to

   *  look at what the ticket carried before anything relies on

   *  it, certificate re-validation below included.

   */

  if (conf->decode_session && !tls_ticket_stateless_decode_run(request, tls_session)) {

    REDEBUG("(TLS) Denying session resumption via session-ticket");

    return SSL_TICKET_RETURN_IGNORE_RENEW;

  }

  if (conf->virtual_server && tls_session->verify_peer_cert) {

    RDEBUG2("(TLS) Requesting certificate re-validation for session-ticket");

    /*

     *  This sets the validation state of the tls_session

     *  so that when we call ASYNC_pause_job(), and execution

     *  jumps back to tls_session_async_handshake_cont

     *  (just under SSL_read())

     *  the code there knows what job it needs to push onto

     *  the unlang stack.

     */

    fr_tls_verify_resumed_request(tls_session);

    /*

     *  Cache functions are only allowed during the handshake

     *  FIXME: With TLS 1.3 session tickets can be sent

     *  later... Technically every point where we call

     *  SSL_read() may need to be a yield point.

     */

    if (unlikely(!tls_session->can_pause)) {

      fr_assert_msg("Unexpected call to %s. "

              "tls_session_async_handshake_cont must be in call stack", __FUNCTION__);

      return SSL_TICKET_RETURN_IGNORE_RENEW;

    }

    /*

     *  Jumps back to SSL_read() in session.c

     *

     *  Be aware that if the request is cancelled

     *  whatever was meant to be done during the

     *  time we yielded may not have been completed.

     */

    ASYNC_pause_job();

    /*

     *  If the request was cancelled get everything back into

     *  a known state.

     */

    if (unlang_request_is_cancelled(request)) {

      fr_tls_verify_cert_reset(tls_session);

      return SSL_TICKET_RETURN_ABORT;

    }

    /*

     *  If we couldn't validate the client certificate

     *  give the client the opportunity to send a new

     *  one, but _don't_ allow session resumption.

     */

    if (!fr_tls_verify_cert_result(tls_session)) {

      RDEBUG2("(TLS) Certificate re-validation failed, denying session resumption via session-ticket");

      return SSL_TICKET_RETURN_IGNORE_RENEW;

    }

  }

  return (status == SSL_TICKET_SUCCESS_RENEW) ? SSL_TICKET_RETURN_USE_RENEW : SSL_TICKET_RETURN_USE;

}

/** Derive the session ticket key, and install the session ticket callbacks on an SSL_CTX

 *

 * The key the configuration gives is stretched to the length OpenSSL asks

 * for with HKDF.  The callbacks embed the session-state list in each session

 * ticket the server issues, and extract the list again when a ticket is

 * presented.

 *

 * @param[in] ctx   to install the key and callbacks on.

 * @param[in] cache_conf  Session caching configuration, for the key and the callbacks.

 * @return

 *  - 0 on success.

 *  - -1 on failure.

 */

int fr_tls_ticket_stateless_ctx_init(SSL_CTX *ctx, fr_tls_ticket_conf_t const *cache_conf)

{

  size_t    key_len;

  uint8_t   *key_buff;

  EVP_PKEY_CTX  *pkey_ctx = NULL;

  /*

   *  If keys is NULL, then OpenSSL returns the expected

   *  key length, which may be different across different

   *  flavours/versions of OpenSSL.

   *

   *  We could calculate this in conf.c, but, if in future

   *  OpenSSL decides to use different key lengths based

   *  on other parameters in the ctx, that'd break.

   */

  key_len = SSL_CTX_set_tlsext_ticket_keys(ctx, NULL, 0);

  if (unlikely((pkey_ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL)) == NULL)) {

    fr_tls_strerror_printf(NULL);

    PERROR("Failed initialising KDF");

  kdf_error:

    if (pkey_ctx) EVP_PKEY_CTX_free(pkey_ctx);

    return -1;

  }

  if (unlikely(EVP_PKEY_derive_init(pkey_ctx) != 1)) {

    fr_tls_strerror_printf(NULL);

    PERROR("Failed initialising KDF derivation ctx");

    goto kdf_error;

  }

  if (unlikely(EVP_PKEY_CTX_set_hkdf_md(pkey_ctx, UNCONST(struct evp_md_st *, EVP_sha256())) != 1)) {

    fr_tls_strerror_printf(NULL);

    PERROR("Failed setting KDF MD");

    goto kdf_error;

  }

  if (unlikely(EVP_PKEY_CTX_set1_hkdf_key(pkey_ctx,

            UNCONST(unsigned char *, cache_conf->session_ticket_key),

            talloc_array_length(cache_conf->session_ticket_key)) != 1)) {

    fr_tls_strerror_printf(NULL);

    PERROR("Failed setting KDF key");

    goto kdf_error;

  }

  if (unlikely(EVP_PKEY_CTX_add1_hkdf_info(pkey_ctx,

             UNCONST(unsigned char *, "freeradius-session-ticket"),

             sizeof("freeradius-session-ticket") - 1) != 1)) {

    fr_tls_strerror_printf(NULL);

    PERROR("Failed setting KDF label");

    goto kdf_error;

  }

  /*

   *  SSL_CTX_set_tlsext_ticket_keys memcpys its

   *  inputs so this is just a temporary buffer.

   */

  MEM(key_buff = talloc_array(NULL, uint8_t, key_len));

  if (EVP_PKEY_derive(pkey_ctx, key_buff, &key_len) != 1) {

    fr_tls_strerror_printf(NULL);

    PERROR("Failed deriving session ticket key");

  key_buff_error:

    talloc_free(key_buff);

    goto kdf_error;

  }

  EVP_PKEY_CTX_free(pkey_ctx);

  pkey_ctx = NULL;

  fr_assert(talloc_array_length(key_buff) == key_len);

  /*

   *  Ensure the same keys are used across all threads

   */

  if (SSL_CTX_set_tlsext_ticket_keys(ctx,

             key_buff, key_len) != 1) {

    fr_tls_strerror_printf(NULL);

    PERROR("Failed setting session ticket keys");

    goto key_buff_error;

  }

  DEBUG3("Derived session-ticket-key:");

  HEXDUMP3(key_buff, key_len, NULL);

  TALLOC_FREE(key_buff);

  /*

   *  These callbacks embed and extract the

   *  session-state list from the session-ticket.

   */

  if (unlikely(SSL_CTX_set_session_ticket_cb(ctx,

               tls_ticket_stateless_app_data_set,

               tls_ticket_stateless_app_data_get,

               UNCONST(fr_tls_ticket_conf_t *, cache_conf)) != 1)) {

    fr_tls_strerror_printf(NULL);

    PERROR("Failed setting session ticket callbacks");

    return -1;

  }

  /*

   *  Stateless resumption is enabled by default when

   *  the TLS ctx is created, but OpenSSL sends too

   *  many session tickets by default (2), and we only

   *      need one.

   */

  SSL_CTX_set_num_tickets(ctx, 1);

  return 0;

}

#endif /* WITH_TLS */