arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-07-27 18:02:17 +03:00
Code Activity

Add BearSSL documentation (#5311)

Browse Source 
Document the BearSSL::WiFiClientSecure, ::WiFiServerSecure, and the
helper classes required to use them.
This commit is contained in:
Earle F. Philhower, III
2018-11-06 11:45:52 -08:00
committed by GitHub
parent 6e0c0e3dcc
commit feb86cd4ff
3 changed files with 279 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
doc/esp8266wifi/bearssl-server-secure-class.rst Normal file
View File

@ -0,0 +1,44 @@
:orphan:
BearSSL Secure Server Class
---------------------------
Implements a TLS encrypted server with optional client certificate validation. See `Server Class <server-class.rst>`__ for general information and `BearSSL Secure Client Class <bearssl-secure-client-class.rst>`__ for basic server and BearSSL concepts.
setBufferSizes(int recv, int xmit)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Similar to the `BearSSL::WiFiClientSecure` method, sets the receive and transmit buffer sizes. Note that servers cannot request a buffer size from the client, so if these are shrunk and the client tries to send a chunk larger than the receive buffer, it will always fail. This must be called before the server is
Setting Server Certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~
TLS servers require a certificate identifying itself and containing its public key, and a private key they will use to encrypt information with. The application author is responsible for generating this certificate and key, either using a self-signed generator or using a commercial certification authority. **Do not re-use the certificates included in the examples provided.**
This example command will generate a RSA 2048-bit key and certificate:
.. code::
openssl req -x509 -nodes -newkey rsa:2048 -keyout key.pem -out cert.pem -days 4096
Again, it is up to the application author to generate this certificate and key and keep the private key safe and **private.**
setRSACert(const BearSSLX509List *chain, const BearSSLPrivateKey *sk)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sets a RSA certificate and key to be used by the server when connections are received. Needs to be called before `begin()`
setECCert(const BearSSLX509List *chain, unsigned cert_issuer_key_type, const BearSSLPrivateKey *sk)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sets an elliptic curve certificate and key for the server. Needs to be called before `begin()`.
Requiring Client Certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TLS servers can request the client to identify itself by transmitting a certificate during handshake. If the client cannot transmit the certificate, the connection will be dropped by the server.
setClientTrustAnchor(const BearSSLX509List *client_CA_ta)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sets the trust anchor (normally a self-signing CA) that all received certificates will be verified against. Needs to be called before `begin()`.