removed virtual, added override specifiers, regenerated documentation
This commit is contained in:
Noah Laptop
parent
8753a7f918
commit
28e1555e76
31 changed files with 424 additions and 424 deletions
|
|
@ -121,9 +121,9 @@ $(document).ready(function(){initNavTree('index.html','');});
|
|||
<h3>Errors</h3>
|
||||
<p>When <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> encounters an error, it will attempt to terminate the SSL session gracefully if possible, and then close the socket. Simple error information can be found from SSLClient::getWriteError(), which will return a value from the <a class="el" href="_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5" title="Static constants defining the possible errors encountered.">Error</a> enum. For more detailed diagnostics, you can look at the serial logs, which will be displayed if the log level is at <code>SSL_ERROR</code> or lower.</p>
|
||||
<h3>Write Buffering</h3>
|
||||
<p>As you may have noticed in the documentation for <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a>, calling this function does not actually write to the network. Instead, you must call <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> or <a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41" title="Force writing the buffered bytes from SSLClient::write to the network.">SSLClient::flush</a>, which will detect that the buffer is ready and write to the network (see <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a> for details).</p>
|
||||
<p>This was implemented as a buffered function because examples in Arduino libraries will often write to the network like so: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">EthernetClient client;</div><div class="line">// ...</div><div class="line">// connect to ardiuino.cc over ssl (port 443 for websites)</div><div class="line">client.connect("www.arduino.cc", 443);</div><div class="line">// ...</div><div class="line">// write an http request to the network</div><div class="line">client.write("GET /asciilogo.txt HTTP/1.1\r\n");</div><div class="line">client.write("Host: arduino.cc\r\n");</div><div class="line">client.write("Connection: close\r\n");</div><div class="line">// wait for response</div><div class="line">while (!client.available()) { /* ... */ }</div><div class="line">// ...</div></div><!-- fragment --><p> Notice that every single write() call immediately writes to the network, which is fine with most network clients. With SSL, however, if we are encrypting and writing to the network every write() call, this will result in a lot of small encryption tasks. Encryption takes a lot of time and code, so to reduce the overhead of an SSL connection, <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a> implicitly buffers until the developer states that they are waiting for data to be received with <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a>. A simple example can be found below:</p>
|
||||
<div class="fragment"><div class="line"> {C++}</div><div class="line">SSLClient<EthernetClient> client(EthernetClient(), TAs, 2, A7);</div><div class="line">// ...</div><div class="line">// connect to ardiuino.cc over ssl (port 443 for websites)</div><div class="line">client.connect("www.arduino.cc", 443);</div><div class="line">// ...</div><div class="line">// add http request to the buffer</div><div class="line">client.write("GET /asciilogo.txt HTTP/1.1\r\n");</div><div class="line">client.write("Host: arduino.cc\r\n");</div><div class="line">client.write("Connection: close\r\n");</div><div class="line">// write the bytes to the network, then wait for response</div><div class="line">while (!client.available()) { /* ... */ }</div><div class="line">// ...</div></div><!-- fragment --><p>If you would like to trigger a network write manually without using the <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a>, you can also call <a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41" title="Force writing the buffered bytes from SSLClient::write to the network.">SSLClient::flush</a>, which will write all data and return when finished.</p>
|
||||
<p>As you may have noticed in the documentation for <a class="el" href="class_s_s_l_client.html#a6b8ff53c10fe34aab1dc2561410f70bb">SSLClient::write</a>, calling this function does not actually write to the network. Instead, you must call <a class="el" href="class_s_s_l_client.html#a5d13fd2f32ee2ea65a1f3820f758e77e" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> or <a class="el" href="class_s_s_l_client.html#a2ee6a3134d07ca09cf61ee04d32c3d44" title="Force writing the buffered bytes from SSLClient::write to the network.">SSLClient::flush</a>, which will detect that the buffer is ready and write to the network (see <a class="el" href="class_s_s_l_client.html#a6b8ff53c10fe34aab1dc2561410f70bb">SSLClient::write</a> for details).</p>
|
||||
<p>This was implemented as a buffered function because examples in Arduino libraries will often write to the network like so: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">EthernetClient client;</div><div class="line">// ...</div><div class="line">// connect to ardiuino.cc over ssl (port 443 for websites)</div><div class="line">client.connect("www.arduino.cc", 443);</div><div class="line">// ...</div><div class="line">// write an http request to the network</div><div class="line">client.write("GET /asciilogo.txt HTTP/1.1\r\n");</div><div class="line">client.write("Host: arduino.cc\r\n");</div><div class="line">client.write("Connection: close\r\n");</div><div class="line">// wait for response</div><div class="line">while (!client.available()) { /* ... */ }</div><div class="line">// ...</div></div><!-- fragment --><p> Notice that every single write() call immediately writes to the network, which is fine with most network clients. With SSL, however, if we are encrypting and writing to the network every write() call, this will result in a lot of small encryption tasks. Encryption takes a lot of time and code, so to reduce the overhead of an SSL connection, <a class="el" href="class_s_s_l_client.html#a6b8ff53c10fe34aab1dc2561410f70bb">SSLClient::write</a> implicitly buffers until the developer states that they are waiting for data to be received with <a class="el" href="class_s_s_l_client.html#a5d13fd2f32ee2ea65a1f3820f758e77e" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a>. A simple example can be found below:</p>
|
||||
<div class="fragment"><div class="line"> {C++}</div><div class="line">SSLClient<EthernetClient> client(EthernetClient(), TAs, 2, A7);</div><div class="line">// ...</div><div class="line">// connect to ardiuino.cc over ssl (port 443 for websites)</div><div class="line">client.connect("www.arduino.cc", 443);</div><div class="line">// ...</div><div class="line">// add http request to the buffer</div><div class="line">client.write("GET /asciilogo.txt HTTP/1.1\r\n");</div><div class="line">client.write("Host: arduino.cc\r\n");</div><div class="line">client.write("Connection: close\r\n");</div><div class="line">// write the bytes to the network, then wait for response</div><div class="line">while (!client.available()) { /* ... */ }</div><div class="line">// ...</div></div><!-- fragment --><p>If you would like to trigger a network write manually without using the <a class="el" href="class_s_s_l_client.html#a5d13fd2f32ee2ea65a1f3820f758e77e" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a>, you can also call <a class="el" href="class_s_s_l_client.html#a2ee6a3134d07ca09cf61ee04d32c3d44" title="Force writing the buffered bytes from SSLClient::write to the network.">SSLClient::flush</a>, which will write all data and return when finished.</p>
|
||||
<h3>Session Caching</h3>
|
||||
<p>As detailed in the <a href="#resources">resources section</a>, SSL handshakes take an extended period (1-4sec) to negotiate. To remedy this problem, BearSSL is able to keep a <a href="https://bearssl.org/api1.html#session-cache">SSL session cache</a> of the clients it has connected to. If BearSSL successfully resumes an SSL session, it can reduce connection time to 100-500ms.</p>
|
||||
<p>In order to use SSL session resumption:</p><ul>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue