Documentation of TLSSocket behavior on AUTH_FAILURE

UNITTESTS/features/netsocket/DTLSSocketWrapper/test_DTLSSocketWrapper.cpp

@@ -163,7 +163,7 @@ TEST_F(TestDTLSSocketWrapper, connect_fail_ctr_drbg_seed)
     stack.return_value = NSAPI_ERROR_OK;
     const SocketAddress a("127.0.0.1", 1024);
     stack.return_socketAddress = a;
-    EXPECT_EQ(wrapper->connect(a), NSAPI_ERROR_PARAMETER);
+    EXPECT_EQ(wrapper->connect(a), NSAPI_ERROR_AUTH_FAILURE);
     mbedtls_stub.crt_expected_int = 0;
 }
 
@@ -175,7 +175,7 @@ TEST_F(TestDTLSSocketWrapper, connect_fail_ssl_setup)
     stack.return_value = NSAPI_ERROR_OK;
     const SocketAddress a("127.0.0.1", 1024);
     stack.return_socketAddress = a;
-    EXPECT_EQ(wrapper->connect(a), NSAPI_ERROR_PARAMETER);
+    EXPECT_EQ(wrapper->connect(a), NSAPI_ERROR_AUTH_FAILURE);
 }
 
 /* send */

UNITTESTS/features/netsocket/TLSSocketWrapper/test_TLSSocketWrapper.cpp

@@ -159,7 +159,7 @@ TEST_F(TestTLSSocketWrapper, connect_fail_ctr_drbg_seed)
     mbedtls_stub.crt_expected_int = 1; // mbedtls_ctr_drbg_seed error
     stack.return_value = NSAPI_ERROR_OK;
     const SocketAddress a("127.0.0.1", 1024);
-    EXPECT_EQ(wrapper->connect(a), NSAPI_ERROR_PARAMETER);
+    EXPECT_EQ(wrapper->connect(a), NSAPI_ERROR_AUTH_FAILURE);
     mbedtls_stub.crt_expected_int = 0;
 }
 
@@ -171,7 +171,7 @@ TEST_F(TestTLSSocketWrapper, connect_fail_ssl_setup)
     mbedtls_stub.retArray[1] = 2; // mbedtls_ssl_setup           error
     stack.return_value = NSAPI_ERROR_OK;
     const SocketAddress a("127.0.0.1", 1024);
-    EXPECT_EQ(wrapper->connect(a), NSAPI_ERROR_PARAMETER);
+    EXPECT_EQ(wrapper->connect(a), NSAPI_ERROR_AUTH_FAILURE);
 }
 
 TEST_F(TestTLSSocketWrapper, connect_handshake_fail_ssl_handshake)

features/netsocket/Socket.h

@@ -64,6 +64,9 @@ class Socket {
      *  To reset the peer address, there must be zero initialized(default constructor) SocketAddress
      *  objects in the address parameter.
      *
+     *  @note If connect() fails it is recommended to close the Socket and create
+     *  a new one before attempting to reconnect.
+     *
      *  @param address  The SocketAddress of the remote peer.
      *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */

features/netsocket/TLSSocket.h

@@ -82,6 +82,9 @@ class TLSSocket : public TLSSocketWrapper {
      *  Initiates a connection to a remote server specified by either
      *  a domain name or an IP address and port.
      *
+     *  @note: In case connect() returns NSAPI_ERROR_AUTH_FAILURE,
+     *  the socket must be freed either by calling close() or destroying it.
+     *
      *  @param host     Hostname of the remote host.
      *  @param port     Port of the remote host.
      *  @return         0 on success, negative error code on failure.

features/netsocket/TLSSocketWrapper.cpp

@@ -171,7 +171,7 @@ nsapi_error_t TLSSocketWrapper::start_handshake(bool first_call)
                                      (const unsigned char *) DRBG_PERS,
                                      sizeof(DRBG_PERS))) != 0) {
         print_mbedtls_error("mbedtls_crt_drbg_init", ret);
-        return NSAPI_ERROR_PARAMETER;
+        return NSAPI_ERROR_AUTH_FAILURE;
     }
 
     mbedtls_ssl_conf_rng(get_ssl_config(), mbedtls_ctr_drbg_random, &_ctr_drbg);
@@ -186,7 +186,7 @@ nsapi_error_t TLSSocketWrapper::start_handshake(bool first_call)
     tr_debug("mbedtls_ssl_setup()");
     if ((ret = mbedtls_ssl_setup(&_ssl, get_ssl_config())) != 0) {
         print_mbedtls_error("mbedtls_ssl_setup", ret);
-        return NSAPI_ERROR_PARAMETER;
+        return NSAPI_ERROR_AUTH_FAILURE;
     }
 
     _transport->set_blocking(false);

features/netsocket/TLSSocketWrapper.h

@@ -76,6 +76,8 @@ class TLSSocketWrapper : public Socket {
     void set_hostname(const char *hostname);
 
     /** Sets the certification of Root CA.
+     *
+     * @note Must be called before calling connect()
      *
      * @param root_ca Root CA Certificate in any Mbed TLS-supported format.
      * @param len     Length of certificate (including terminating 0 for PEM).
@@ -84,9 +86,10 @@ class TLSSocketWrapper : public Socket {
     nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
 
     /** Sets the certification of Root CA.
+     *
+     * @note Must be called before calling connect()
      *
      * @param root_ca_pem Root CA Certificate in PEM format.
-     * @return            0 on success, negative error code on failure.
      */
     nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
 
@@ -136,6 +139,10 @@ class TLSSocketWrapper : public Socket {
 
     /* = Functions inherited from Socket = */
     virtual nsapi_error_t close();
+    /*
+     *  @note: In case connect() returns an error, the state of the socket is
+     *  unspecified. A new socket should be created before reconnecting.
+     */
     virtual nsapi_error_t connect(const SocketAddress &address = SocketAddress());
     virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size);
     virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,