Cripts: Adds some certificate introspection (#12320)

* Cripts: Adds some certificate introspection

* Use the Cripts mixin string_view type

* Fixes autest for Cripts, and adds some more tests

Author: zwoop

doc/developer-guide/cripts/cripts-certs.en.rst

@@ -0,0 +1,186 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. include:: ../../common.defs
+
+.. highlight:: cpp
+.. default-domain:: cpp
+
+.. _cripts-certs:
+
+Certificates
+************
+
+Cripts provides a set of convenient classes for introspection into the various
+TLS certificates that are used. These include both the server certificates used
+to establish a TLS connections, as well as any client certificates used for
+mutual TLS.
+
+In the current implementation, these objects only work on X509 certificates as
+associated with the ``client`` and ``server`` connections. Let's start off with
+a simple example of how to use these objects:
+
+.. code-block:: cpp
+
+   do_send_response()
+   {
+     if (client.connection.IsTLS()) {
+       const auto tls = cripts::Certs::Server(client.connection);
+
+       client.response["X-Subject"] = tls.subject;
+       client.response["X-NotBefore"] = tls.notBefore;
+       client.response["X-NotAfter"] = tls.notAfter;
+     }
+   }
+
+.. _cripts-certs-objects:
+
+Objects
+=======
+
+There are two types of objects for the certificates:
+
+=================================   ===============================================================
+Object                              Description
+=================================   ===============================================================
+``cripts::Certs::Server``           The certificate used on the connection for TLS handshakes.
+``cripts::Certs::Client``           The mutual TLS (mTLS) certificate used on the connection.
+=================================   ===============================================================
+
+This combined with the two kinds of connections, ``cripts::Client::Connection`` and
+``cripts::Server::Connection`` yields a total of four possible certificate objects. For example, to
+access the client mTLS provided certificate on a client connection, you would use:
+
+.. code-block:: cpp
+
+   const auto tls = cripts::Certs::Client(cripts::Client::Connection::Get());
+
+Or if you are using the convenience wrappers:
+
+.. code-block:: cpp
+
+   const auto tls = cripts::Certs::Client(client.connection);
+
+.. _cripts-certs-x509:
+
+X509 Values
+===========
+
+As part of the certificate objects, there are a number of values that can be
+accessed. These values are all based on the X509 standard and can be used to
+introspect the certificate. The following values are available:
+
+=================================   ===============================================================
+Value                               Description
+=================================   ===============================================================
+``certificate``                     The raw X509 certificate in PEM format.
+``signature``                       The raw signature of the certificate.
+``subject``                         The subject of the certificate.
+``issuer``                          The issuer of the certificate.
+``serialNumber``                    The serial number of the certificate.
+``notBefore``                       The date and time when the certificate is valid from.
+``notAfter``                        The date and time when the certificate is valid until.
+``version``                         The version of the certificate.
+=================================   ===============================================================
+
+.. _cripts-certs-san:
+
+SAN Values
+==========
+
+We've made special provisions to access the Subject Alternative Name (SAN) values
+of the certificate. These values are often used to identify the hostnames or IP
+addresses that the certificate is valid for. Once you have the certificate object,
+you can access the SAN values as follows:
+
+====================   ===============   ===============================================================
+Field                  X509 field        Description
+====================   ===============   ===============================================================
+``.san``               na                An array of tuples with type and ``string_view`` of  all SANs.
+``.san.email``         ``GEN_EMAIL``     An array of ``string_view`` of email addresses.
+``.san.dns``           ``GEN_DNS``       An array of ``string_view`` of DNS names.
+``.san.uri``           ``GEN_URI``       An array of ``string_view`` of URIs.
+``.san.ipadd``         ``GEN_IPADD``     An array of ``string_view`` of IP addresses.
+====================   ===============   ===============================================================
+
+.. note::
+
+   These arrays are empty if no SAN values are present in the certificate. We also populate these
+   arrays lazily, but they are kept for the lifetime of the certificate object. This means that
+   you can access these values multiple times without incurring additional overhead. Remember
+   that you can use the ``cripts::Net::IP`` class to convert the IP addresses into proper
+   IP address objects if needed.
+
+
+Odds are that you will want to use one of the specific array values, such as ``.san.uri``, which is
+easily done in a simple loop:
+
+.. code-block:: cpp
+
+   do_remap()
+   {
+     if (client.connection.IsTLS()) {
+       const auto tls = cripts::Certs::Server(client.connection);
+
+       for (auto uri : tls.san.uri) {
+         // Check the URI string_view
+       }
+     }
+   }
+
+
+You can of course loop over all SAN values, which is where the type of the value would come in handy,
+and why this is an array of tuples. In this scenario, you would iterate over the tuples like this:
+
+.. code-block:: cpp
+
+   do_remap()
+   {
+     if (client.connection.IsTLS()) {
+       const auto tls = cripts::Certs::Server(client.connection);
+
+       for (const [type, san] : tls.san) {
+         if (type == cripts::Certs::SAN::URI) {
+           // Check the URI string here
+         } else if (type == cripts::Certs::SAN::DNS) {
+           // Check the DNS string here
+         }
+       }
+     }
+   }
+
+In addition to traditional C++ iterators, you can also access SAN values by index. Make sure
+you check the size of the array first, as accessing an out-of-bounds index will give you an
+empty tuple. Prefer the iterator above, unless you know you want to access a specific element.
+
+Example of an alternative way to loop over all SAN values:
+
+.. code-block:: cpp
+
+   do_remap()
+   {
+     if (client.connection.IsTLS()) {
+       const auto tls = cripts::Certs::Server(client.connection);
+
+       size_t san_count = tls.san.size();
+
+       for (size_t i = 0; i < san_count; ++i) {
+         const auto [type, san] = tls.san[i];
+         // Process the type and san as needed
+       }
+     }
+   }

doc/developer-guide/cripts/cripts-connections.en.rst

@@ -71,6 +71,9 @@ Method                    Description
 ``LocalIP()``             The server (ATS) IP address of the connection.
 ``IsInternal()``          Returns ``true`` or ``false`` if the connection is internal to ATS.
 ``Socket()``              Returns the raw socket structure for the connection (use with care).
+``IsTLS()``               Returns ``true`` if the connection is a TLS connection.
+``ClientCert()``          Returns the client certificiate (mTLS) for the connection (if any).
+``ServerCert()``          Returns the server certificate for the connection, if it's a TLS connection.
 =======================   =========================================================================
 
 The ``IP()`` and ``LocalIP()`` methods return the IP address as an object. In addition to the
@@ -102,6 +105,7 @@ Variable                   Description
 ``pacing``                Configure socket pacing for the connection.
 ``dscp``                  Manage the DSCP value for the connection socket.
 ``mark``                  Manage the Mark value for the connection socket.
+``tls``                   Access to the TLS object for the connection.
 =======================   =========================================================================
 
 For other advanced features, a Cript has access to the socket file descriptor, via the ``FD()``
@@ -165,3 +169,24 @@ Method                    Description
 .. note::
    All methods return string values. These are methods and not fields, so they must be called as
    functions.
+
+.. _cripts-connections-tls:
+
+TLS
+===
+
+The ``tls`` variable provides access to the TLS object for the session. This object
+provides access to the TLS certificate and other TLS related information. The following methods
+are available:
+
+=======================   =========================================================================
+Method                    Description
+=======================   =========================================================================
+``Connection``            Returns the connection object for the TLS connection.
+``GetX509()``             Returns the X509 certificate for the connection, an OpenSSL object.
+=======================   =========================================================================
+
+Both of these can return a null pointer, if the connection is not a TLS connection or
+if the certificate is not available. The ``GetX509()`` method can take an optional
+boolean argument, which indicates if the certificate should be for a mutual TLS connection. The
+default is ``false``, which means that the server certificate for the connection will be returned.

doc/developer-guide/cripts/index.en.rst

@@ -31,8 +31,9 @@ Cripts
    cripts-urls.en
    cripts-headers.en
    cripts-connections.en
-   cripts-matcher.en
+   cripts-certs.en
    cripts-crypto.en
+   cripts-matcher.en
    cripts-misc.en
    cripts-bundles.en
    cripts-convenience.en