From b36f9ca5dc60da27da8773a983f18531d88d3a33 Mon Sep 17 00:00:00 2001 From: Melanie Date: Sun, 31 Mar 2019 16:39:10 -0700 Subject: [PATCH] Updated documentation for comprehension, readability --- TrustAnchors.md | 2 +- src/SSLClient.h | 30 ++++++++++++++++++------------ src/SSLSession.h | 11 ++++++----- 3 files changed, 25 insertions(+), 18 deletions(-) diff --git a/TrustAnchors.md b/TrustAnchors.md index 851e626..a04e4cb 100644 --- a/TrustAnchors.md +++ b/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. diff --git a/src/SSLClient.h b/src/SSLClient.h index 3dd88d2..0a08d34 100644 --- a/src/SSLClient.h +++ b/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 - * to complete a SSL handshake. This function runs until the SSL handshake + * with the parameters supplied, then once the socket is open, uses BearSSL to + * 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. + * + * @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; } diff --git a/src/SSLSession.h b/src/SSLSession.h index 716b4c8..b6ca188 100644 --- a/src/SSLSession.h +++ b/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: