TLS

This API supports transport layer security (TLS), historically known as a 'secure socket layer'. There are two parts of making secure connections: authentication and encryption. This API creates an encrypted channel by using X509 certificates as public keys to initiate a session key exchange. It also performs part of authentication, by verifying that a certificate is trusted. The other core part of authentication is host name verification, which checks that the server you are talking to actually matches that which the certificate has been issued for; host name verification is left to the programmer to do separately as it can be protocol-specific.

Functions

TLS(storeTLSContext context)

bool accept(TCPSocket socket)

bool connect(TCPSocket socket)

char[] getPeerCertificate()

String[] getPeerCertChain()

VerifyStatus verifyCertificate(TLSCertStore storeData, char certificate[], String chain[])

void close()

TLS(storeTLSContext context)

Instantiate a new secure session object, using the configuration in the given TLSContext object.

bool accept(TCPSocket socket)

This function is used by servers to accept new client connections.

socket A TCPSocket instance which has already been connected to a remote host via the TCP accept() function

bool connect(TCPSocket socket)

This function allows you to connect to a remote host using a TLS handshake, creating an encrypted channel. After connecting, you can then send/recv encrypted data over this channel. However, connecting in itself *does not* verify that the remote host has an authentic TLS (X509) certificate and is therefore trustworthy. In order to assure that the certificate is actually authentic, you must do this verification immediately after connect() by using verifyCertificate() and then, based on the result, decide on whether or not you wish to send any data. Note that you should *also* perform host name verification yourself before sending any data.

socket A TCPSocket instance which has already been connected to a remote host

char[] getPeerCertificate()

Get the certificate of the remote host, which can be queried or used in verifyCertificate(). The certificate is returned in base64-encoded PEM format.

String[] getPeerCertChain()

Get the certificate chain of the remote host, which can be queried or used in verifyCertificate(). The certificate chain is returned as an array base64-encoded PEM format certificates.

VerifyStatus verifyCertificate(TLSCertStore storeData, char certificate[], String chain[])

This function allows you to verify a certificate, as returned by getPeerCertificate() or getPeerCertChain(). A TLSCertStore instance must be passed in which holds root certificates that you intend to trust. It is still your responsibility to perform host name verification separately.