Fold threads.h into crypto.h making API public

Document thread-safe lock creation

Reviewed-by: Richard Levitte <levitte@openssl.org>

diff --git a/crypto/async/async.c b/crypto/async/async.c
index b4ba5618881789869e30df438463d82256741550..719379e175a28d55eafd3b1ab777c69b69661dbb 100644 (file)
--- a/crypto/async/async.c
+++ b/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>

diff --git a/crypto/bio/b_addr.c b/crypto/bio/b_addr.c
index 1813f5a9bb641c7a122aa54046b2a5d0aa5e7efc..356ab113304ca7c7977dbf6e747bb0c051b03919 100644 (file)
--- a/crypto/bio/b_addr.c
+++ b/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>

diff --git a/crypto/bn/bn_blind.c b/crypto/bn/bn_blind.c
index 81b895ce379f21cc9ebf17e5c9bc86fbe2f67a00..fcc4db520556e8878a23e3ddb9810b7834272db3 100644 (file)
--- a/crypto/bn/bn_blind.c
+++ b/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

diff --git a/crypto/engine/eng_int.h b/crypto/engine/eng_int.h
index b1752957db5770bda9e88e2a49061dcd2e2ccff0..36bc933695c10b6230671e50360f757ae68ce19d 100644 (file)
--- a/crypto/engine/eng_int.h
+++ b/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

diff --git a/crypto/err/err.c b/crypto/err/err.c
index fd2ea8194afc01e1a560ff37d569a314e4038da6..f1a80c0d50314079b00d7aa2e262c378f3479573 100644 (file)
--- a/crypto/err/err.c
+++ b/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>

diff --git a/crypto/err/err_prn.c b/crypto/err/err_prn.c
index 0f7d40c3982040189a209978990960c34aee8f1f..1cbec54734a79a6b1d4b76648eb95cd5ce093d83 100644 (file)
--- a/crypto/err/err_prn.c
+++ b/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>

diff --git a/crypto/ex_data.c b/crypto/ex_data.c
index ca1c204f38e116c2f81e0a957d52d92deb383109..257073630456443401142f9f75c2bcccc4d85d30 100644 (file)
--- a/crypto/ex_data.c
+++ b/crypto/ex_data.c
@@ -109,7 +109,6 @@
  */
 
 #include "internal/cryptlib_int.h"
-#include "internal/threads.h"
 #include <openssl/lhash.h>
 
 /*

diff --git a/crypto/init.c b/crypto/init.c
index 938bf78a39cef71b34e12e2ed14a515c6fc57b21..90ab6dff40a9c11b1b94eb3bff7716e7b9e25b5a 100644 (file)
--- a/crypto/init.c
+++ b/crypto/init.c
@@ -55,7 +55,6 @@
  *
  */
 
-#include <internal/threads.h>
 #include <internal/cryptlib_int.h>
 #include <openssl/err.h>
 #include <internal/rand.h>

diff --git a/crypto/mem_dbg.c b/crypto/mem_dbg.c
index 2b8cf73028deac21ff1ec542dd44fb293179620b..0df050d057ad2c71d3606c4ede3a9be35b74d8a4 100644 (file)
--- a/crypto/mem_dbg.c
+++ b/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"

diff --git a/crypto/mem_sec.c b/crypto/mem_sec.c
index d61d945d6366cbd746732af9f65c67b534a19232..31fcee6877c2b201f229feec647f40d1982e48b7 100644 (file)
--- a/crypto/mem_sec.c
+++ b/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)

diff --git a/crypto/rand/md_rand.c b/crypto/rand/md_rand.c
index e9574b08b8975a5d47a6f1d4f9a292886f8f361b..74beda8bb4a5ddda6ac4bce847579c258b14e1dd 100644 (file)
--- a/crypto/rand/md_rand.c
+++ b/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>
 

diff --git a/crypto/threads_none.c b/crypto/threads_none.c
index 4e3b7a52e8cfe6804f0b6570482ff7f81f1a2b6b..bd92b8294db15812028baa6510bc4d3ad6dfebbc 100644 (file)
--- a/crypto/threads_none.c
+++ b/crypto/threads_none.c
@@ -48,7 +48,6 @@
  */
 
 #include <openssl/crypto.h>
-#include "internal/threads.h"
 
 #if !defined(OPENSSL_THREADS) || defined(CRYPTO_TDEBUG)
 

diff --git a/crypto/threads_pthread.c b/crypto/threads_pthread.c
index edca77c0b972a207bb1b866ae8723225302bb70d..c861faa9bd3553b7f2b35ee1dd7575d028109843 100644 (file)
--- a/crypto/threads_pthread.c
+++ b/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)
 

diff --git a/crypto/threads_win.c b/crypto/threads_win.c
index 63647a39a673dc37e3ab0bd513b82d4cb6331934..f2c4cfa179f414a15afe685d424cb407babc2cf9 100644 (file)
--- a/crypto/threads_win.c
+++ b/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)
 

diff --git a/crypto/x509/by_dir.c b/crypto/x509/by_dir.c
index 55241175b5bb60d45f5a36146efd7ad095a640b9..9b3f4f50cb598cd39d068b72b4e3611e65d06495 100644 (file)
--- a/crypto/x509/by_dir.c
+++ b/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"
 

diff --git a/doc/crypto/threads.pod b/doc/crypto/threads.pod
index 90c57098a46957da0a43b10862acb1cadb1ef6c6..bb21462f3e08ac8e3133242a869b755d8576087d 100644 (file)
--- a/doc/crypto/threads.pod
+++ b/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

diff --git a/include/internal/threads.h b/include/internal/threads.h
deleted file mode 100644 (file)
index 7897728..0000000
--- a/include/internal/threads.h
+++ /dev/null
@@ -1,92 +0,0 @@
-/* ====================================================================
- * 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

diff --git a/include/openssl/crypto.h b/include/openssl/crypto.h
index 5e16318d7ba95b5a2c6bd8a700e8ccd959281f40..3d73c62f2924c0b14c01924716e944d69ac1e5ee 100644 (file)
--- a/include/openssl/crypto.h
+++ b/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

diff --git a/ssl/ssl_cert.c b/ssl/ssl_cert.c
index dc7debbab262f51f317dc1d1d513b681a5ede20e..43589ef2711b4fd97105bf3c927c5970c28fb041 100644 (file)
--- a/ssl/ssl_cert.c
+++ b/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,

diff --git a/ssl/ssl_ciph.c b/ssl/ssl_ciph.c
index 8b65daa95c965526463b8d28ab5ea688964ff0fd..435deb8fae8ff22dc44a83150c27cec082fc7e02 100644 (file)
--- a/ssl/ssl_ciph.c
+++ b/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

diff --git a/ssl/ssl_init.c b/ssl/ssl_init.c
index 546f5d23a89f958d95b4d5006441345b26d9929d..9ed06fb4a28db62cfa3b2c9c730469a3af3047c5 100644 (file)
--- a/ssl/ssl_init.c
+++ b/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>

diff --git a/test/ssltest_old.c b/test/ssltest_old.c
index eb35c1d6c0803779a65788d87e931052ae313880..14d5b71ddae1204d1489f5901d02abf174b04b03 100644 (file)
--- a/test/ssltest_old.c
+++ b/test/ssltest_old.c
@@ -191,7 +191,6 @@
 # include <openssl/ct.h>
 #endif
 
-#include "internal/threads.h"
 #include "../ssl/ssl_locl.h"
 
 /*

diff --git a/test/threadstest.c b/test/threadstest.c
index e3a9ff5849ca28880b4537697929b76a6eb4f8c4..e15f2c31ae78928eb54d159088e5f68e9810b781 100644 (file)
--- a/test/threadstest.c
+++ b/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)
 

diff --git a/util/mkdef.pl b/util/mkdef.pl
index 4d8befe19f6dccdf093d3c522b7ea3b390cc7cbf..c2fbfe7062f3a4f7443796eb5d579d87cfec9be7 100755 (executable)
--- a/util/mkdef.pl
+++ b/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;