Enabling atexit for tests only

Author: maddeleine

api/s2n.h

@@ -229,8 +229,8 @@ S2N_API extern unsigned long s2n_get_openssl_version(void);
 S2N_API extern int s2n_init(void);
 
 /**
- * Cleans up any internal resources used by s2n-tls. This function should be called from each thread or process
- * that is created subsequent to calling `s2n_init` when that thread or process is done calling other s2n-tls functions.
+ * Cleans up thread-local resources used by s2n-tls. Does not perform a full library cleanup. To fully
+ * clean up the library use s2n_cleanup_final().
  *
  * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
  */
@@ -239,12 +239,6 @@ S2N_API extern int s2n_cleanup(void);
 /*
  * Performs a complete deinitialization and cleanup of the s2n-tls library.
  *
- * s2n_cleanup_final will always perform a complete cleanup. In contrast,
- * s2n_cleanup will only perform a complete cleanup if the atexit handler
- * is disabled and s2n_cleanup is called by the thread that called s2n_init.
- * Therefore s2n_cleanup_final should be used instead of s2n_cleanup in cases
- * where the user needs full control over when the complete cleanup executes.
- *
  * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
  */
 S2N_API extern int s2n_cleanup_final(void);

docs/usage-guide/topics/ch02-initialization.md

@@ -1,10 +1,17 @@
 # Initialization and Teardown
-The s2n-tls library must be initialized with `s2n_init()` before calling most library functions. `s2n_init()` MUST NOT be called more than once, even when an application uses multiple threads or processes. s2n attempts to clean up its thread-local memory at thread-exit and all other memory at process-exit. However, this may not work if you are using a thread library other than pthreads or other threads using s2n outlive the thread that called `s2n_init()`. In that case you should call `s2n_cleanup_thread()` from every thread or process created after `s2n_init()`.
 
-> Note: `s2n_cleanup_thread()` is currently considered unstable, meaning the API is subject to change in a future release. To access this API, include `api/unstable/cleanup.h`.
+## Initialization
+The s2n-tls library must be initialized with `s2n_init()` before using the library functions. `s2n_init()` will error if it is called more than once per process.
 
 Initialization can be modified by calling `s2n_crypto_disable_init()` or `s2n_disable_atexit()` before `s2n_init()`.
 
-An application can override s2n-tls’s internal memory management by calling `s2n_mem_set_callbacks` before calling s2n_init.
+An application can override s2n-tls’s internal memory management by calling `s2n_mem_set_callbacks` before calling `s2n_init()`.
 
 If you are trying to use FIPS mode, you must enable FIPS in your libcrypto library (probably by calling `FIPS_mode_set(1)`) before calling `s2n_init()`.
+
+## Teardown
+### Thread-local Memory
+s2n has thread-local memory that it attempts to clean up automatically at thread-exit. This is done using pthread destructors and may not work if you are using a threads library other than pthreads. You can call `s2n_cleanup()` from every thread or process created after `s2n_init()` if you notice thread-local memory leaks.
+
+### Library Cleanup
+A full cleanup and de-initialization of the library can be done by calling `s2n_cleanup_final()`.

tests/s2n_test.h

@@ -15,18 +15,18 @@
 
 #pragma once
 #include <errno.h>
+#include <openssl/crypto.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
 
-#include <openssl/crypto.h>
-
 #include "error/s2n_errno.h"
-#include "utils/s2n_safety.h"
-#include "utils/s2n_result.h"
 #include "tls/s2n_alerts.h"
 #include "tls/s2n_tls13.h"
+#include "utils/s2n_init.h"
+#include "utils/s2n_result.h"
+#include "utils/s2n_safety.h"
 
 int test_count;
 
@@ -64,14 +64,15 @@ bool s2n_use_color_in_output = true;
  * number of independent childs at the start of a unit test and where you want
  * each child to have its own independently initialised s2n.
  */
-#define BEGIN_TEST_NO_INIT()                                        \
-    do {                                                            \
-        test_count = 0;                                             \
-        fprintf(stdout, "Running %-50s ... ", __FILE__);            \
-        fflush(stdout);                                             \
-        EXPECT_SUCCESS_WITHOUT_COUNT(s2n_in_unit_test_set(true));   \
-        S2N_TEST_OPTIONALLY_ENABLE_FIPS_MODE();                     \
-    } while(0)
+#define BEGIN_TEST_NO_INIT()                                      \
+    do {                                                          \
+        test_count = 0;                                           \
+        fprintf(stdout, "Running %-50s ... ", __FILE__);          \
+        fflush(stdout);                                           \
+        EXPECT_SUCCESS_WITHOUT_COUNT(s2n_in_unit_test_set(true)); \
+        S2N_TEST_OPTIONALLY_ENABLE_FIPS_MODE();                   \
+        EXPECT_SUCCESS(s2n_enable_atexit());                      \
+    } while (0)
 
 #define END_TEST_NO_INIT()                                          \
     do {                                                            \

tests/unit/s2n_init_test.c

@@ -105,12 +105,6 @@ int main(int argc, char **argv)
         EXPECT_SUCCESS(s2n_cleanup_final());
         EXPECT_FALSE(s2n_is_initialized());
 
-        /* s2n_cleanup fully cleans up the library when the atexit handler is disabled.
-         * Therefore, calling s2n_cleanup_final after s2n_cleanup will error */
-        EXPECT_SUCCESS(s2n_init());
-        EXPECT_SUCCESS(s2n_cleanup());
-        EXPECT_FAILURE_WITH_ERRNO(s2n_cleanup_final(), S2N_ERR_NOT_INITIALIZED);
-
         /* s2n_cleanup_thread only cleans up thread-local storage.
          * Therefore calling s2n_cleanup_final after s2n_cleanup_thread will succeed  */
         EXPECT_SUCCESS(s2n_init());
@@ -127,7 +121,6 @@ int main(int argc, char **argv)
     pthread_t init_success_thread = { 0 };
     EXPECT_EQUAL(pthread_create(&init_success_thread, NULL, s2n_init_success_cb, NULL), 0);
     EXPECT_EQUAL(pthread_join(init_success_thread, NULL), 0);
-    EXPECT_SUCCESS(s2n_cleanup_final());
 
     END_TEST_NO_INIT();
 }

utils/s2n_init.h

@@ -20,3 +20,4 @@
 int s2n_init(void);
 int s2n_cleanup(void);
 bool s2n_is_initialized(void);
+int s2n_enable_atexit(void);