Documentation for plugin certifier

doc/admin-guide/plugins/certifier.en.rst

@@ -0,0 +1,91 @@
+.. _admin-plugins-certifier:
+
+Certifier Plugin
+***************
+
+.. 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.
+
+Description
+===========
+
+The ``certifier`` performs two basic tasks:
+
+#. Load SSL certificates from file storage on demand. The total number of loaded certificates kept in memory can be configured.
+#. Generates SSL certificates on demand. Generated certificates will be written to file storage for later retrieval.
+
+Implementation
+==============
+Certificates management is done by `SslLRUList` (a Least-Recently-Used (LRU) list with a lookup map). The structure holding all info related to a given SNI is `SslData`. On lookup/insertion, the lookup map will be accessed and the corresponding `SslData` pointer will be moved to the head in the list. If on lookup/insertion the internal count exceeds the given limit on number of files, the tail node will be removed from both the list and the map.
+
+When the plugin sees an incoming HTTPS request, it does:
+
+#. Look up the SNI in `SslLRUList` and set up the context if a valid context exists. Otherwise, it will schedule a thread to retrieve such context from disk (or generate). If such a thread is already scheduled, it will put this SSL connection onto the queue.
+#. The retriever thread will first try to load the cert from disk. If no such certs exist and dynamic generation is enabled, the thread will generate a Certificate Signing Request (CSR) with provided SNI and sign it with root CA passed in from config options. The signed certificate is then written to the disk and all queued up SSL connections are set up with correct context and enabled.
+
+Setup
+=====
+* Cert and key:
+   For example, ``openssl req -newkey rsa:2048 -nodes -keyout ca.key -x509 -days 365 -out ca.cert``. Note that the cert/key should be generated without a challenge password.
+* Serial number:
+   A text file containing a valid integer with a trailing new line.
+
+Plugin Configuration
+====================
+.. program:: certifier.so
+* Specify certificate generation related files. If any of the following parameters is missing, the dynamic generation will be disabled.
+   .. option:: --sign-cert <path_to_certificate>
+   (`optional`, default:empty/unused) - specifies the path to the root CA certficate. In most cases, this would be a self-signed certificate that is configured to be trusted by all potential clients. Path should be the path and file name of the cert. If it is relative, it is relative to the Traffic Server configuration directory.
+
+   .. option:: --sign-key <path_to_key>
+   (`optional`, default:empty/unused) - specifies the path to the root CA private key. In most cases, this would be generated alongside the self-signed root CA certificate.
+
+   .. option:: --sign-serial <path_to_serial>
+   (`optional`, default:empty/unused) - specifies the path to the serial number file. This will be used to assign serial numbers to certificates and keep all generated ones in sync. Serial file should be a number with a trailing newline.
+* Specify the certificates management related settings.
+   .. option:: --store <path_to_certs_dir>
+   (`required`, default:empty) - specifies the directory to use as the root of file system certificates storage.
+
+   .. option:: --max <N>
+   (`required`, default:empty) - specifies the upper limit on number of files kept in memory.
+
+
+Example Usage
+=============
+To use this plugin, enable it in a :file:`plugin.config` rule, specifying certificates storage path, max number of certificates in memory, and signing cert+key+serial. For example:
+
+   certifier.so --store=/home/zeyuan/certifier/certs --max=1000 --sign-cert=/home/zeyuan/certifier/root-ca.crt --sign-key=/home/zeyuan/certifier/root-ca.key --sign-serial=/home/zeyuan/certifier/ca-serial.txt
+
+One use case would be routing incoming CONNECT request to another port on traffic server. With the certifier generating a trusted certificate, other plugins can act with a similar behavior to Man-In-The-Middle (logging interesting data for example).
+
+.. uml::
+   :align: center
+   actor "User"
+   participant "Traffic_Server"
+   participant "Origin_Server"
+   [User] -> [Traffic_Server]: CONNECT request
+   [Traffic_Server] -> [Traffic_Server]: Route CONNECT\nback to self
+   [User] -->> [Traffic_Server]: Client Hello
+   [Traffic_Server] -->> [User]: Server Hello with fake certs from certifier
+   [User] -->> [Traffic_Server]: ClientKeyExchange [ChangeCipherSpec]
+   [Traffic_Server] -->> [User]: ChangeCipherSpec
+   [User] <-> [Traffic_Server]: Tunnel established
+   [User] -> [Traffic_Server]: User request via tunnel
+   [Traffic_Server] -> [Origin_Server]: Request
+   [Origin_Server] --> [Traffic_Server]: Response
+   [Traffic_Server] --> [User]: TS response via tunnel
+@enduml

doc/admin-guide/plugins/index.en.rst

@@ -144,6 +144,7 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
    Access Control <access_control.en>
    Balancer <balancer.en>
    Buffer Upload <buffer_upload.en>
+   Certifier <certifier.en>
    Collapsed-Forwarding <collapsed_forwarding.en>
    GeoIP ACL <geoip_acl.en>
    FQ Pacing <fq_pacing.en>
@@ -172,6 +173,9 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
 :doc:`Buffer Upload <buffer_upload.en>`
    Buffers POST data before connecting to the Origin server.
 
+:doc:`Certifier <certifier.en>`
+   Manages and/or generates certificates for incoming HTTPS requests.
+
 :doc:`Collapsed-Forwarding <collapsed_forwarding.en>`
    Allows to Collapse multiple Concurrent requests by downloading once from the Origin and serving
    all clients in parallel.