granicus.if.org Git - apache/blob - docs/manual/programs/ctlogconfig.xml

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision: $ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="ctlogconfig.xml.meta">
  24 <parentdocument href="./">Programs</parentdocument>
  25
  26 <title>ctlogconfig - Certificate Transparency log configuration tool</title>
  27
  28 <summary>
  29     <p><code>ctlogconfig</code> is a tool for maintaining a log configuration
  30     database, for use with <module>mod_ssl_ct</module>.</p>
  31
  32     <p>Refer first to <a href="../mod/mod_ssl_ct.html#logconf">Log
  33     configuration</a> in the <module>mod_ssl_ct</module> documentation.</p>
  34
  35     <p>Refer to the <a href="#examples">examples below</a> for typical use.</p>
  36
  37 </summary>
  38 <seealso><module>mod_ssl_ct</module></seealso>
  39
  40 <section id="synopsis">
  41   <title>Synopsis</title>
  42   <p><code>
  43     <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>dump</strong>
  44   </code></p>
  45
  46   <p><code>
  47     <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>configure-public-key</strong>
  48     [ <em>log-id</em>|<em>record-id</em> ]
  49     <em>/path/to/public-key.pem</em>
  50   </code></p>
  51
  52   <p><code>
  53     <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>configure-url</strong>
  54     [ <em>log-id</em>|<em>record-id</em> ]
  55     <em>log-URL</em>
  56   </code></p>
  57
  58   <p><code>
  59     <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>valid-time-range</strong>
  60     <em>log-id</em>|<em>record-id</em>
  61     <em>min-timestamp</em> <em>max-timestamp</em>
  62   </code></p>
  63
  64   <p><code>
  65     <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>trust</strong>
  66     <em>log-id</em>|<em>record-id</em>
  67   </code></p>
  68
  69   <p><code>
  70     <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>distrust</strong>
  71     <em>log-id</em>|<em>record-id</em>
  72   </code></p>
  73
  74   <p><code>
  75     <strong>ctlogconfig</strong> <em>/path/to/db</em> <strong>forget</strong>
  76     <em>log-id</em>|<em>record-id</em>
  77   </code></p>
  78
  79 </section>
  80
  81 <section id="subcommands">
  82   <title>Sub-commands</title>
  83   <dl>
  84     <dt>dump</dt>
  85     <dd>Display configuration database contents.  The record id shown in
  86     the output of this sub-command can be used to identify the affected
  87     record in other sub-commands.</dd>
  88
  89     <dt>configure-public-key</dt>
  90     <dd>Add a log's public key to the database or set the public key for an
  91     existing entry.  The log's public key is needed to validate the signature
  92     of SCTs received by a proxy from a backend server.</dd>
  93
  94     <dt>configure-url</dt>
  95     <dd>Add a log's URL to the database or set the URL for an existing entry.
  96     The log's URL is used when submitting server certificates to logs in
  97     order to obtain SCTs to send to clients.</dd>
  98
  99     <dt>valid-time-range</dt>
 100     <dd>Set the minimum valid time and/or the maximum valid time for a log.
 101     SCTs from the log with timestamps outside of the valid range will not be
 102     accepted.  Use <code>-</code> for a time that is not being configured.</dd>
 103
 104     <dt>trust</dt>
 105     <dd>Mark a log as trusted, which is the default setting.  This sub-command
 106     is used to reverse a <em>distrust</em> setting.</dd>
 107
 108     <dt>distrust</dt>
 109     <dd>Mark a log as distrusted.</dd>
 110
 111     <dt>forget</dt>
 112     <dd>Remove information about a log from the database.</dd>
 113   </dl>
 114 </section>
 115
 116 <section id="examples">
 117   <title>Examples</title>
 118
 119   <p>Consider an Apache httpd instance which serves as a TLS server and a proxy.
 120   The TLS server needs to obtain SCTs from a couple of known logs in order to
 121   pass those to clients, and the proxy needs to be able to validate the signature
 122   of SCTs received from backend servers.</p>
 123
 124   <p>First we'll configure the URLs for logs where server certificates are logged:</p>
 125
 126   <example>
 127     $ ctlogconfig /path/to/conf/log-config configure-url http://log1.example.com/<br />
 128     $ ctlogconfig /path/to/conf/log-config configure-url http://log2.example.com/<br />
 129     $ ctlogconfig /path/to/conf/log-config dump<br />
 130     Log entry:<br />
 131       Record 1<br />
 132       Log id         : (not configured)<br />
 133       Public key file: (not configured)<br />
 134       URL            : http://log1.example.com/<br />
 135       Time range     : -INF to +INF<br />
 136 <br />
 137     Log entry:<br />
 138       Record 2<br />
 139       Log id         : (not configured)<br />
 140       Public key file: (not configured)<br />
 141       URL            : http://log2.example.com/<br />
 142       Time range     : -INF to +INF<br />
 143   </example>
 144
 145   <p>Next we'll set the public key of a log where the certificate of our only
 146   backend server is published.  In this case it is the log with URL
 147   http://log2.example.com/ which has already been configured.</p>
 148
 149   <example>
 150     $ ctlogconfig /path/to/conf/log-config configure-public-key \\#2 /path/to/conf/log2-pub.pem<br />
 151     $ ctlogconfig /path/to/conf/log-config dump<br />
 152     Log entry:<br />
 153       Record 1<br />
 154       Log id         : (not configured)<br />
 155       Public key file: (not configured)<br />
 156       URL            : http://log1.example.com/<br />
 157       Time range     : -INF to +INF<br />
 158 <br />
 159     Log entry:<br />
 160       Record 2<br />
 161       Log id         : (not configured)<br />
 162       Public key file: /path/to/conf/log2-pub.pem<br />
 163       URL            : http://log2.example.com/<br />
 164       Time range     : -INF to +INF<br />
 165   </example>
 166 </section>
 167
 168 </manualpage>