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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
<!--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>mod_ssl_ct - Apache HTTP Server Version 2.5</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
<script src="../style/scripts/prettify.min.js" type="text/javascript">
</script>
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body>
<div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
<p class="apache">Apache HTTP Server Version 2.5</p>
<img alt="" src="../images/feather.png" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<div id="path">
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_ssl_ct</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/mod/mod_ssl_ct.html" title="English"> en </a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Implementation of Certificate Transparency (RFC 6962)
</td></tr>
<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>ssl_ct_module</td></tr>
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_ssl_ct.c</td></tr></table>
<h3>Summary</h3>
<p>This module provides an implementation of Certificate Transparency, in
conjunction with <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> and command-line tools from the
<a href="https://code.google.com/p/certificate-transparency/">certificate-transparency</a>
open source project. The goal of Certificate Transparency is to expose the
use of server certificates which are trusted by browsers but were mistakenly
or maliciously issued. More information about Certificate Transparency is
available at <a href="http://www.certificate-transparency.org/">
http://www.certificate-transparency.org/</a>. Key terminology used in
this documentation:</p>
<dl>
<dt>Certificate log</dt>
<dd>A certificate log, referred to simply as <q>log</q> in this documentation,
is a network service to which server certificates have been submitted. A
user agent can confirm that the certificate of a server which it accesses
has been submitted to a log which it trusts, and that the log itself has
not been tampered with.</dd>
<dt>Signed Certificate Timestamp (SCT)</dt>
<dd>This is an acknowledgement from a log that it has accepted a valid
certificate. It is signed with the log's public key. One or more SCTs
is passed to clients during the handshake, either in the ServerHello
(TLS extension), certificate extension, or in a stapled OCSP response.</dd>
</dl>
<p>This implementation for Apache httpd provides these features for TLS
servers and proxies:</p>
<ul>
<li>Signed Certificate Timestamps (SCTs) can be obtained from logs
automatically and, in conjunction with any statically configured SCTs, sent
to aware clients in the ServerHello (during the handshake).</li>
<li>SCTs can be received by the proxy from origin servers in the ServerHello,
in a certificate extension, and/or within stapled OCSP responses; any SCTs
received can be partially validated on-line and optionally queued for off-line
audit.</li>
<li>The proxy can be configured to disallow communication with an origin
server which does not provide an SCT which passes on-line validation.</li>
</ul>
<p>Configuration information about logs can be defined statically in the web
server configuration or maintained in a SQLite3 database. In the latter case,
<code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> will reload the database periodically, so any
site-specific infrastructure for maintaining and propagating log configuration
information does not have to also restart httpd to make it take effect.</p>
<div class="note">This module is experimental for the following reasons:
<ul>
<li>Insufficient test and review</li>
<li>Reliance on an unreleased version of OpenSSL (1.0.2, Beta 3 or later) for
basic operation</li>
<li>Incomplete <a href="#audit">off-line audit capability</a></li>
</ul>
<p>Configuration mechanisms, format of data saved for off-line audit, and
other characteristics are subject to change based on further feedback and
testing.</p>
</div>
</div>
<div id="quickview"><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#server">Server processing overview</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#proxy">Proxy processing overview</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#logconf">Log configuration</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#static">Storing SCTs in a form consumable by mod_ssl_ct</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging CT status in the access log</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#audit">Off-line audit for proxy</a></li>
</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#ctauditstorage">CTAuditStorage</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctlogclient">CTLogClient</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctlogconfigdb">CTLogConfigDB</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctmaxsctage">CTMaxSCTAge</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctproxyawareness">CTProxyAwareness</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctsctstorage">CTSCTStorage</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctserverhellosctlimit">CTServerHelloSCTLimit</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctstaticlogconfig">CTStaticLogConfig</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#ctstaticscts">CTStaticSCTs</a></li>
</ul>
<ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="server" id="server">Server processing overview</a></h2>
<p>Servers need to send SCTs to their clients. SCTs in a certificate
extension or stapled OCSP response will be sent without any special program
logic. This module handles sending SCTs configured by the administrator or
received from configured logs.</p>
<p>The number of SCTs sent in the ServerHello (i.e., not including those in a
certificate extension or stapled OCSP response) can be limited by the
<code class="directive"><a href="#ctserverhellosctlimit">CTServerHelloSCTLimit</a></code>
directive.</p>
<p>For each server certificate, a daemon process maintains an SCT list to be
sent in the ServerHello, created from statically configured SCTs as well as
those received from logs. Logs marked as untrusted or with a maximum valid
timestamp before the present time will be ignored. Periodically the daemon
will submit certificates to a log as necessary (due to changed log
configuration or age) and rebuild the concatenation of SCTs.</p>
<p>The SCT list for a server certificate will be sent to any client that
indicates awareness in the ClientHello when that particular server certificate
is used.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="proxy" id="proxy">Proxy processing overview</a></h2>
<p>The proxy indicates Certificate Transparency awareness in the ClientHello
by including the <em>signed_certificate_timestamp</em> extension. It can
recognize SCTs received in the ServerHello, in an extension in the certificate
for an origin server, or in a stapled OCSP response.</p>
<p>On-line verification is attempted for each received SCT:</p>
<ul>
<li>For any SCT, the timestamp can be checked to see if it is not yet valid
based on the current time as well as any configured valid time interval for
the log.</li>
<li>For an SCT from a log for which a public key is configured, the server
signature will be checked.</li>
</ul>
<p>If verification fails for at least one SCT and verification was not
successful for at least one SCT, the connection is aborted if
<code class="directive"><a href="#ctproxyawareness">CTProxyAwareness</a></code> is set to
<em>require</em>.</p>
<p>Additionally, the server certificate chain and SCTs are stored for off-line
verification if the <code class="directive"><a href="#ctauditstorage">CTAuditStorage</a></code>
directive is configured.</p>
<p>As an optimization, on-line verification and storing of data from the
server is only performed the first time a web server child process receives
the data. This saves some processing time as well as disk space. For typical
reverse proxy setups, very little processing overhead will be required.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="logconf" id="logconf">Log configuration</a></h2>
<p>Servers and proxies use different information about logs for their processing.
This <em>log configuration</em> can be set in two ways:</p>
<ul>
<li>Create a log configuration database using <code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code>,
and configure the path to that database using the <code class="directive"><a href="#ctlogconfig">
CTLogConfig</a></code> directive. This method of configuration supports
dynamic updates; <code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> will re-read the database at
intervals. Additionally, the off-line audit program <code>ctauditscts</code>
can use this configuration to find the URL of logs.</li>
<li>Configure information about logs statically using the <code class="directive"><a href="#ctstaticlogconfig">CTStaticLogConfig</a></code> directive. As with all other
directives, the server must be restarted in order to pick up changes to the
directives.</li>
</ul>
<p>The information that can be configured about a log using either mechanism is
described below:</p>
<dl>
<dt>log id</dt>
<dd>The log id is the SHA-256 hash of the log's public key, and is part of
every SCT. This is a convenient way to identify a particular log when
configuring valid timestamp ranges or certain other information.</dd>
<dt>public key of the log</dt>
<dd>A proxy must have the public key of the log in order to check the
signature in SCTs it receives which were obtained from the log.
<br />
A server must have the public key of the log in order to submit certificates
to it.</dd>
<dt>general trust/distrust setting</dt>
<dd>This is a mechanism to distrust or restore trust in a particular log,
for whatever reason (including simply avoiding interaction with the
log in situations where it is off-line).</dd>
<dt>minimum and/or maximum valid timestamps</dt>
<dd>When configured, the proxy will check that timestamps from SCTs
are within the valid range.</dd>
<dt>log URL</dt>
<dd>The URL of the log (for its API) is required by a server in order to
submit server certificates to the log. The server will submit
each server certificate in order to obtain an SCT for each log with a
configured URL, except when the log is also marked as distrusted or the
current time is not within any configured valid timestamp range.
<br />
The log URL is also needed by off-line auditing of SCTs received by a
proxy.</dd>
</dl>
<p>Generally, only a small subset of this information is configured for a
particular log. Refer to the documentation for the <code class="directive"><a href="#ctstaticlogconfig">CTStaticLogConfig</a></code> directive and the
<code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code> command for more specific information.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="static" id="static">Storing SCTs in a form consumable by mod_ssl_ct</a></h2>
<p><code class="module"><a href="../mod/mod_ssl_ct.html">mod_ssl_ct</a></code> allows you to configure SCTs statically
using the <code class="directive">CTStaticSCTs</code> directive. These must be
in binary form, ready to send to a client.</p>
<p>Sample code in the form of a Python script to build an SCT in the correct
format from data received from a log can be found in
<a href="https://github.com/tomrittervg/ct-tools">Tom Ritter's ct-tools
repository</a>. Refer to <code>write-sct.py</code></p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="logging" id="logging">Logging CT status in the access log</a></h2>
<p>Proxy and server modes set the <code>SSL_CT_PROXY_STATUS</code> and
<code>SSL_CT_CLIENT_STATUS</code> variables, respectively, to indicate
if the corresponding peer is CT-aware.</p>
<p>Proxy mode sets the <code>SSL_CT_PROXY_SCT_SOURCES</code> variable to
indicate whether and where SCTs were obtained (ServerHello, certificate
extension, etc.).</p>
<p>These variables can be logged with the <code>%{<em>varname</em>}e</code>
format of <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="audit" id="audit">Off-line audit for proxy</a></h2>
<p>Experimental support for this is implemented in the <code>ctauditscts</code>
command, which itself relies on the <code>verify_single_proof.py</code> tool in the
<em>certificate-transparency</em> open source project. <code>ctauditscts</code>
can parse data for off-line audit (enabled with the <code class="directive"><a href="#ctauditstorage">
CTAuditStorage</a></code> directive) and invoke <code>verify_single_proof.py</code>.
</p>
<p>Here are rough notes for using <code>ctauditscts</code>:</p>
<ul>
<li>Create a <em>virtualenv</em> using the <code>requirements.txt</code> file
from the <em>certificate-transparency</em> project and run the following steps
with that <em>virtualenv</em> activated.</li>
<li>Set <code>PYTHONPATH</code> to include the <code>python</code>
directory within the <em>certificate-transparency</em> tools.</li>
<li>Set <code>PATH</code> to include the <code>python/ct/client/tools</code>
directory.</li>
<li>Run <code>ctauditscts</code>, passing the value of the
<code class="directive">CTAuditStorage</code> directive and, optionally, the path to
the log configuration database. The latter will be used to look up log URLs
by log id.</li>
</ul>
<p>The data saved for audit can also be used by other programs; refer to the
<code>ctauditscts</code> source code for details on processing the data.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTAuditStorage" id="CTAuditStorage">CTAuditStorage</a> <a name="ctauditstorage" id="ctauditstorage">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Existing directory where data for off-line audit will be stored</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTAuditStorage <em>directory</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p>The <code class="directive">CTAuditStorage</code> directive sets the name of a
directory where data will be stored for off-line audit. If <em>directory</em>
is not absolute then it is assumed to be relative to <code class="directive"><a href="../mod/core.html#defaultruntimedir">
DefaultRuntimeDir</a></code>.</p>
<p>If this directive is not specified, data will not be stored for off-line
audit.</p>
<p>The directory will contain files named <code><em>PID</em>.tmp</code> for
active child processes and files named <code><em>PID</em>.out</code> for exited
child processes. These <code>.out</code> files are ready for off-line audit.
The experimental command <code>ctauditscts</code> (in the httpd source tree, not
currently installed) interfaces with <em>certificate-transparency</em> tools to
perform the audit.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTLogClient" id="CTLogClient">CTLogClient</a> <a name="ctlogclient" id="ctlogclient">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Location of certificate-transparency log client tool</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTLogClient <em>executable</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p><em>executable</em> is the full path to the log client tool, which is
normally file <code>cpp/client/ct</code> (or <code>ct.exe</code>) within the
source tree of the
<a href="https://code.google.com/p/certificate-transparency/">
certificate-transparency</a> open source project.</p>
<p>An alternative implementation could be used to retrieve SCTs for a
server certificate as long as the command-line interface is equivalent.</p>
<p>If this directive is not configured, server certificates cannot be
submitted to logs in order to obtain SCTs; thus, only admin-managed
SCTs or SCTs in certificate extensions will be provided to clients.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTLogConfigDB" id="CTLogConfigDB">CTLogConfigDB</a> <a name="ctlogconfigdb" id="ctlogconfigdb">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Log configuration database supporting dynamic updates</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTLogConfigDB <em>filename</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p>The <code class="directive">CTLogConfigDB</code> directive sets the name of a database
containing configuration about known logs. If <em>filename</em> is not absolute
then it is assumed to be relative to
<code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
<p>Refer to the documentation for the <code class="program"><a href="../programs/ctlogconfig.html">ctlogconfig</a></code> program,
which manages the database.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTMaxSCTAge" id="CTMaxSCTAge">CTMaxSCTAge</a> <a name="ctmaxsctage" id="ctmaxsctage">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum age of SCT obtained from a log, before it will be
refreshed</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTMaxSCTAge <em>num-seconds</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>1 day</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p>Server certificates with SCTs which are older than this maximum age will
be resubmitted to configured logs. Generally the log will return the same SCT
as before, but that is subject to log operation. SCTs will be refreshed as
necessary during normal server operation, with new SCTs returned to clients
as they become available.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTProxyAwareness" id="CTProxyAwareness">CTProxyAwareness</a> <a name="ctproxyawareness" id="ctproxyawareness">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Level of CT awareness and enforcement for a proxy
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTProxyAwareness <em>oblivious|aware|require</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>aware</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p>This directive controls awareness and checks for valid SCTs for a
proxy. Several options are available:</p>
<dl>
<dt>oblivious</dt>
<dd>The proxy will neither ask for nor examine SCTs. Certificate
Transparency processing for the proxy is completely disabled.</dd>
<dt>aware</dt>
<dd>The proxy will perform all appropriate Certificate Transparency
processing, such as asking for and examining SCTs. However, the
proxy will not disallow communication if the origin server does
not provide any valid SCTs.</dd>
<dt>require</dt>
<dd>The proxy will abort communication with the origin server if it
does not provide at least one SCT which passes on-line validation.</dd>
</dl>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTSCTStorage" id="CTSCTStorage">CTSCTStorage</a> <a name="ctsctstorage" id="ctsctstorage">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Existing directory where SCTs are managed</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTSCTStorage <em>directory</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p>The <code class="directive">CTSCTStorage</code> directive sets the name of a
directory where SCTs and SCT lists will be stored. If <em>directory</em>
is not absolute then it is assumed to be relative to <code class="directive"><a href="../mod/core.html#defaultruntimedir">
DefaultRuntimeDir</a></code>.</p>
<p>A subdirectory for each server certificate contains information relative
to that certificate; the name of the subdirectory is the SHA-256 hash of the
certificate.</p>
<p>The certificate-specific directory contains SCTs retrieved from configured
logs, SCT lists prepared from statically configured SCTs and retrieved SCTs,
and other information used for managing SCTs.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTServerHelloSCTLimit" id="CTServerHelloSCTLimit">CTServerHelloSCTLimit</a> <a name="ctserverhellosctlimit" id="ctserverhellosctlimit">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Limit on number of SCTs that can be returned in
ServerHello</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTServerHelloSCTLimit <em>limit</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>100</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p>This directive can be used to limit the number of SCTs which can be
returned by a TLS server in ServerHello, in case the number of configured
logs and statically-defined SCTs is relatively high.</p>
<p>Typically only a few SCTs would be available, so this directive is only
needed in special circumstances.</p>
<p>The directive does not take into account SCTs which may be provided in
certificate extensions or in stapled OCSP responses.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTStaticLogConfig" id="CTStaticLogConfig">CTStaticLogConfig</a> <a name="ctstaticlogconfig" id="ctstaticlogconfig">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Static configuration of information about a log</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTStaticLogConfig <em>log-id|-</em> <em>public-key-file|-</em>
<em>1|0|-</em> <em>min-timestamp|-</em> <em>max-timestamp|-</em>
<em>log-URL|-</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p>This directive is used to configure information about a particular log.
This directive is appropriate when configuration information changes rarely.
If dynamic configuration updates must be supported, refer to the
<code class="directive"><a href="#ctlogconfigdb">CTLogConfigDB</a></code> directive.</p>
<p>Each of the six fields must be specified, but usually only a small
amount of information must be configured for each log; use <em>-</em> when no
information is available for the field. For example, in support of a
server-only configuration (i.e., no proxy), the administrator might
configure only the log URL to be used when submitting server certificates
and obtaining a Signed Certificate Timestamp.</p>
<p>The fields are defined as follows:</p>
<dl>
<dt><em>log-id</em></dt>
<dd>This is the id of the log, which is the SHA-256 hash of the log's
public key, provided in hexadecimal format. This string is 64 characters
in length.
<br />
This field should be omitted when <em>public-key-file</em> is provided.</dd>
<dt><em>public-key-file</em></dt>
<dd>This is the name of a file containing the PEM encoding of the log's
public key. If the name is not absolute, then it is assumed to be relative
to <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</dd>
<dt><em>trust/distrust</em></dt>
<dd>Set this field to <em>1</em> to distrust this log, or to otherwise avoid
using it for server certificate submission. Set this to <em>-</em> or
<em>0</em> (the default) to treat the log normally.</dd>
<dt><em>min-timestamp</em> and <em>max-timestamp</em></dt>
<dd>A timestamp is a time as expressed in the number of milliseconds since the
epoch, ignoring leap seconds. This is the form of time used in Signed Certificate
Timestamps. This must be provided as a decimal number.
<br />
Specify <strong><code>-</code></strong> for one of the timestamps if it is unknown.
For example, when configuring the minimum valid timestamp for a log which remains
valid, specify <strong><code>-</code></strong> for <em>max-timestamp</em>.
<br />
SCTs received from this log by the proxy are invalid if the timestamp
is older than <em>min-timestamp</em> or newer than <em>max-timestamp</em>.</dd>
<dt><em>log-URL</em></dt>
<dd>This is the URL of the log, for use in submitting server certificates
and in turn obtaining an SCT to be sent to clients.</dd>
</dl>
<h3>See also</h3>
<ul>
<li><a href="#logconf">Log configuration</a> contains more general information
about the fields which can be configured with this directive.</li>
</ul>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CTStaticSCTs" id="CTStaticSCTs">CTStaticSCTs</a> <a name="ctstaticscts" id="ctstaticscts">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Static configuration of one or more SCTs for a server certificate
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CTStaticSCTs <em>certificate-pem-file</em> <em>sct-directory</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl_ct</td></tr>
</table>
<p>This directive is used to statically define one or more SCTs corresponding
to a server certificate. This mechanism can be used instead of or in
addition to dynamically obtaining SCTs from configured logs. Any changes to
the set of SCTs for a particular server certificate will be adopted dynamically
without the need to restart the server.</p>
<p><em>certificate-pem-file</em> refers to the server certificate in PEM
format. If the name is not absolute, then it is assumed to be relative to
<code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
<p><em>sct-directory</em> should contain one or more files with extension
<code>.sct</code>, representing one or more SCTs corresponding to the
server certificate. If <em>sct-directory</em> is not absolute, then it is
assumed to be relative to <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>.</p>
<p>If <em>sct-directory</em> is empty, no error will be raised.</p>
<p>This directive could be used to identify directories of SCTs maintained by
other infrastructure, provided that they are saved in binary format with
file extension <em>.sct</em></p>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_ssl_ct.html" title="English"> en </a></p>
</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
<script type="text/javascript"><!--//--><![CDATA[//><!--
var comments_shortname = 'httpd';
var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html';
(function(w, d) {
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
}
else {
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
}
})(window, document);
//--><!]]></script></div><div id="footer">
<p class="apache">Copyright 2016 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
if (typeof(prettyPrint) !== 'undefined') {
prettyPrint();
}
//--><!]]></script>
</body></html>
|
