- added documentation for TLS API/SPI

src/tls/mbedtls/tls_mbedtls.c

@@ -398,6 +398,17 @@ TLSSocket_getPeerCertificate(TLSSocket self, int* certSize)
     return self->peerCert;
 }
 
+bool
+TLSSocket_performHandshake(TLSSocket self)
+{
+    //TODO evaluate return value
+
+    if (mbedtls_ssl_renegotiate(&(self->ssl)) == 0)
+        return true;
+    else
+        return false;
+}
+
 int
 TLSSocket_read(TLSSocket self, uint8_t* buf, int size)
 {

src/tls/tls_api.h

@@ -25,22 +25,55 @@ typedef struct sTLSConfiguration* TLSConfiguration;
 
 typedef struct sTLSSocket* TLSSocket;
 
+/**
+ * \brief Create a new \ref TLSConfiguration object to represent TLS configuration and certificates
+ *
+ * \return the new TLS configuration
+ */
 TLSConfiguration
 TLSConfiguration_create(void);
 
-/* will be called by stack automatically */
+/* will be called by stack automatically when appropriate */
 void
 TLSConfiguration_setClientMode(TLSConfiguration self);
 
+/**
+ * \brief Enables the validation of the certificate trust chain (enabled by default)
+ *
+ * \param value true to enable chain validation, false to disable
+ */
 void
 TLSConfiguration_setChainValidation(TLSConfiguration self, bool value);
 
+/**
+ * \brief Set if only known certificates are accepted.
+ *
+ * If set to true only known certificates are accepted. Connections with unknown certificates
+ * are rejected even if they are signed by a trusted authority.
+ *
+ * \param value true to enable setting, false otherwise
+ */
 void
 TLSConfiguration_setAllowOnlyKnownCertificates(TLSConfiguration self, bool value);
 
+/**
+ * \brief Set own certificate (identity) from a byte buffer
+ *
+ * \param certificate the certificate buffer
+ * \param certLen the lenght of the certificate
+ *
+ * \return true, when the certificate was set, false otherwise (e.g. unknown certificate format)
+ */
 bool
 TLSConfiguration_setOwnCertificate(TLSConfiguration self, uint8_t* certificate, int certLen);
 
+/**
+ * \brief Set own certificate (identity) from a certificate file
+ *
+ * \param filename of the certificate file
+ *
+ * \return true, when the certificate was set, false otherwise (e.g. unknown certificate format)
+ */
 bool
 TLSConfiguration_setOwnCertificateFromFile(TLSConfiguration self, const char* filename);
 
@@ -62,15 +95,35 @@ TLSConfiguration_addCACertificate(TLSConfiguration self, uint8_t* certifcate, in
 bool
 TLSConfiguration_addCACertificateFromFile(TLSConfiguration self, const char* filename);
 
+/**
+ * \brief Set the renegotiation timeout.
+ *
+ * After the timeout elapsed a TLS session renegotiation has to occur.
+ *
+ * \param timeInMs session renegotiation timeout in milliseconds
+ */
+void
+TLSConfiguration_setRenegotiationTime(TLSConfiguration self, int timeInMs);
+
 void
 TLSConfiguration_destroy(TLSConfiguration self);
 
 TLSSocket
 TLSSocket_create(Socket socket, TLSConfiguration configuration, bool storeClientCert);
 
+/**
+ * \brief Perform a new TLS handshake/session renegotiation
+ */
 bool
 TLSSocket_performHandshake(TLSSocket self);
 
+/**
+ * \brief Access the certificate used by the peer
+ *
+ * \param[out] certSize the size of the certificate in bytes
+ *
+ * \return the certificate byte buffer
+ */
 uint8_t*
 TLSSocket_getPeerCertificate(TLSSocket self, int* certSize);
 
@@ -105,6 +158,9 @@ TLSSocket_read(TLSSocket self, uint8_t* buf, int size);
 int
 TLSSocket_write(TLSSocket self, uint8_t* buf, int size);
 
+/**
+ * \brief Close the TLS socket and release all resources
+ */
 void
 TLSSocket_close(TLSSocket self);