Traffic Dump: dump server-side protocol stack (apache#6972)

This also adds some TLS information in the protocol stack, such as the
verify_mode applied to the SSL session and whether the server requested
a client certificate.

Co-authored-by: bneradt <bneradt@verizonmedia.com>

doc/developer-guide/api/functions/TSClientProtocolStack.en.rst

@@ -31,10 +31,14 @@ Synopsis
 
 .. function:: TSReturnCode TSHttpTxnClientProtocolStackGet(TSHttpTxn txnp, int n, char const** result, int* actual)
 
+.. function:: TSReturnCode TSHttpTxnServerProtocolStackGet(TSHttpTxn txnp, int n, const char** result, int* actual)
+
 .. function:: TSReturnCode TSHttpSsnClientProtocolStackGet(TSHttpSsn ssnp, int n, char const** result, int* actual)
 
 .. function:: char const* TSHttpTxnClientProtocolStackContains(TSHttpTxn txnp)
 
+.. function:: const char* TSHttpTxnServerProtocolStackContains(TSHttpTxn txnp, char const* tag)
+
 .. function:: char const* TSHttpSsnClientProtocolStackContains(TSHttpSsn ssnp)
 
 .. function:: char const* TSNormalizedProtocolTag(char const* tag)
@@ -44,12 +48,15 @@ Synopsis
 Description
 ===========
 
-These functions are used to explore the protocol stack of the client (user agent) connection to
+These functions are used to explore the protocol stack of either the client (user agent) or origin server connection to
 |TS|. The functions :func:`TSHttpTxnClientProtocolStackGet` and
 :func:`TSHttpSsnClientProtocolStackGet` can be used to retrieve the entire protocol stack for the
-user agent connection. :func:`TSHttpTxnClientProtocolStackContains` and
-:func:`TSHttpSsnClientProtocolStackContains` will check for a specific protocol :arg:`tag` being
-present in the stack.
+user agent connection. The :func:`TSHttpTxnServerProtocolStackGet` can be used
+to retrieve the entire protocol stack for
+the origin server connection. :func:`TSHttpTxnClientProtocolStackContains`,
+:func:`TSHttpSsnClientProtocolStackContains`, and
+:func:`TSHttpTxnServerProtocolStackContains`  will check for a specific
+protocol :arg:`tag` being present in the stack.
 
 Each protocol is represented by tag which is a null terminated string. A particular tag will always
 be returned as the same character pointer and so protocols can be reliably checked with pointer
@@ -60,18 +67,18 @@ normalized value. This is useful for plugins that provide custom protocols for u
 
 The protocols are ordered from higher level protocols to the lower level ones on which the higher
 operate. For instance a stack might look like "http/1.1,tls/1.2,tcp,ipv4". For
-:func:`TSHttpTxnClientProtocolStackGet` and :func:`TSHttpSsnClientProtocolStackGet` these values
+:func:`TSHttpTxnClientProtocolStackGet`, :func:`TSHttpSsnClientProtocolStackGet`, and :func:`TSHttpTxnServerProtocolStackGet` these values
 are placed in the array :arg:`result`. :arg:`count` is the maximum number of elements of
 :arg:`result` that may be modified by the function call. If :arg:`actual` is not :const:`NULL` then
 the actual number of elements in the protocol stack will be returned. If this is equal or less than
 :arg:`count` then all elements were returned. If it is larger then some layers were omitted from
 :arg:`result`. If the full stack is required :arg:`actual` can be used to resize :arg:`result` to
 be sufficient to hold all of the elements and the function called again with updated :arg:`count`
-and :arg:`result`. In practice the maximum number of elements will is almost certain to be less
+and :arg:`result`. In practice the maximum number of elements is almost certain to be less
 than 10 which therefore should suffice. These functions return :const:`TS_SUCCESS` on success and
 :const:`TS_ERROR` on failure which should only occurr if :arg:`txnp` or :arg:`ssnp` are invalid.
 
-The :func:`TSHttpTxnClientProtocolStackContains` and :func:`TSHttpSsnClientProtocolStackContains`
+The :func:`TSHttpTxnClientProtocolStackContains`, :func:`TSHttpSsnClientProtocolStackContains`, and :func:`TSHttpTxnServerProtocolStackContains`
 functions are provided for the convenience when only the presence of a protocol is of interest, not
 its location or the presence of other protocols. These functions return :const:`NULL` if the protocol
 :arg:`tag` is not present, and a pointer to the normalized tag if it is present. The strings are

doc/developer-guide/api/functions/TSVConn.en.rst

@@ -21,7 +21,7 @@
 TSVConn
 *******
 
-Traffic Server APIs to get :type:`TSVConn` from :type:`TSHttpSsn` object
+Traffic Server APIs to get :type:`TSVConn` from :type:`TSHttpSsn` or :type:`TSHttpTxn` object.
 
 Synopsis
 ========
@@ -32,11 +32,13 @@ Synopsis
 
 .. function:: TSVConn TSHttpSsnClientVConnGet(TSHttpSsn ssnp)
 .. function:: TSVConn TSHttpSsnServerVConnGet(TSHttpSsn ssnp)
+.. function:: TSVConn TSHttpTxnServerVConnGet(TSHttpTxn txnp)
 
 Description
 ===========
 
-These APIs allow the developer to get the NetVconnection (represented by :type:`TSVConn`) from the Http session (:type:`TSHttpSsn`) object.
+These APIs allow the developer to get the NetVconnection (represented by :type:`TSVConn`) from the Http session (:type:`TSHttpSsn`) or transaction (:type:`TSHttpTxn`) object.
 
 :func:`TSHttpSsnClientVConnGet` returns the :type:`TSVConn` associated with the client side :type:`TSHttpSsn` object.
 :func:`TSHttpSsnServerVConnGet` returns the same associated with the server side :type:`TSHttpSsn`.
+:func:`TSHttpTxnServerVConnGet` returns the same associated with a :type:`TSHttpTxn`.

doc/developer-guide/api/functions/TSVConnProvidedSslCert.en.rst

@@ -0,0 +1,38 @@
+.. 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
+
+.. default-domain:: c
+
+TSVConnProvidedSslCert
+********************************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: int TSVConnProvidedSslCert(TSVConn svc)
+
+Description
+===========
+
+Determines whether the connection associated with :arg:`svc` was an SSL
+connection on which a server certificate was provided in the SSL handshake.
+Returns :literal:`1` if it was and :literal:`0` otherwise.

include/ts/ts.h

@@ -1216,9 +1216,11 @@ tsapi void TSHttpHookAdd(TSHttpHookID id, TSCont contp);
 tsapi void TSHttpSsnHookAdd(TSHttpSsn ssnp, TSHttpHookID id, TSCont contp);
 tsapi void TSHttpSsnReenable(TSHttpSsn ssnp, TSEvent event);
 tsapi int TSHttpSsnTransactionCount(TSHttpSsn ssnp);
-/* get TSVConn from session */
+/* Get the TSVConn from a session. */
 tsapi TSVConn TSHttpSsnClientVConnGet(TSHttpSsn ssnp);
 tsapi TSVConn TSHttpSsnServerVConnGet(TSHttpSsn ssnp);
+/* Get the TSVConn from a transaction. */
+tsapi TSVConn TSHttpTxnServerVConnGet(TSHttpTxn txnp);
 
 /* --------------------------------------------------------------------------
    SSL connections */
@@ -1258,6 +1260,10 @@ TSReturnCode TSVConnProtocolEnable(TSVConn connp, const char *protocol_name);
 
 /*  Returns 1 if the sslp argument refers to a SSL connection */
 tsapi int TSVConnIsSsl(TSVConn sslp);
+/* Returns 1 if a certificate was provided in the TLS handshake, 0 otherwise.
+ */
+tsapi int TSVConnProvidedSslCert(TSVConn sslp);
+
 tsapi TSSslSession TSSslSessionGet(const TSSslSessionID *session_id);
 tsapi int TSSslSessionGetBuffer(const TSSslSessionID *session_id, char *buffer, int *len_ptr);
 tsapi TSReturnCode TSSslSessionInsert(const TSSslSessionID *session_id, TSSslSession add_session, TSSslConnection ssl_conn);
@@ -2512,7 +2518,7 @@ tsapi TSUuid TSProcessUuidGet(void);
 tsapi const char *TSHttpTxnPluginTagGet(TSHttpTxn txnp);
 
 /*
- * Return information about the client protocols
+ * Return information about the client protocols.
  */
 tsapi TSReturnCode TSHttpTxnClientProtocolStackGet(TSHttpTxn txnp, int n, const char **result, int *actual);
 tsapi TSReturnCode TSHttpSsnClientProtocolStackGet(TSHttpSsn ssnp, int n, const char **result, int *actual);
@@ -2521,6 +2527,12 @@ tsapi const char *TSHttpSsnClientProtocolStackContains(TSHttpSsn ssnp, char cons
 tsapi const char *TSNormalizedProtocolTag(char const *tag);
 tsapi const char *TSRegisterProtocolTag(char const *tag);
 
+/*
+ * Return information about the server protocols.
+ */
+tsapi TSReturnCode TSHttpTxnServerProtocolStackGet(TSHttpTxn txnp, int n, const char **result, int *actual);
+tsapi const char *TSHttpTxnServerProtocolStackContains(TSHttpTxn txnp, char const *tag);
+
 // If, for the given transaction, the URL has been remapped, this function puts the memory location of the "from" URL object in
 // the variable pointed to by urlLocp, and returns TS_SUCCESS.  (The URL object will be within memory allocated to the
 // transaction object.)  Otherwise, the function returns TS_ERROR.

include/tscore/ink_inet.h

@@ -45,7 +45,18 @@ IN6_IS_ADDR_UNSPECIFIED(in6_addr const *addr)
 }
 #endif
 
-// IP protocol stack tags.
+/*
+ * IP protocol stack tags.
+ *
+ * When adding support for an additional protocol, the following minimum steps
+ * should be done:
+ *
+ * 1. This set of string_views should be updated with the new tag.
+ * 2. A populate_protocol function overload should be implemented for the
+ *    appropriate VConnection or ProxySession virtual function.
+ * 3. Traffic Dump should be updated to handle the new tag in:
+ *    plugins/experimental/traffic_dump/session_data.cc
+ */
 extern const std::string_view IP_PROTO_TAG_IPV4;
 extern const std::string_view IP_PROTO_TAG_IPV6;
 extern const std::string_view IP_PROTO_TAG_UDP;