Merged massive SSL Testing improvements
diff --git a/ChangeLog b/ChangeLog
index 2dd0c28..0667d23 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -14,6 +14,8 @@
    * entropy_add_source(), entropy_update_manual() and entropy_gather()
      now thread-safe if POLARSSL_THREADING_C defined
    * Improvements to the CMake build system, contributed by Julian Ospald.
+   * Work around a bug of the version of Clang shipped by Apple with Mavericks
+     that prevented bignum.c from compiling. (Reported by Rafael Baptista.)
 
 Security
    * Forbid change of server certificate during renegotiation to prevent
diff --git a/include/polarssl/pk.h b/include/polarssl/pk.h
index 013d973..6f21dab 100644
--- a/include/polarssl/pk.h
+++ b/include/polarssl/pk.h
@@ -400,6 +400,12 @@
  * \param pwd       password for decryption (optional)
  * \param pwdlen    size of the password
  *
+ * \note            On entry, ctx must be empty, either freshly initialised
+ *                  with pk_init() or reset with pk_free(). If you need a
+ *                  specific key type, check the result with pk_can_do().
+ *
+ * \note            The key is also checked for correctness.
+ *
  * \return          0 if successful, or a specific PK or PEM error code
  */
 int pk_parse_key( pk_context *ctx,
@@ -414,6 +420,12 @@
  * \param key       input buffer
  * \param keylen    size of the buffer
  *
+ * \note            On entry, ctx must be empty, either freshly initialised
+ *                  with pk_init() or reset with pk_free(). If you need a
+ *                  specific key type, check the result with pk_can_do().
+ *
+ * \note            The key is also checked for correctness.
+ *
  * \return          0 if successful, or a specific PK or PEM error code
  */
 int pk_parse_public_key( pk_context *ctx,
@@ -428,6 +440,12 @@
  * \param path      filename to read the private key from
  * \param password  password to decrypt the file (can be NULL)
  *
+ * \note            On entry, ctx must be empty, either freshly initialised
+ *                  with pk_init() or reset with pk_free(). If you need a
+ *                  specific key type, check the result with pk_can_do().
+ *
+ * \note            The key is also checked for correctness.
+ *
  * \return          0 if successful, or a specific PK or PEM error code
  */
 int pk_parse_keyfile( pk_context *ctx,
@@ -440,6 +458,12 @@
  * \param ctx       key to be initialized
  * \param path      filename to read the private key from
  *
+ * \note            On entry, ctx must be empty, either freshly initialised
+ *                  with pk_init() or reset with pk_free(). If you need a
+ *                  specific key type, check the result with pk_can_do().
+ *
+ * \note            The key is also checked for correctness.
+ *
  * \return          0 if successful, or a specific PK or PEM error code
  */
 int pk_parse_public_keyfile( pk_context *ctx, const char *path );
diff --git a/library/bignum.c b/library/bignum.c
index a73bf76..d9a22c1 100644
--- a/library/bignum.c
+++ b/library/bignum.c
@@ -1232,7 +1232,14 @@
             Z.p[i - t - 1] = ~0;
         else
         {
-#if defined(POLARSSL_HAVE_UDBL)
+            /*
+             * The version of Clang shipped by Apple with Mavericks can't
+             * handle 128-bit division properly. Disable 128-bits division
+             * for Clang on Apple for now, while waiting for more input on the
+             * exact version(s) affected and their identification macros.
+             */
+#if defined(POLARSSL_HAVE_UDBL) && \
+    ! ( defined(__x86_64__) && defined(__clang__) && defined(__APPLE__) )
             t_udbl r;
 
             r  = (t_udbl) X.p[i] << biL;
diff --git a/programs/ssl/ssl_client1.c b/programs/ssl/ssl_client1.c
index efb210e..11e04f3 100644
--- a/programs/ssl/ssl_client1.c
+++ b/programs/ssl/ssl_client1.c
@@ -155,6 +155,8 @@
     printf( " ok\n" );
 
     ssl_set_endpoint( &ssl, SSL_IS_CLIENT );
+    /* OPTIONAL is not optimal for security,
+     * but makes interop easier in this simplified example */
     ssl_set_authmode( &ssl, SSL_VERIFY_OPTIONAL );
     ssl_set_ca_chain( &ssl, &cacert, NULL, "PolarSSL Server 1" );
 
@@ -185,6 +187,7 @@
      */
     printf( "  . Verifying peer X.509 certificate..." );
 
+    /* In real life, we may want to bail out when ret != 0 */
     if( ( ret = ssl_get_verify_result( &ssl ) ) != 0 )
     {
         printf( " failed\n" );
diff --git a/programs/ssl/ssl_client2.c b/programs/ssl/ssl_client2.c
index 0665a8e..3b8dec7 100644
--- a/programs/ssl/ssl_client2.c
+++ b/programs/ssl/ssl_client2.c
@@ -59,7 +59,7 @@
 #define DFL_RENEGOTIATE         0
 #define DFL_MIN_VERSION         -1
 #define DFL_MAX_VERSION         -1
-#define DFL_AUTH_MODE           SSL_VERIFY_OPTIONAL
+#define DFL_AUTH_MODE           SSL_VERIFY_REQUIRED
 #define DFL_MFL_CODE            SSL_MAX_FRAG_LEN_NONE
 #define DFL_TRUNC_HMAC          0
 #define DFL_RECONNECT           0
@@ -283,7 +283,7 @@
     "    max_version=%%s      default: \"\" (tls1_2)\n"     \
     "    force_version=%%s    default: \"\" (none)\n"       \
     "                        options: ssl3, tls1, tls1_1, tls1_2\n" \
-    "    auth_mode=%%s        default: \"optional\"\n"          \
+    "    auth_mode=%%s        default: \"required\"\n"      \
     "                        options: none, optional, required\n" \
     "\n"                                                    \
     "    force_ciphersuite=<name>    default: all enabled\n"\
@@ -861,7 +861,16 @@
     {
         if( ret != POLARSSL_ERR_NET_WANT_READ && ret != POLARSSL_ERR_NET_WANT_WRITE )
         {
-            printf( " failed\n  ! ssl_handshake returned -0x%x\n\n", -ret );
+            printf( " failed\n  ! ssl_handshake returned -0x%x\n", -ret );
+            if( ret == POLARSSL_ERR_X509_CERT_VERIFY_FAILED )
+                printf(
+                    "    Unable to verify the server's certificate. "
+                        "Either it is invalid,\n"
+                    "    or you didn't set ca_file or ca_path "
+                        "to an appropriate value.\n"
+                    "    Alternatively, you may want to use "
+                        "auth_mode=optional for testing purposes.\n" );
+            printf( "\n" );
             goto exit;
         }
     }
diff --git a/programs/ssl/ssl_mail_client.c b/programs/ssl/ssl_mail_client.c
index a0e1cb6..8d1b060 100644
--- a/programs/ssl/ssl_mail_client.c
+++ b/programs/ssl/ssl_mail_client.c
@@ -156,6 +156,7 @@
      */
     printf( "  . Verifying peer X.509 certificate..." );
 
+    /* In real life, we may want to bail out when ret != 0 */
     if( ( ret = ssl_get_verify_result( ssl ) ) != 0 )
     {
         printf( " failed\n" );
@@ -590,6 +591,8 @@
     printf( " ok\n" );
 
     ssl_set_endpoint( &ssl, SSL_IS_CLIENT );
+    /* OPTIONAL is not optimal for security,
+     * but makes interop easier in this simplified example */
     ssl_set_authmode( &ssl, SSL_VERIFY_OPTIONAL );
 
     ssl_set_rng( &ssl, ctr_drbg_random, &ctr_drbg );