Merge pull request #2 from mirrorkeydev/master

Updated documentation for comprehension, readability

TrustAnchors.md

@@ -40,7 +40,7 @@ A full example of a trust anchor header can be found in [this file](./readme/cer
 
 ### HTTPS
 
-For HTTPS, there a couple of tools you can use. Ordered from easy to hard:
+For HTTPS, there a couple of tools you can use. Ordered from easiest to hardest:
 * [This website, written to simplify the creation of trust anchor headers](https://openslab-osu.github.io/bearssl-certificate-utility/). Simply plug and play.
 * [pycert_bearssl](./tools/pycert_bearssl/pycert_bearssl.py), a command line utility based on a [pycert](https://learn.adafruit.com/introducing-the-adafruit-wiced-feather-wifi/pycert-dot-py). You will need to install Python 3, and follow the instructions in the [pycert_bearssl.py file](./tools/pycert_bearssl/pycert_bearssl.py). You'll want to use the `pycert_bearssl.py download` command once the utility is set up.
 * The brssl command line utility, included in the [BearSSL source](https://bearssl.org/gitweb/?p=BearSSL;a=blob_plain;f=tools/brssl.h;hb=HEAD). You will need to compile this file yourself.

src/SSLClient.h

@@ -88,11 +88,11 @@ public:
      * SSLClient::connect(host, port) should be preferred over this function, 
      * as verifying the domain name is a step in ensuring the certificate is 
      * legitimate, which is important to the security of the device. Additionally,
-     * SSL sessions cannot be resumed, which can drastically increase initial
+     * SSL sessions cannot be resumed when using this function, which can drastically increase initial
      * connect time.
      * 
      * This function initializes the socket by calling m_client::connect(IPAddress, uint16_t)
-     * with the parameters supplied, then once the socket uses BearSSL to
+     * with the parameters supplied, then once the socket is open, uses BearSSL to
      * to complete a SSL handshake. Due to the design of the SSL standard, 
      * this function will probably take an extended period (1-4sec) to negotiate 
      * the handshake and finish the connection. This function runs until the SSL 
@@ -127,8 +127,8 @@ public:
      * @brief Connect over SSL to a host specified by a hostname.
      * 
      * This function initializes the socket by calling m_client::connect(const char*, uint16_t)
-     * with the parameters supplied, then once the socket is open uses BearSSL to
+     * with the parameters supplied, then once the socket is open, uses BearSSL to
-     * to complete a SSL handshake. This function runs until the SSL handshake 
+     * complete a SSL handshake. This function runs until the SSL handshake 
      * succeeds or fails.
      * 
      * SSL requires the client to generate some random bits (to be later combined 
@@ -189,7 +189,7 @@ public:
 	virtual size_t write(const uint8_t *buf, size_t size) { return write_impl(buf, size); }
 
     /**
-     * @brief Returns the number of bytes availible to read from the SSL Socket
+     * @brief Returns the number of bytes available to read from the data that has been received and decrypted.
      * 
      * This function updates the state of the SSL engine (including writing any data, 
      * see SSLClient::write) and as a result should be called periodically when expecting data. 
@@ -214,7 +214,7 @@ public:
      */
 	virtual int read() { uint8_t read_val; return read(&read_val, 1) > 0 ? read_val : -1; };
     /**
-     * @brief Read size bytes from the SSL socket buffer, copying them into *buf, and return the number of bytes read.
+     * @brief Read size bytes from the SSL client buffer, copying them into *buf, and return the number of bytes read.
      * 
      * This function checks if bytes are ready to be read by calling SSLClient::available,
      * and if so copies size number of bytes from the IO buffer into the buf pointer.
@@ -237,7 +237,8 @@ public:
 	virtual int read(uint8_t *buf, size_t size) { return read_impl(buf, size); }
 
     /** 
-     * @brief view the first byte of the buffer, without removing it from the SSLClient Buffer
+     * @brief View the first byte of the buffer, without removing it from the SSLClient Buffer
+     * 
      * The implementation for this function can be found in SSLClientImpl::peek 
      * @pre SSLClient::available must be >0
      * @returns The first byte received, or -1 if the preconditions are not satisfied (warning: 
@@ -247,6 +248,7 @@ public:
 
     /**
      * @brief Force writing the buffered bytes from SSLClient::write to the network.
+     * 
      * This function is blocking until all bytes from the buffer are written. For
      * an explanation of how writing with SSLClient works, please see SSLClient::write.
      * The implementation for this function can be found in SSLClientImpl::flush.
@@ -255,6 +257,7 @@ public:
 
     /**
      * @brief Close the connection
+     *
      * If the SSL session is still active, all incoming data is discarded and BearSSL will attempt to
      * close the session gracefully (will write to the network), and then call m_client::stop. If the session is not active or an
      * error was encountered previously, this function will simply call m_client::stop.
@@ -264,6 +267,7 @@ public:
 
     /**
      * @brief Check if the device is connected.
+     *
      * Use this function to determine if SSLClient is still connected and a SSL connection is active.
      * It should be noted that SSLClient::available should be preferred over this function for rapid
      * polling--both functions send and receive data with the SSLClient::m_client device, however SSLClient::available
@@ -280,7 +284,7 @@ public:
     //========================================
 
     /**
-     * @brief Get a session reference corresponding to a host and IP, or a reference to a empty session if none exist
+     * @brief Gets a session reference corresponding to a host and IP, or a reference to a empty session if none exist
      * 
      * If no session corresponding to the host and IP exist, then this function will cycle through
      * sessions in a rotating order. This allows the session cache to continually store sessions,
@@ -307,12 +311,14 @@ public:
 
     /**
      * @brief Get the maximum number of SSL sessions that can be stored at once
+     *
      *  @returns The SessionCache template parameter.
      */
     virtual size_t getSessionCount() const { return SessionCache; }
 
     /** 
      * @brief Equivalent to SSLClient::connected() > 0
+     * 
      * @returns true if connected, false if not
      */
 	virtual operator bool() { return connected() > 0; }
@@ -349,14 +355,14 @@ public:
         } 
     }
 
-    /** @brief returns a reference to the client object stored in this class. Take care not to break it. */
+    /** @brief Returns a reference to the client object stored in this class. Take care not to break it. */
     C& getClient() { return m_client; }
 
 protected:
-    /** @brief return an instance of m_client that is polymorphic and can be used by SSLClientImpl */
+    /** @brief Returns an instance of m_client that is polymorphic and can be used by SSLClientImpl */
     virtual Client& get_arduino_client() { return m_client; }
     virtual const Client& get_arduino_client() const { return m_client; }
-    /** @brief return an instance of the session array that is on the stack */
+    /** @brief Returns an instance of the session array that is on the stack */
     virtual SSLSession* get_session_array() { return m_sessions; }
     virtual const SSLSession* get_session_array() const { return m_sessions; }
 

src/SSLSession.h

@@ -70,7 +70,7 @@ public:
      * 
      * @returns A String object or "" if there is no hostname
      * @pre must check isValidSession before getting this value,
-     * as if this session in invalid this value is not guarented
+     * as if this session in invalid this value is not guarenteed
      * to be reset to "".
      */
     const String& get_hostname() const { return m_hostname; }
@@ -80,7 +80,7 @@ public:
      * 
      * @returns A ::IPAddress object, #INADDR_NONE if there is no IP
      * @pre must check isValidSession before getting this value,
-     * as if this session in invalid this value is not guarented
+     * as if this session in invalid this value is not guarenteed
      * to be reset to #INADDR_NONE.
      */
     const IPAddress& get_ip() const { return m_ip; }
@@ -98,7 +98,7 @@ public:
      * @pre You must call 
      * ::br_ssl_engine_get_session_parameters
      * with this session before calling this function. This is because
-     * there is no way to completly validate the ::br_ssl_session_parameters
+     * there is no way to completely validate the ::br_ssl_session_parameters
      * and the session may end up in a corrupted state if this is not observed.
      * 
      * @param ip The IP address of the host associated with the session
@@ -109,14 +109,15 @@ public:
     void set_parameters(const IPAddress& ip, const char* hostname = NULL);
 
     /**
-     * @brief delete the parameters and invalidate the session
+     * @brief Delete the parameters and invalidate the session.
+     *
      * Roughly equivalent to this_session = SSLSession(), however 
      * this function preserves the String object, allowing it
      * to better handle the dynamic memory needed.
      */
     void clear_parameters();
 
-    /** @brief returns a pointer to the ::br_ssl_session_parameters component of this class */
+    /** @brief Returns a pointer to the ::br_ssl_session_parameters component of this class. */
     br_ssl_session_parameters* to_br_session() { return (br_ssl_session_parameters *)this; }
 
 private: