feat: Adds cleanup_final (#4853)

api/s2n.h

@@ -241,6 +241,19 @@ S2N_API extern int s2n_init(void);
  */
 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);
+
 typedef enum {
     S2N_FIPS_MODE_DISABLED = 0,
     S2N_FIPS_MODE_ENABLED,

tests/unit/s2n_init_test.c

@@ -104,6 +104,27 @@ int main(int argc, char **argv)
         EXPECT_FAILURE_WITH_ERRNO(s2n_cleanup(), S2N_ERR_NOT_INITIALIZED);
     }
 
+    /* s2n_cleanup_final */
+    {
+        /* s2n_cleanup_final fully de-initializes the library */
+        EXPECT_SUCCESS(s2n_init());
+        EXPECT_TRUE(s2n_is_initialized());
+        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());
+        EXPECT_SUCCESS(s2n_cleanup_thread());
+        EXPECT_SUCCESS(s2n_cleanup_final());
+    }
+
     /* The following test requires atexit to be enabled. */
     EXPECT_SUCCESS(s2n_enable_atexit());