Adding resumption using session tickets (#785)

* Adding resumption using session tickets

* Addressed feedback comments

* Addressed feedback: Update to Session ID cache lookup logic, cleaned integration tests and few other changes

* Addressed feedback and updated s2n_ticket_key to store intro timestamp instead of expiry time

* Addressed Feedback: Removed S2N_RECEIVED_VALID_TICKET status

* Added intro time to STK addition API

* Addressed feedback

* Renamed valid and semi-valid key to encrypt-decrypt and decrpt key respectively, and addressed other feedback

* Updated s2n_conn_set_handshake_type_proof in SAWScript tests

* Addressed feedback

* Added missing break statement and addressed feedback

* Addressed feedback

* Updated max key hashes

Author: kshreeja

api/s2n.h

@@ -56,7 +56,6 @@ extern int s2n_config_free(struct s2n_config *config);
 extern int s2n_config_free_dhparams(struct s2n_config *config);
 extern int s2n_config_free_cert_chain_and_key(struct s2n_config *config);
 
-
 typedef int (*s2n_clock_time_nanoseconds) (void *, uint64_t *);
 extern int s2n_config_set_wall_clock(struct s2n_config *config, s2n_clock_time_nanoseconds clock_fn, void *ctx);
 extern int s2n_config_set_monotonic_clock(struct s2n_config *config, s2n_clock_time_nanoseconds clock_fn, void *ctx);
@@ -110,6 +109,16 @@ extern int s2n_config_set_extension_data(struct s2n_config *config, s2n_tls_exte
 extern int s2n_config_send_max_fragment_length(struct s2n_config *config, s2n_max_frag_len mfl_code);
 extern int s2n_config_accept_max_fragment_length(struct s2n_config *config);
 
+extern int s2n_config_set_session_state_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
+
+extern int s2n_config_set_session_tickets_onoff(struct s2n_config *config, uint8_t enabled);
+extern int s2n_config_set_ticket_encrypt_decrypt_key_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
+extern int s2n_config_set_ticket_decrypt_key_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
+extern int s2n_config_add_ticket_crypto_key(struct s2n_config *config,
+                                            const uint8_t *name, uint32_t name_len,
+                                            uint8_t *key, uint32_t key_len,
+                                            uint64_t intro_time_in_seconds_from_epoch);
+
 struct s2n_connection;
 typedef enum { S2N_SERVER, S2N_CLIENT } s2n_mode;
 extern struct s2n_connection *s2n_connection_new(s2n_mode mode);
@@ -183,6 +192,7 @@ extern int s2n_connection_get_client_cert_chain(struct s2n_connection *conn, uin
 
 extern int s2n_connection_set_session(struct s2n_connection *conn, const uint8_t *session, size_t length);
 extern int s2n_connection_get_session(struct s2n_connection *conn, uint8_t *session, size_t max_length);
+extern int s2n_connection_get_session_ticket_lifetime_hint(struct s2n_connection *conn);
 extern ssize_t s2n_connection_get_session_length(struct s2n_connection *conn);
 extern ssize_t s2n_connection_get_session_id_length(struct s2n_connection *conn);
 extern int s2n_connection_is_session_resumed(struct s2n_connection *conn);

bin/s2nc.c

@@ -63,7 +63,9 @@ void usage()
     fprintf(stderr, "  -i,--insecure\n");
     fprintf(stderr, "    Turns off certification validation altogether.\n");
     fprintf(stderr, "  -r,--reconnect\n");
-    fprintf(stderr, "    Drop and re-make the connection with the same Session-ID\n");
+    fprintf(stderr, "    Drop and re-make the connection using Session ticket. If session ticket is disabled, then re-make the connection using Session-ID \n");
+    fprintf(stderr, "  -T,--no-session-ticket \n");
+    fprintf(stderr, "    Disable session ticket for resumption.\n");
     fprintf(stderr, "  -D,--dynamic\n");
     fprintf(stderr, "    Set dynamic record resize threshold\n");
     fprintf(stderr, "  -t,--timeout\n");
@@ -223,6 +225,7 @@ int main(int argc, char *const *argv)
     uint16_t mfl_value = 0;
     uint8_t insecure = 0;
     int reconnect = 0;
+    uint8_t session_ticket = 1;
     s2n_status_request_type type = S2N_STATUS_REQUEST_NONE;
     uint32_t dyn_rec_threshold = 0;
     uint8_t dyn_rec_timeout = 0;
@@ -245,12 +248,13 @@ int main(int argc, char *const *argv)
         {"ca-dir", required_argument, 0, 'd'},
         {"insecure", no_argument, 0, 'i'},
         {"reconnect", no_argument, 0, 'r'},
+        {"no-session-ticket", no_argument, 0, 'T'},
         {"Dynamic", required_argument, 0, 'D'},
         {"timeout", required_argument, 0, 't'},
     };
     while (1) {
         int option_index = 0;
-        int c = getopt_long(argc, argv, "a:c:ehn:sf:d:D:t:ir", long_options, &option_index);
+        int c = getopt_long(argc, argv, "a:c:ehn:sf:d:D:t:irT", long_options, &option_index);
         if (c == -1) {
             break;
         }
@@ -288,6 +292,9 @@ int main(int argc, char *const *argv)
         case 'r':
             reconnect = 5;
             break;
+        case 'T':
+            session_ticket = 0;
+            break;
         case 't':
             dyn_rec_timeout = (uint8_t) MIN(255, atoi(optarg));
             break;
@@ -373,6 +380,10 @@ int main(int argc, char *const *argv)
             s2n_config_disable_x509_verification(config);
         }
 
+        if (session_ticket) {
+            s2n_config_set_session_tickets_onoff(config, 1);
+        }
+
         struct s2n_connection *conn = s2n_connection_new(S2N_CLIENT);
 
         if (conn == NULL) {
@@ -413,7 +424,7 @@ int main(int argc, char *const *argv)
 
         /* Save session state from connection if reconnect is enabled */
         if (reconnect > 0) {
-            if (s2n_connection_get_session_id_length(conn) <= 0) {
+            if (!session_ticket && s2n_connection_get_session_id_length(conn) <= 0) {
                 printf("Endpoint sent empty session id so cannot resume session\n");
                 exit(1);
             }

bin/s2nd.c

@@ -32,6 +32,9 @@
 #include <getopt.h>
 
 #include <errno.h>
+#include <error.h>
+
+#include <error/s2n_errno.h>
 
 #include <openssl/crypto.h>
 #include <openssl/err.h>
@@ -135,6 +138,13 @@ static char dhparams[] =
     "HI5CnYmkAwJ6+FSWGaZQDi8bgerFk9RWwwIBAg==\n"
     "-----END DH PARAMETERS-----\n";
 
+uint8_t ticket_key_name[16] = "2016.07.26.15\0";
+
+uint8_t default_ticket_key[32] = {0x07, 0x77, 0x09, 0x36, 0x2c, 0x2e, 0x32, 0xdf, 0x0d, 0xdc,
+                                  0x3f, 0x0d, 0xc4, 0x7b, 0xba, 0x63, 0x90, 0xb6, 0xc7, 0x3b,
+                                  0xb5, 0x0f, 0x9c, 0x31, 0x22, 0xec, 0x84, 0x4a, 0xd7, 0xc2,
+                                  0xb3, 0xe5 };
+
 #define MAX_KEY_LEN 32
 #define MAX_VAL_LEN 255
 
@@ -328,6 +338,10 @@ void usage()
     fprintf(stderr, "    This option is only used if mutual auth is enabled.\n");
     fprintf(stderr, "  -i,--insecure\n");
     fprintf(stderr, "    Turns off certification validation altogether.\n");
+    fprintf(stderr, "  --stk-file\n");
+    fprintf(stderr, "    Location of key file used for encryption and decryption of session ticket.\n");
+    fprintf(stderr, "  -T,--no-session-ticket\n");
+    fprintf(stderr, "    Disable session ticket for resumption.\n");
     fprintf(stderr, "  -h,--help\n");
     fprintf(stderr, "    Display this message and quit.\n");
 
@@ -342,6 +356,7 @@ struct conn_settings {
     int prefer_throughput;
     int prefer_low_latency;
     int enable_mfl;
+    int session_ticket;
     const char *ca_dir;
     const char *ca_file;
     int insecure;
@@ -439,10 +454,12 @@ int main(int argc, char *const *argv)
     const char *certificate_chain_file_path = NULL;
     const char *private_key_file_path = NULL;
     const char *ocsp_response_file_path = NULL;
+    const char *session_ticket_key_file_path = NULL;
     const char *cipher_prefs = "default";
     struct conn_settings conn_settings = { 0 };
     int fips_mode = 0;
     int parallelize = 0;
+    conn_settings.session_ticket = 1;
 
     struct option long_options[] = {
         {"ciphers", required_argument, NULL, 'c'},
@@ -461,12 +478,14 @@ int main(int argc, char *const *argv)
         {"ca-dir", required_argument, 0, 'd'},
         {"ca-file", required_argument, 0, 't'},
         {"insecure", no_argument, 0, 'i'},
+        {"stk-file", required_argument, 0, 'a'},
+        {"no-session-ticket", no_argument, 0, 'T'},
         /* Per getopt(3) the last element of the array has to be filled with all zeros */
         { 0 },
     };
     while (1) {
         int option_index = 0;
-        int c = getopt_long(argc, argv, "c:hmnst:d:i", long_options, &option_index);
+        int c = getopt_long(argc, argv, "c:hmnst:d:i:T", long_options, &option_index);
         if (c == -1) {
             break;
         }
@@ -519,7 +538,13 @@ int main(int argc, char *const *argv)
             break;
         case 'i':
             conn_settings.insecure = 1;
-                break;
+            break;
+        case 'a':
+            session_ticket_key_file_path = optarg;
+            break;
+        case 'T':
+            conn_settings.session_ticket = 0;
+            break;
         case '?':
         default:
             fprintf(stdout, "getopt_long returned: %d", c);
@@ -713,6 +738,45 @@ int main(int argc, char *const *argv)
         exit(1);
     }
 
+    if (conn_settings.session_ticket) {
+        if (s2n_config_set_session_tickets_onoff(config, 1) < 0) {
+            fprintf(stderr, "Error enabling session tickets: '%s'\n", s2n_strerror(s2n_errno, "EN"));
+            exit(1);
+        }
+
+        /* Key initialization */
+        uint8_t *st_key;
+        uint32_t st_key_length;
+
+        if (session_ticket_key_file_path) {
+            int fd = open(session_ticket_key_file_path, O_RDONLY);
+            if (fd < 0) {
+                error(1, errno, "Error opening session ticket key file");
+                exit(1);
+            }
+
+            struct stat st;
+            if (fstat(fd, &st) < 0) {
+                error(1, errno, "Error fstat-ing session ticket key file");
+                exit(1);
+            }
+
+            st_key = mmap(0, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+            S2N_ERROR_IF(st_key == MAP_FAILED, S2N_ERR_MMAP);
+
+            st_key_length = st.st_size;
+
+            close(fd);
+        } else {
+            st_key = default_ticket_key;
+            st_key_length = strlen((char *)default_ticket_key);
+        }
+
+        if (s2n_config_add_ticket_crypto_key(config, ticket_key_name, strlen((char *) ticket_key_name), st_key, st_key_length, 0) != 0) {
+            fprintf(stderr, "Error adding ticket key: '%s'\n", s2n_strerror(s2n_errno, "EN"));
+            exit(1);
+        }
+    }
 
     int fd;
     while ((fd = accept(sockfd, ai->ai_addr, &ai->ai_addrlen)) > 0) {

docs/USAGE-GUIDE.md

@@ -1139,30 +1139,63 @@ const char * s2n_connection_get_curve(struct s2n_connection *conn);
 
 **s2n_connection_get_curve** returns a string indicating the elliptic curve used during ECDHE key exchange. The string "NONE" is returned if no curve has was used.
 
-### Session State Related calls
+### Session Resumption Related calls
 
 ```c
+int s2n_config_set_session_state_lifetime(struct s2n_config *config, uint32_t lifetime_in_secs);
+
 int s2n_connection_set_session(struct s2n_connection *conn, const uint8_t *session, size_t length);
 int s2n_connection_get_session(struct s2n_connection *conn, uint8_t *session, size_t max_length);
+int s2n_connection_get_session_ticket_lifetime_hint(struct s2n_connection *conn);
 ssize_t s2n_connection_get_session_length(struct s2n_connection *conn);
 ssize_t s2n_connection_get_session_id_length(struct s2n_connection *conn);
 int s2n_connection_is_session_resumed(struct s2n_connection *conn);
 ```
 
-- **session** session will contain serialized session related information needed to resume handshake.
+- **lifetime_in_secs** lifetime of the cached session state required to resume a handshake
+- **session** session will contain serialized session related information needed to resume handshake either using session id or session ticket.
 - **length** length of the serialized session state.
 - **max_length** Max number of bytes to copy into the **session** buffer.
 
-**s2n_connection_set_session** de-serializes the session state and updates the connection accrodingly.
+**s2n_config_set_session_state_lifetime** sets the lifetime of the cached session state. The default value is 15 hours.
+
+**s2n_connection_set_session** de-serializes the session state and updates the connection accordingly.
+
+**s2n_connection_get_session** serializes the session state from connection and copies into the **session** buffer and returns the number of bytes that were copied. If the first byte in **session** is 1, then the next 2 bytes will contain the session ticket length, followed by session ticket and session state. If the first byte in **session** is 0, then the next byte will contain session id length, followed by session id and session state.
 
-**s2n_connection_get_session** serializes the session state from connection and copies into the **session** buffer and returns the number of bytes that were copied.
+**s2n_connection_get_session_ticket_lifetime_hint** returns the session ticket lifetime hint in seconds from the server or -1 when session ticket was not used for resumption.
 
-**s2n_connection_get_session_length** returns number of bytes needed to store serailized session state; it can be used to allocate the **session** buffer.
+**s2n_connection_get_session_length** returns number of bytes needed to store serialized session state; it can be used to allocate the **session** buffer.
 
 **s2n_connection_get_session_id_length** returns session id length from the connection.
 
 **s2n_connection_is_session_resumed** checks if the handshake is abbreviated or not.
 
+### Session Ticket Specific calls
+
+```c
+int s2n_config_set_session_tickets_onoff(struct s2n_config *config, uint8_t enabled);
+int s2n_config_set_ticket_encrypt_decrypt_key_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
+int s2n_config_set_ticket_decrypt_key_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
+int s2n_config_add_ticket_crypto_key(struct s2n_config *config, const uint8_t *name, uint32_t name_len, uint8_t *key, uint32_t key_len, uint64_t intro_time_in_seconds_from_epoch);
+```
+
+- **enabled** when set to 0 will disable session resumption using session ticket
+- **name** name of the session ticket key that should be randomly generated to avoid collisions
+- **name_len** length of session ticket key name
+- **key** key used to perform encryption/decryption of session ticket
+- **key_len** length of the session ticket key
+- **intro_time_in_seconds_from_epoch** time at which the session ticket key is introduced. If this is 0, then intro_time_in_seconds_from_epoch is set to now.
+
+**s2n_config_set_session_tickets_onoff** enables and disables session resumption using session ticket
+
+**s2n_config_set_ticket_encrypt_decrypt_key_lifetime** sets how long a session ticket key will be in a state where it can be used for both encryption and decryption of tickets on the server side. The default value is 2 hours.
+
+**s2n_config_set_ticket_decrypt_key_lifetime** sets how long a session ticket key will be in a state where it can used just for decryption of already assigned tickets on the server side. Once decrypted, the session will resume and the server will issue a new session ticket encrypted using a key in encrypt-decrypt state. The default value is 13 hours.
+
+**s2n_config_add_ticket_crypto_key** adds session ticket key on the server side. It would be ideal to add new keys after every (encrypt_decrypt_key_lifetime_in_nanos/2) nanos because
+this will allow for gradual and linear transition of a key from encrypt-decrypt state to decrypt-only state.
+
 ### s2n\_connection\_wipe
 
 ```c

error/s2n_errno.c

@@ -141,6 +141,14 @@ struct s2n_error_translation EN[] = {
     {S2N_ERR_MAX_FRAG_LEN_MISMATCH, "Negotiated Maximum Fragmentation Length from server does not match the requested length by client"},
     {S2N_ERR_INVALID_SERIALIZED_SESSION_STATE, "Serialized session state is not in valid format"},
     {S2N_ERR_SERIALIZED_SESSION_STATE_TOO_LONG, "Serialized session state is too long"},
+    {S2N_ERR_CLIENT_AUTH_NOT_SUPPORTED_IN_SESSION_RESUMPTION_MODE, "Client Auth is not supported in session resumption mode"},
+    {S2N_ERR_INVALID_TICKET_KEY_LENGTH, "Session ticket key length cannot be zero"},
+    {S2N_ERR_INVALID_TICKET_KEY_NAME_OR_NAME_LENGTH, "Session ticket key name should be unique and the name length cannot be zero"},
+    {S2N_ERR_TICKET_KEY_LIMIT, "Limit reached for unexpired session ticket keys"},
+    {S2N_ERR_NO_TICKET_ENCRYPT_DECRYPT_KEY, "No key in encrypt-decrypt state is available to encrypt session ticket"},
+    {S2N_ERR_ENCRYPT_DECRYPT_KEY_SELECTION_FAILED, "Failed to select a key from keys in encrypt-decrypt state"},
+    {S2N_ERR_KEY_USED_IN_SESSION_TICKET_NOT_FOUND, "Key used in already assigned session ticket not found for decryption"},
+    {S2N_ERR_SENDING_NST, "Error in session ticket status encountered before sending NST"},
     {S2N_ERR_INVALID_DYNAMIC_THRESHOLD, "invalid dynamic record threshold"}
 };
 

error/s2n_errno.h

@@ -156,6 +156,14 @@ typedef enum {
     S2N_ERR_CANCELLED,
     S2N_ERR_INVALID_SERIALIZED_SESSION_STATE,
     S2N_ERR_SERIALIZED_SESSION_STATE_TOO_LONG,
+    S2N_ERR_CLIENT_AUTH_NOT_SUPPORTED_IN_SESSION_RESUMPTION_MODE,
+    S2N_ERR_INVALID_TICKET_KEY_LENGTH,
+    S2N_ERR_INVALID_TICKET_KEY_NAME_OR_NAME_LENGTH,
+    S2N_ERR_TICKET_KEY_LIMIT,
+    S2N_ERR_NO_TICKET_ENCRYPT_DECRYPT_KEY,
+    S2N_ERR_ENCRYPT_DECRYPT_KEY_SELECTION_FAILED,
+    S2N_ERR_KEY_USED_IN_SESSION_TICKET_NOT_FOUND,
+    S2N_ERR_SENDING_NST,
     S2N_ERR_INVALID_DYNAMIC_THRESHOLD,
 } s2n_error;