Fold threads.h into crypto.h making API public

Document thread-safe lock creation
Reviewed-by: NRichard Levitte <levitte@openssl.org>

crypto/async/async.c

@@ -61,7 +61,6 @@
 /* This must be the first #include file */
 #include "async_locl.h"
 
-#include <internal/threads.h>
 #include <openssl/err.h>
 #include <internal/cryptlib_int.h>
 #include <string.h>

crypto/bio/b_addr.c

@@ -55,7 +55,7 @@
 #include <string.h>
 
 #include "bio_lcl.h"
-#include "internal/threads.h"
+#include <openssl/crypto.h>
 
 #ifndef OPENSSL_NO_SOCK
 #include <openssl/err.h>

crypto/bn/bn_blind.c

@@ -110,7 +110,6 @@
 
 #include <openssl/opensslconf.h>
 #include "internal/cryptlib.h"
-#include "internal/threads.h"
 #include "bn_lcl.h"
 
 #define BN_BLINDING_COUNTER     32

crypto/engine/eng_int.h

@@ -65,7 +65,6 @@
 # define HEADER_ENGINE_INT_H
 
 # include "internal/cryptlib.h"
-# include "internal/threads.h"
 # include <internal/engine.h>
 
 #ifdef  __cplusplus

crypto/err/err.c

@@ -112,7 +112,6 @@
 #include <stdarg.h>
 #include <string.h>
 #include <internal/cryptlib_int.h>
-#include <internal/threads.h>
 #include <internal/err.h>
 #include <internal/err_int.h>
 #include <openssl/lhash.h>

crypto/err/err_prn.c

@@ -57,7 +57,6 @@
 
 #include <stdio.h>
 #include "internal/cryptlib.h"
-#include "internal/threads.h"
 #include <openssl/lhash.h>
 #include <openssl/crypto.h>
 #include <openssl/buffer.h>

crypto/ex_data.c

@@ -109,7 +109,6 @@
  */
 
 #include "internal/cryptlib_int.h"
-#include "internal/threads.h"
 #include <openssl/lhash.h>
 
 /*

crypto/init.c

@@ -55,7 +55,6 @@
  *
  */
 
-#include <internal/threads.h>
 #include <internal/cryptlib_int.h>
 #include <openssl/err.h>
 #include <internal/rand.h>

crypto/mem_dbg.c

@@ -112,7 +112,6 @@
 #include <stdlib.h>
 #include <time.h>
 #include "internal/cryptlib.h"
-#include "internal/threads.h"
 #include <openssl/crypto.h>
 #include <openssl/buffer.h>
 #include "internal/bio.h"

crypto/mem_sec.c

@@ -25,7 +25,6 @@
 # include <sys/param.h>
 # include <sys/stat.h>
 # include <fcntl.h>
-# include "internal/threads.h"
 #endif
 
 #define CLEAR(p, s) OPENSSL_cleanse(p, s)

crypto/rand/md_rand.c

@@ -125,7 +125,6 @@
 #include <openssl/rand.h>
 #include <openssl/async.h>
 #include "rand_lcl.h"
-#include "internal/threads.h"
 
 #include <openssl/err.h>
 

crypto/threads_none.c

@@ -48,7 +48,6 @@
  */
 
 #include <openssl/crypto.h>
-#include "internal/threads.h"
 
 #if !defined(OPENSSL_THREADS) || defined(CRYPTO_TDEBUG)
 

crypto/threads_pthread.c

@@ -48,7 +48,6 @@
  */
 
 #include <openssl/crypto.h>
-#include "internal/threads.h"
 
 #if defined(OPENSSL_THREADS) && !defined(CRYPTO_TDEBUG) && !defined(OPENSSL_SYS_WINDOWS)
 

crypto/threads_win.c

@@ -48,7 +48,6 @@
  */
 
 #include <openssl/crypto.h>
-#include "internal/threads.h"
 
 #if defined(OPENSSL_THREADS) && !defined(CRYPTO_TDEBUG) && defined(OPENSSL_SYS_WINDOWS)
 

crypto/x509/by_dir.c

@@ -71,7 +71,6 @@
 
 #include <openssl/lhash.h>
 #include <openssl/x509.h>
-#include "internal/threads.h"
 #include "internal/x509_int.h"
 #include "x509_lcl.h"
 

doc/crypto/threads.pod

@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+CRYPTO_THREAD_run_once,
 CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
 CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL thread support
 
@@ -9,6 +10,9 @@ CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL threa
 
  #include <openssl/crypto.h>
 
+ CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;
+ int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
+
  CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);
  int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);
  int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);
@@ -30,6 +34,16 @@ The following multi-threading function are provided:
 
 =over 4
 
+=item *
+CRYPTO_THREAD_run_once() can be used to perform one-time initialization.
+The B<once> argument must be a pointer to a static object of type
+B<CRYPTO_ONCE> that was statically initialized to the value
+B<CRYPTO_ONCE_STATIC_INIT>.
+The B<init> argument is a pointer to a function that performs the desired
+exactly once initialization.
+In particular, this can be used to allocate locks in a thread-safe manner,
+which can then be used with the locking functions below.
+
 =item *
 CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write
 lock.
@@ -57,17 +71,62 @@ be the only way that the variable is modified.
 
 =head1 RETURN VALUES
 
+CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.
+
 CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
 
 CRYPTO_THREAD_lock_frees() returns no value.
 
 The other functions return 1 on success or 0 on error.
 
+=head1 EXAMPLE
+
+This example safely initializes and uses a lock.
+
+  #include <openssl/crypto.h>
+  
+  static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;
+  static CRYPTO_RWLOCK *lock;
+  
+  static void myinit(void)
+  {
+      lock = CRYPTO_THREAD_lock_new();
+  }
+  
+  static int mylock(void)
+  {
+      if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)
+          return 0;
+      return CRYPTO_THREAD_write_lock(lock);
+  }
+  
+  static int myunlock(void)
+  {
+      return CRYPTO_THREAD_unlock(lock);
+  }
+  
+  int serialized(void)
+  {
+      int ret = 0;
+  
+      if (mylock()) {
+          /* Your code here, do not return without releasing the lock! */
+          ret = ... ;
+      }
+      myunlock();
+      return ret;
+  }
+
+Finalization of locks is an advanced topic, not covered in this example.
+This can only be done at process exit or when a dynamically loaded library is
+no longer in use and is unloaded.
+The simplest solution is to just "leak" the lock in applications and not
+repeatedly load/unload shared libraries that allocate locks.
+
 =head1 NOTES
 
 You can find out if OpenSSL was configured with thread support:
 
- #define OPENSSL_THREAD_DEFINES
  #include <openssl/opensslconf.h>
  #if defined(OPENSSL_THREADS)
    // thread support enabled

include/internal/threads.h

-/* ====================================================================
- * Copyright (c) 2016 The OpenSSL Project.  All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- *    notice, this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in
- *    the documentation and/or other materials provided with the
- *    distribution.
- *
- * 3. All advertising materials mentioning features or use of this
- *    software must display the following acknowledgment:
- *    "This product includes software developed by the OpenSSL Project
- *    for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)"
- *
- * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
- *    endorse or promote products derived from this software without
- *    prior written permission. For written permission, please contact
- *    licensing@OpenSSL.org.
- *
- * 5. Products derived from this software may not be called "OpenSSL"
- *    nor may "OpenSSL" appear in their names without prior written
- *    permission of the OpenSSL Project.
- *
- * 6. Redistributions of any form whatsoever must retain the following
- *    acknowledgment:
- *    "This product includes software developed by the OpenSSL Project
- *    for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)"
- *
- * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
- * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
- * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
- * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
- * OF THE POSSIBILITY OF SUCH DAMAGE.
- */
-
-#ifndef HEADER_INTERNAL_THREADS_H
-# define HEADER_INTERNAL_THREADS_H
-
-#include "e_os.h"
-
-# if !defined(OPENSSL_THREADS) || defined(CRYPTO_TDEBUG)
-typedef unsigned int CRYPTO_ONCE;
-typedef unsigned int CRYPTO_THREAD_LOCAL;
-typedef unsigned int CRYPTO_THREAD_ID;
-
-#  define CRYPTO_ONCE_STATIC_INIT 0
-# elif defined(OPENSSL_SYS_WINDOWS)
-#  include <windows.h>
-typedef DWORD CRYPTO_THREAD_LOCAL;
-typedef DWORD CRYPTO_THREAD_ID;
-
-#  if _WIN32_WINNT < 0x0600
-typedef LONG CRYPTO_ONCE;
-#   define CRYPTO_ONCE_STATIC_INIT 0
-#  else
-typedef INIT_ONCE CRYPTO_ONCE;
-#   define CRYPTO_ONCE_STATIC_INIT INIT_ONCE_STATIC_INIT
-#  endif
-
-# else
-#  include <pthread.h>
-typedef pthread_once_t CRYPTO_ONCE;
-typedef pthread_key_t CRYPTO_THREAD_LOCAL;
-typedef pthread_t CRYPTO_THREAD_ID;
-
-#  define CRYPTO_ONCE_STATIC_INIT PTHREAD_ONCE_INIT
-# endif
-
-int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
-
-int CRYPTO_THREAD_init_local(CRYPTO_THREAD_LOCAL *key, void (*cleanup)(void *));
-void *CRYPTO_THREAD_get_local(CRYPTO_THREAD_LOCAL *key);
-int CRYPTO_THREAD_set_local(CRYPTO_THREAD_LOCAL *key, void *val);
-int CRYPTO_THREAD_cleanup_local(CRYPTO_THREAD_LOCAL *key);
-
-CRYPTO_THREAD_ID CRYPTO_THREAD_get_current_id(void);
-int CRYPTO_THREAD_compare_id(CRYPTO_THREAD_ID a, CRYPTO_THREAD_ID b);
-
-#endif

include/openssl/crypto.h

@@ -485,6 +485,44 @@ void OPENSSL_INIT_set_config_filename(OPENSSL_INIT_SETTINGS *settings,
 #endif
 void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *settings);
 
+# if !defined(OPENSSL_THREADS) || defined(CRYPTO_TDEBUG)
+typedef unsigned int CRYPTO_ONCE;
+typedef unsigned int CRYPTO_THREAD_LOCAL;
+typedef unsigned int CRYPTO_THREAD_ID;
+
+#  define CRYPTO_ONCE_STATIC_INIT 0
+# elif defined(OPENSSL_SYS_WINDOWS)
+#  include <windows.h>
+typedef DWORD CRYPTO_THREAD_LOCAL;
+typedef DWORD CRYPTO_THREAD_ID;
+
+#  if _WIN32_WINNT < 0x0600
+typedef LONG CRYPTO_ONCE;
+#   define CRYPTO_ONCE_STATIC_INIT 0
+#  else
+typedef INIT_ONCE CRYPTO_ONCE;
+#   define CRYPTO_ONCE_STATIC_INIT INIT_ONCE_STATIC_INIT
+#  endif
+
+# else
+#  include <pthread.h>
+typedef pthread_once_t CRYPTO_ONCE;
+typedef pthread_key_t CRYPTO_THREAD_LOCAL;
+typedef pthread_t CRYPTO_THREAD_ID;
+
+#  define CRYPTO_ONCE_STATIC_INIT PTHREAD_ONCE_INIT
+# endif
+
+int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
+
+int CRYPTO_THREAD_init_local(CRYPTO_THREAD_LOCAL *key, void (*cleanup)(void *));
+void *CRYPTO_THREAD_get_local(CRYPTO_THREAD_LOCAL *key);
+int CRYPTO_THREAD_set_local(CRYPTO_THREAD_LOCAL *key, void *val);
+int CRYPTO_THREAD_cleanup_local(CRYPTO_THREAD_LOCAL *key);
+
+CRYPTO_THREAD_ID CRYPTO_THREAD_get_current_id(void);
+int CRYPTO_THREAD_compare_id(CRYPTO_THREAD_ID a, CRYPTO_THREAD_ID b);
+
 /* BEGIN ERROR CODES */
 /*
  * The following lines are auto generated by the script mkerr.pl. Any changes

ssl/ssl_cert.c

@@ -127,7 +127,7 @@
 #include <openssl/x509v3.h>
 #include <openssl/dh.h>
 #include <openssl/bn.h>
-#include "internal/threads.h"
+#include <openssl/crypto.h>
 #include "ssl_locl.h"
 
 static int ssl_security_default_callback(const SSL *s, const SSL_CTX *ctx, int op,

ssl/ssl_ciph.c

@@ -144,7 +144,7 @@
 #include <openssl/objects.h>
 #include <openssl/comp.h>
 #include <openssl/engine.h>
-#include "internal/threads.h"
+#include <openssl/crypto.h>
 #include "ssl_locl.h"
 
 #define SSL_ENC_DES_IDX         0

ssl/ssl_init.c

@@ -57,7 +57,6 @@
 
 #include "e_os.h"
 
-#include "internal/threads.h"
 #include "internal/err.h"
 #include <openssl/crypto.h>
 #include <openssl/evp.h>

test/ssltest_old.c

@@ -191,7 +191,6 @@
 # include <openssl/ct.h>
 #endif
 
-#include "internal/threads.h"
 #include "../ssl/ssl_locl.h"
 
 /*

test/threadstest.c

@@ -50,7 +50,6 @@
 #include <stdio.h>
 
 #include <openssl/crypto.h>
-#include "internal/threads.h"
 
 #if !defined(OPENSSL_THREADS) || defined(CRYPTO_TDEBUG)
 

util/mkdef.pl

@@ -247,7 +247,6 @@ $ssl.=" include/openssl/srtp.h";
 my $crypto ="include/openssl/crypto.h";
 $crypto.=" include/internal/o_dir.h";
 $crypto.=" include/internal/o_str.h";
-$crypto.=" include/internal/threads.h";
 $crypto.=" include/internal/err.h";
 $crypto.=" include/openssl/des.h" ; # unless $no_des;
 $crypto.=" include/openssl/idea.h" ; # unless $no_idea;