1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
.. include:: ../../common.defs
.. _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 certificate. 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 |TS|. 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::
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
|
