include/internal/statem.h

   1 /*
   2  * Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9 #ifndef OSSL_INTERNAL_STATEM_H
  10 # define OSSL_INTERNAL_STATEM_H
  11
  12 /*****************************************************************************
  13  *                                                                           *
  14  * These enums should be considered PRIVATE to the state machine. No         *
  15  * non-state machine code should need to use these                           *
  16  *                                                                           *
  17  *****************************************************************************/
  18 /*
  19  * Valid return codes used for functions performing work prior to or after
  20  * sending or receiving a message
  21  */
  22 typedef enum {
  23     /* Something went wrong */
  24     WORK_ERROR,
  25     /* We're done working and there shouldn't be anything else to do after */
  26     WORK_FINISHED_STOP,
  27     /* We're done working move onto the next thing */
  28     WORK_FINISHED_CONTINUE,
  29     /* We're working on phase A */
  30     WORK_MORE_A,
  31     /* We're working on phase B */
  32     WORK_MORE_B,
  33     /* We're working on phase C */
  34     WORK_MORE_C
  35 } WORK_STATE;
  36
  37 /* Write transition return codes */
  38 typedef enum {
  39     /* Something went wrong */
  40     WRITE_TRAN_ERROR,
  41     /* A transition was successfully completed and we should continue */
  42     WRITE_TRAN_CONTINUE,
  43     /* There is no more write work to be done */
  44     WRITE_TRAN_FINISHED
  45 } WRITE_TRAN;
  46
  47 /* Message flow states */
  48 typedef enum {
  49     /* No handshake in progress */
  50     MSG_FLOW_UNINITED,
  51     /* A permanent error with this connection */
  52     MSG_FLOW_ERROR,
  53     /* We are reading messages */
  54     MSG_FLOW_READING,
  55     /* We are writing messages */
  56     MSG_FLOW_WRITING,
  57     /* Handshake has finished */
  58     MSG_FLOW_FINISHED
  59 } MSG_FLOW_STATE;
  60
  61 /* Read states */
  62 typedef enum {
  63     READ_STATE_HEADER,
  64     READ_STATE_BODY,
  65     READ_STATE_POST_PROCESS
  66 } READ_STATE;
  67
  68 /* Write states */
  69 typedef enum {
  70     WRITE_STATE_TRANSITION,
  71     WRITE_STATE_PRE_WORK,
  72     WRITE_STATE_SEND,
  73     WRITE_STATE_POST_WORK
  74 } WRITE_STATE;
  75
  76 typedef enum {
  77     CON_FUNC_ERROR = 0,
  78     CON_FUNC_SUCCESS,
  79     CON_FUNC_DONT_SEND
  80 } CON_FUNC_RETURN;
  81
  82 typedef int (*ossl_statem_mutate_handshake_cb)(const unsigned char *msgin,
  83                                                size_t inlen,
  84                                                unsigned char **msgout,
  85                                                size_t *outlen,
  86                                                void *arg);
  87
  88 typedef void (*ossl_statem_finish_mutate_handshake_cb)(void *arg);
  89
  90 /*****************************************************************************
  91  *                                                                           *
  92  * This structure should be considered "opaque" to anything outside of the   *
  93  * state machine. No non-state machine code should be accessing the members  *
  94  * of this structure.                                                        *
  95  *                                                                           *
  96  *****************************************************************************/
  97
  98 struct ossl_statem_st {
  99     MSG_FLOW_STATE state;
 100     WRITE_STATE write_state;
 101     WORK_STATE write_state_work;
 102     READ_STATE read_state;
 103     WORK_STATE read_state_work;
 104     OSSL_HANDSHAKE_STATE hand_state;
 105     /* The handshake state requested by an API call (e.g. HelloRequest) */
 106     OSSL_HANDSHAKE_STATE request_state;
 107     int in_init;
 108     int read_state_first_init;
 109     /* true when we are actually in SSL_accept() or SSL_connect() */
 110     int in_handshake;
 111     /*
 112      * True when are processing a "real" handshake that needs cleaning up (not
 113      * just a HelloRequest or similar).
 114      */
 115     int cleanuphand;
 116     /* Should we skip the CertificateVerify message? */
 117     unsigned int no_cert_verify;
 118     int use_timer;
 119
 120     /* Test harness message mutator callbacks */
 121     ossl_statem_mutate_handshake_cb mutate_handshake_cb;
 122     ossl_statem_finish_mutate_handshake_cb finish_mutate_handshake_cb;
 123     void *mutatearg;
 124     unsigned int write_in_progress : 1;
 125 };
 126 typedef struct ossl_statem_st OSSL_STATEM;
 127
 128 /*****************************************************************************
 129  *                                                                           *
 130  * The following macros/functions represent the libssl internal API to the   *
 131  * state machine. Any libssl code may call these functions/macros            *
 132  *                                                                           *
 133  *****************************************************************************/
 134
 135 typedef struct ssl_connection_st SSL_CONNECTION;
 136
 137 __owur int ossl_statem_accept(SSL *s);
 138 __owur int ossl_statem_connect(SSL *s);
 139 OSSL_HANDSHAKE_STATE ossl_statem_get_state(SSL_CONNECTION *s);
 140 void ossl_statem_clear(SSL_CONNECTION *s);
 141 void ossl_statem_set_renegotiate(SSL_CONNECTION *s);
 142 void ossl_statem_send_fatal(SSL_CONNECTION *s, int al);
 143 void ossl_statem_fatal(SSL_CONNECTION *s, int al, int reason,
 144                        const char *fmt, ...);
 145 # define SSLfatal_alert(s, al) ossl_statem_send_fatal((s), (al))
 146 # define SSLfatal(s, al, r) SSLfatal_data((s), (al), (r), NULL)
 147 # define SSLfatal_data                                          \
 148     (ERR_new(),                                                 \
 149      ERR_set_debug(OPENSSL_FILE, OPENSSL_LINE, OPENSSL_FUNC),   \
 150      ossl_statem_fatal)
 151
 152 int ossl_statem_in_error(const SSL_CONNECTION *s);
 153 void ossl_statem_set_in_init(SSL_CONNECTION *s, int init);
 154 int ossl_statem_get_in_handshake(SSL_CONNECTION *s);
 155 void ossl_statem_set_in_handshake(SSL_CONNECTION *s, int inhand);
 156 __owur int ossl_statem_skip_early_data(SSL_CONNECTION *s);
 157 void ossl_statem_check_finish_init(SSL_CONNECTION *s, int send);
 158 void ossl_statem_set_hello_verify_done(SSL_CONNECTION *s);
 159 __owur int ossl_statem_app_data_allowed(SSL_CONNECTION *s);
 160 __owur int ossl_statem_export_allowed(SSL_CONNECTION *s);
 161 __owur int ossl_statem_export_early_allowed(SSL_CONNECTION *s);
 162
 163 /* Flush the write BIO */
 164 int statem_flush(SSL_CONNECTION *s);
 165
 166 int ossl_statem_set_mutator(SSL *s,
 167                             ossl_statem_mutate_handshake_cb mutate_handshake_cb,
 168                             ossl_statem_finish_mutate_handshake_cb finish_mutate_handshake_cb,
 169                             void *mutatearg);
 170
 171 #endif