From 6838bd1d737b6c3c4518e63543bf1e6a38113f55 Mon Sep 17 00:00:00 2001
From: Paul Bakker <p.j.bakker@polarssl.org>
Date: Mon, 30 Sep 2013 13:56:38 +0200
Subject: [PATCH] Clarified threading issues

---
 include/polarssl/config.h    | 2 ++
 include/polarssl/ecdsa.h     | 1 +
 include/polarssl/ecp.h       | 1 +
 include/polarssl/ssl.h       | 1 +
 include/polarssl/threading.h | 4 +++-
 5 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/include/polarssl/config.h b/include/polarssl/config.h
index 4a9d0efd5..bd1234396 100644
--- a/include/polarssl/config.h
+++ b/include/polarssl/config.h
@@ -674,6 +674,8 @@
  * \def POLARSSL_THREADING_DUMMY
  *
  * Provide a dummy threading implementation.
+ * Warning: If you use this, all claims of thread-safety in the documentation
+ *          are void!
  *
  * Requires: POLARSSL_THREADING_C
  *
diff --git a/include/polarssl/ecdsa.h b/include/polarssl/ecdsa.h
index 2de3b68d7..4a29ac634 100644
--- a/include/polarssl/ecdsa.h
+++ b/include/polarssl/ecdsa.h
@@ -88,6 +88,7 @@ int ecdsa_verify( ecp_group *grp,
 /**
  * \brief           Compute ECDSA signature and write it to buffer,
  *                  serialized as defined in RFC 4492 page 20.
+ *                  (Not thread-safe to use same context in multiple threads)
  *
  * \param ctx       ECDSA context
  * \param hash      Message hash
diff --git a/include/polarssl/ecp.h b/include/polarssl/ecp.h
index 94618e769..dec4e0a68 100644
--- a/include/polarssl/ecp.h
+++ b/include/polarssl/ecp.h
@@ -450,6 +450,7 @@ int ecp_sub( const ecp_group *grp, ecp_point *R,
 
 /**
  * \brief           Multiplication by an integer: R = m * P
+ *                  (Not thread-safe to use same group in multiple threads)
  *
  * \param grp       ECP group
  * \param R         Destination point
diff --git a/include/polarssl/ssl.h b/include/polarssl/ssl.h
index fb9a40c8b..cf18ea751 100644
--- a/include/polarssl/ssl.h
+++ b/include/polarssl/ssl.h
@@ -789,6 +789,7 @@ int ssl_get_ciphersuite_id( const char *ciphersuite_name );
 
 /**
  * \brief          Initialize an SSL context
+ *                 (An individual SSL context is not thread-safe)
  *
  * \param ssl      SSL context
  *
diff --git a/include/polarssl/threading.h b/include/polarssl/threading.h
index 4afaeea39..ceb127798 100644
--- a/include/polarssl/threading.h
+++ b/include/polarssl/threading.h
@@ -56,7 +56,7 @@ typedef pthread_mutex_t threading_mutex_t;
  * \brief           Set your alternate threading implementation function
  *                  pointers
  *
- * \param mutex_init    the malloc function implementation
+ * \param mutex_init    the init function implementation
  * \param mutex_free    the free function implementation
  * \param mutex_lock    the lock function implementation
  * \param mutex_unlock  the unlock function implementation
@@ -71,6 +71,8 @@ int threading_set_alt( int (*mutex_init)( threading_mutex_t * ),
 
 /*
  * The function pointers for mutex_init, mutex_free, mutex_ and mutex_unlock
+ *
+ * All these functions are expected to work or the result will be undefined.
  */
 extern int (*polarssl_mutex_init)( threading_mutex_t *mutex );
 extern int (*polarssl_mutex_free)( threading_mutex_t *mutex );