pigweed/pw_tls_client/docs.rst

.. _module-pw_tls_client:

--------------
pw_tls_client
--------------

This module provides a facade that defines the public APIs for establishing TLS
sessions over arbitrary transports. Two options of backends,
pw_tls_client_mbedtls and pw_tls_client_boringssl, which are based on BoringSSL
and MbedTLS libraries, are under construction.

The facade provides a class ``pw::tls_client::Session`` with Open(), Read(),
Write() and Close() methods for TLS communication. An instance is created by
``pw::tls_client::Session::Create`` method. The method takes a
``pw::tls_client::SessionOptions`` object, which is used to configure TLS
connection options. The list of supported configurations currently include:

1. Host name of the target server. This will be used as the Server Name
   Indication(SNI) extension during TLS handshake.

2. User-implemented transport. The underlying transport for the TLS
   communication. It is an object that implements the interface of
   ``pw::stream::ReaderWriter``.

The module will also provide mechanisms/APIs for users to specify sources of
trust anchors, time and entropy. These are under construction.

.. warning::
   This module is under construction, not ready for use, and the documentation
   is incomplete.

Prerequisites
=============
This module requires the following dependencies:

1. Entropy
-----------
TLS requires an entropy source for generating random bytes. Users of this
module should provide one by implementing a backend to the
``pw_tls_client:entropy`` facade. The backend defaults to
``pw_tls_client:fake_entropy`` that does nothing.

2. Chromium Verifier
---------------------
BoringSSL backend uses chromium verifier for certication verification. If the
downstream project uses BoringSSL as the backend, the sources of the verifier,
which is part of the chorimum sources, needs to be downloaded in order for
``//third_party/chromium_verifier`` to build. It is recommended to use our
support in pw_package for downloading compatible and tested version:

.. code-block:: sh

   pw package install chromium_verifier

Then follow instruction for setting ``dir_pw_third_party_chromium_verifier`` to
the path of the downloaded repo.

3. Date time
-------------
TLS needs a trust-worthy source of wall clock time in order to check
expiration. Provisioning of time source for TLS communication is very specific
to the TLS library in use. However, common TLS libraires, such as BoringSSL
and MbedTLS, support the use of C APIs ``time()`` and ``getimtofday()`` for
obtaining date time. To accomodate the use of these libraries, a facade target
``pw_tls_client:time`` is added that wraps these APIs. For GN builds,
specify the backend target with variable ``pw_tls_client_TIME_BACKEND``.
``pw_tls_client_TIME_BACKEND`` defaults to the ``pw_chrono::wrap_time_build_time``
backend that returns build time.

If downstream project chooses to use other TLS libraires that handle time source
differently, then it needs to be investigated separately.

4. CRLSet
-----------
The module supports CRLSet based revocation check for certificates. A CRLSet
file specifies a list of X509 certificates that either need to be blocked, or
have been revoked by the issuer. It is introduced by chromium and primarily
used for certificate verification/revocation checks during TLS handshake. The
format of a CRLSet file is available in
https://chromium.googlesource.com/chromium/src/+/refs/heads/main/net/cert/crl_set.cc#24.

Downstream projects need to provide a CRLSet file at build time. For GN builds,
specify the path of the CRLSet file with the GN variable
``pw_tls_client_CRLSET_FILE``. This module converts the CRLSet file into
source code at build time and generates APIs for querying certificate
block/revocation status. See ``pw_tls_client/crlset.h`` for more detail.

Chromium maintains its own CRLSet that targets at the general Internet. To use it,
run the following command to download the latest version:

.. code-block:: sh

   pw package install crlset --force

The `--force` option forces CRLSet to be always re-downloaded so that it is
up-to-date. Project that are concerned about up-to-date CRLSet should always
run the above command before build.

Toolings will be provided for generating custom CRLSet files from user-provided
certificate files. The functionality is under construction.

Setup
=====
This module requires the following setup:

1. Choose a ``pw_tls_client`` backend, or write one yourself.
2. If using GN build, Specify the ``pw_tls_client_BACKEND`` GN build arg to
   point the library that provides a ``pw_tls_client`` backend. To use the
   MbedTLS backend, set variable ``pw_tls_client_BACKEND`` to
   ``//pw_tls_client_mbedtls``. To use the BoringSSL backend, set it to
   ``//pw_tls_client_boringssl``.
3. Provide a `pw_tls_client:entropy` backend. If using GN build, specify the
   backend with variable ``pw_tls_client_ENTROPY_BACKEND``.

Module usage
============
For GN build, add ``//pw_tls_client`` to the dependency list.

The following gives an example code for using the module on host platform.
The example uses a Pigweed socket stream as the transport and performs TLS
connection to www.google.com:

.. code-block:: cpp

   // Host domain name
   constexpr char kHost[] = "www.google.com";

   constexpr int kPort = 443;

   // Server Name Indication.
   constexpr const char* kServerNameIndication = kHost;

   // An example message to send.
   constexpr char kHTTPRequest[] = "GET / HTTP/1.1\r\n\r\n";

   // pw::stream::SocketStream doesn't accept host domain name as input. Thus we
   // introduce this helper function for getting the IP address
   pw::Status GetIPAddrFromHostName(std::string_view host, pw::span<char> ip) {
     char null_terminated_host_name[256] = {0};
     auto host_copy_status = pw::string::Copy(host, null_terminated_host_name);
     if (!host_copy_status.ok()) {
       return host_copy_status.status();
     }

     struct hostent* ent = gethostbyname(null_terminated_host_name);
     if (ent == NULL) {
       return PW_STATUS_INTERNAL;
     }

     in_addr** addr_list = reinterpret_cast<in_addr**>(ent->h_addr_list);
     if (addr_list[0] == nullptr) {
       return PW_STATUS_INTERNAL;
     }

     auto ip_copy_status = pw::string::Copy(inet_ntoa(*addr_list[0]), ip);
     if (!ip_copy_status.ok()) {
       return ip_copy_status.status();
     }

     return pw::OkStatus();
   }

   int main() {
     // Get the IP address of the target host.
     char ip_address[64] = {0};
     auto get_ip_status = GetIPAddrFromHostName(kHost, ip_address);
     if (!get_ip_status.ok()) {
       return 1;
     }

     // Use a socket stream as the transport.
     pw::stream::SocketStream socket_stream;

     // Connect the socket to the remote host.
     auto socket_connect_status = socket_stream.Connect(ip_address, kPort);
     if (!socket_connect_status.ok()) {
       return 1;
     }

     // Create a TLS session. Register the transport.
     auto options = pw::tls_client::SessionOptions()
             .set_server_name(kServerNameIndication)
             .set_transport(socket_stream);
     auto tls_conn = pw::tls_client::Session::Create(options);
     if (!tls_conn.ok()) {
       // Handle errors.
       return 1;
     }

     auto open_status = tls_conn.value()->Open();
     if (!open_status.ok()) {
       // Inspect/handle error with open_status.code() and
       // tls_conn.value()->GetLastTLSStatus().
       return 1;
     }

     auto write_status = tls_conn.value()->Write(pw::as_bytes(pw::span{kHTTPRequest}));
     if (!write_status.ok()) {
       // Inspect/handle error with write_status.code() and
       // tls_conn.value()->GetLastTLSStatus().
       return 0;
     }

     // Listen for incoming data.
     std::array<std::byte, 4096> buffer;
     while (true) {
       auto res = tls_conn.value()->Read(buffer);
       if (!res.ok()) {
         // Inspect/handle error with res.status().code() and
         // tls_conn.value()->GetLastTLSStatus().
         return 1;
       }

       // Process data in |buffer|. res.value() gives the span of read bytes.
       // The following simply print to console.
       if (res.value().size()) {
         auto print_status = pw::sys_io::WriteBytes(res.value());
         if (!print_status.ok()) {
           return 1;
         }
       }

     }
   }

A list of other demos will be provided in ``//pw_tls_client/examples/``

.. warning::
   Open()/Read() APIs are synchronous for now. Support for
   non-blocking/asynchronous usage will be added in the future.


.. toctree::
   :hidden:
   :maxdepth: 1

   Backends <backends>