ssl/statem/statem.h

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