[rs-commit] r86 - in /rs-manual/trunk/src/site: resources/images/mod_ca_disk-1.png resources/images/mod_ca_disk-2.png resources/images/mod_ca_disk-3.png xhtml5/mod/mod_ca_disk.xhtml5
rs-commit at redwax.eu
rs-commit at redwax.eu
Sat Oct 12 13:16:51 CEST 2019
Author: minfrin at redwax.eu
Date: Sat Oct 12 13:16:50 2019
New Revision: 86
Log:
Add reference docs for mod_ca_disk.
Added:
rs-manual/trunk/src/site/resources/images/mod_ca_disk-1.png (with props)
rs-manual/trunk/src/site/resources/images/mod_ca_disk-2.png (with props)
rs-manual/trunk/src/site/resources/images/mod_ca_disk-3.png (with props)
rs-manual/trunk/src/site/xhtml5/mod/mod_ca_disk.xhtml5
Added: rs-manual/trunk/src/site/resources/images/mod_ca_disk-1.png
==============================================================================
Binary file - no diff available.
Propchange: rs-manual/trunk/src/site/resources/images/mod_ca_disk-1.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: rs-manual/trunk/src/site/resources/images/mod_ca_disk-2.png
==============================================================================
Binary file - no diff available.
Propchange: rs-manual/trunk/src/site/resources/images/mod_ca_disk-2.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: rs-manual/trunk/src/site/resources/images/mod_ca_disk-3.png
==============================================================================
Binary file - no diff available.
Propchange: rs-manual/trunk/src/site/resources/images/mod_ca_disk-3.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: rs-manual/trunk/src/site/xhtml5/mod/mod_ca_disk.xhtml5
==============================================================================
--- rs-manual/trunk/src/site/xhtml5/mod/mod_ca_disk.xhtml5 (added)
+++ rs-manual/trunk/src/site/xhtml5/mod/mod_ca_disk.xhtml5 Sat Oct 12 13:16:50 2019
@@ -0,0 +1,700 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+ <head>
+ <title>mod_ca_disk Module</title>
+ <meta name="description" content="Read and write certificates, serial numbers and certificate sign requests from and to files on disk." />
+ <meta name="mod-ca-type" content="backend" />
+ </head>
+ <body>
+ <div class="index align-left">
+
+ <section class="wrapper style1 align-center"
+ id="introduction">
+ <div class="inner">
+ <h2>Disk Backend Module</h2>
+ <p>Read and write certificates, serial numbers and certificate sign requests from and to files on disk.</p>
+
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>What does it do?</h3>
+ </header>
+ <div class="content">
+
+ <p>
+ Based on the configuration of paths and files, this module
+ allows certificate sign requests to be saved to disk for later
+ processing, and certificates to be returned to clients that
+ ask for them.
+ </p>
+
+ <p>In addition, an OpenSSL compatible serial file
+ and index database can be used to generate serial numbers for
+ certificates and stored for later access in an index database.
+ </p>
+
+ <p>This module allows a typical disk based OpenSSL certificate
+ authority to be accessible over the web.
+ </p>
+
+ </div>
+ </section>
+
+
+ </div>
+ </div>
+ </section>
+
+
+
+ <section class="wrapper style1 align-center" id="integration">
+ <div class="inner">
+ <h2>Module Integration</h2>
+ <p>
+ The
+ <code>mod_ca_disk</code>
+ module is a
+ <a href="mod_ca.html#backend">backend module</a>
+ and will not do anything useful until
+ <code>mod_ca_disk</code>
+ has been combined with one or
+ more
+ <a href="mod_ca.html#frontend">frontend modules</a>
+ and optional <a href="mod_ca.html#backend">backend modules</a> listed below. The
+ <code>mod_ca_disk</code>
+ module provides the following hooks, and suitable
+ <a href="mod_ca.html#frontend">frontend modules</a>
+ must be configured to implement each protocol as needed.
+ </p>
+
+ <p>
+ All <a href="mod_ca.html#backend">backend modules</a> run within
+ a standard Apache httpd request, and standard httpd functionality
+ applies in all cases.
+ </p>
+
+ <div>
+ <img src="../images/mod_ca_disk-1.png" style="width: 100%;" />
+ </div>
+
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>
+ <a href="mod_ca.html#ca_sign">Sign Request Hook</a>
+ </h3>
+ </header>
+ <div class="content">
+ <p>When this hook is triggered, this module saves the certificate sign
+ request to disk ready for later processing. Protocols like SCEP provide
+ a mechanism to register the request for a certificate, and then return
+ the results when ready.</p>
+ <p>The <a href="#CADiskCertificateSignRequestPath">CADiskCertificateSignRequestPath</a>
+ directive enables the <a href="mod_ca.html#ca_sign">Sign Request Hook</a>
+ in <a href="mod_ca_disk.html">mod_ca_disk</a>.</p>
+ <table>
+ <tbody>
+ <tr>
+ <td>
+ <a href="mod_csr.html">mod_csr</a>
+ </td>
+ <td>Generate and issue certificates in response to an X509
+ certificate request.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="mod_pkcs12.html">mod_csr</a>
+ </td>
+ <td>Generate public/private key pairs and and issue certificates in response
+ to a application/x-www-form-urlencoded form request.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="mod_scep.html">mod_scep</a>
+ </td>
+ <td>Generate and issue certificates using the SCEP protocol.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="mod_spkac.html">mod_spkac</a>
+ </td>
+ <td>Generate and issue certificates using the SPKAC protocol.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>
+ <a href="mod_ca.html#ca_certstore">Certificate Storage Hook</a>
+ </h3>
+ </header>
+ <div class="content">
+ <p>When this hook is triggered, this module saves the newly generated
+ certificate to a directory.</p>
+ <p>Either the <a href="#CADiskCertificateBySerialPath">CADiskCertificateBySerialPath</a>
+ directive or the <a href="#CADiskCertificateByTransactionPath">CADiskCertificateByTransactionPath</a>
+ directive enables the <a href="mod_ca.html#ca_certstore">Certificate Storage Hook</a>
+ in <a href="mod_ca_disk.html">mod_ca_disk</a>.</p>
+ <table>
+ <tbody>
+ <tr>
+ <td>
+ <a href="mod_csr.html">mod_csr</a>
+ </td>
+ <td>Generate and issue certificates in response to an X509
+ certificate request.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="mod_pkcs12.html">mod_csr</a>
+ </td>
+ <td>Generate public/private key pairs and and issue certificates in response
+ to a application/x-www-form-urlencoded form request.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="mod_scep.html">mod_scep</a>
+ </td>
+ <td>Generate and issue certificates using the SCEP protocol.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="mod_spkac.html">mod_spkac</a>
+ </td>
+ <td>Generate and issue certificates using the SPKAC protocol.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </section>
+
+ </div>
+
+ <div>
+ <img src="../images/mod_ca_disk-2.png" style="width: 100%;" />
+ </div>
+
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>
+ <a href="mod_ca.html#ca_getcert">Get Certificate Hook</a>
+ </h3>
+ </header>
+ <div class="content">
+ <p>When this hook is triggered, certificates that were generated earlier
+ are returned from the specified directory.</p>
+ <p>This hook will trigger the
+ <a href="mod_ca.html#ca_getchain">Get Certificate Chain Hook</a> to add
+ a certificate chain to the given certificate.</p>
+ <p>Either the <a href="#CADiskCertificateBySerialPath">CADiskCertificateBySerialPath</a>
+ directive or the <a href="#CADiskCertificateByTransactionPath">CADiskCertificateByTransactionPath</a>
+ directive enables the <a href="mod_ca.html#ca_getcert">Get Certificate Hook</a>
+ in <a href="mod_ca_disk.html">mod_ca_disk</a>.</p>
+ <table>
+ <tbody>
+ <tr>
+ <td>
+ <a href="mod_scep.html">mod_scep</a>
+ </td>
+ <td>Generate and issue certificates using the SCEP protocol.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </section>
+
+ </div>
+
+ <div>
+ <img src="../images/mod_ca_disk-3.png" style="width: 100%;" />
+ </div>
+
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>
+ <a href="mod_ca.html#ca_makeserial">Make Serial Hook</a>
+ </h3>
+ </header>
+ <div class="content">
+ <p>When this hook is triggered, this module returns the next serial
+ number after the one stored in the current serial file. The serial
+ number can optionally be stored in an OpenSSL compatible database
+ index file.</p>
+ <p>The <a href="#CADiskSerialFile">CADiskSerialFile</a>
+ directive enables the <a href="mod_ca.html#ca_makeserial">Make Serial Hook</a>
+ in <a href="mod_ca_disk.html">mod_ca_disk</a>.</p>
+ <table>
+ <tbody>
+ <tr>
+ <td>
+ <a href="mod_ca_engine.html#ca_sign">mod_ca_engine</a>
+ </td>
+ <td>This hook signs a given certificate sign request using an
+ OpenSSL provided crypto engine such as a smartcard, using the
+ serial number returned by this module.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="mod_ca_simple.html#ca_sign">mod_ca_simple</a>
+ </td>
+ <td>This hook signs a given certificate sign request, using the
+ serial number returned by this module.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="mod_timestamp.html">mod_timestamp</a>
+ </td>
+ <td>Parse and return responses to RFC3161 Time Stamp Protocol requests.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </section>
+
+ </div>
+ </div>
+ </section>
+
+
+ <section class="wrapper style1 align-center"
+ id="directive-reference">
+ <div class="inner">
+ <h2>Examples</h2>
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>SCEP Example</h3>
+ </header>
+ <div class="content">
+ <p>Save incoming certificate sign requests to an incoming directory,
+ then serve the resulting certificates back when ready. In this example,
+ certificates are signed out of band.</p>
+<pre><code><![CDATA[
+# backend configuration:
+<IfModule mod_ca_disk.c>
+ CADiskCertificateSignRequestPath /etc/pki/CA/certs/
+ CADiskCertificateByTransactionPath /etc/pki/CA/certs/
+</IfModule>
+
+# frontend configuration:
+<IfModule mod_scep.c>
+ <Location /scep>
+ SetHandler scep
+ ScepSubjectRequest commonName
+ </Location>
+</IfModule>
+]]></code></pre>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>OpenSSL Serial / Index Example</h3>
+ </header>
+ <div class="content">
+ <p>In this example we generate serial numbers from the OpenSSL
+ serial file, and we keep track of certificates issued by writing
+ them to the OpenSSL index.</p>
+<pre><code><![CDATA[
+# backend configuration:
+<IfModule mod_ca_disk.c>
+ CADiskSerialFile /etc/pki/CA/serial
+ CADiskIndexFile /etc/pki/CA/index.txt
+ CADiskCertificateBySerialPath /etc/pki/CA/certs/
+</IfModule>
+<IfModule mod_ca_simple.c>
+ CASimpleTime on
+</IfModule>
+
+# frontend configuration:
+<IfModule mod_csr.c>
+ <Location /csr>
+ SetHandler csr
+ CsrSubjectRequest CN
+ </Location>
+</IfModule>
+]]></code></pre>
+ </div>
+ </section>
+
+ </div>
+ </div>
+ </section>
+
+
+ <section class="wrapper style1 align-center"
+ id="directive-reference">
+ <div class="inner">
+ <h2>Directive Reference</h2>
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>CADiskCertificateSignRequestPath Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Set to the path where certificate sign requests should be stored.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CADiskCertificateSignRequestPath path</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Default</td>
+ <td>
+ <code>none</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Context</td>
+ <td>server config, virtual host, directory, .htaccess</td>
+ </tr>
+ <tr>
+ <td>Status</td>
+ <td>
+ <a href="mod_ca.html#backend">Backend</a>
+ </td>
+ </tr>
+ <tr>
+ <td>Module</td>
+ <td>mod_ca_disk</td>
+ </tr>
+ <tr>
+ <td>Compatibility</td>
+ <td>Introduced in mod_ca 0.2.0 and works with Apache HTTP
+ Server 2.4.0 and later</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>Set to the path where certificate sign requests should be stored.</p>
+
+ <p>Incoming certificate sign requests will be written to the path
+ specified by this directive, for later processing. Each certificate
+ sign request is written to a file named after the transaction ID,
+ with the extension <code>csr</code>.</p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CADiskCertificateByTransactionPath Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Set to the path for certificates keyed by transaction, followed by optional suffix (defaults to 'cert').</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CADiskCertificateByTransactionPath path [suffix]</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Default</td>
+ <td>
+ <code>none</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Context</td>
+ <td>server config, virtual host, directory, .htaccess</td>
+ </tr>
+ <tr>
+ <td>Status</td>
+ <td>
+ <a href="mod_ca.html#backend">Backend</a>
+ </td>
+ </tr>
+ <tr>
+ <td>Module</td>
+ <td>mod_ca_disk</td>
+ </tr>
+ <tr>
+ <td>Compatibility</td>
+ <td>Introduced in mod_ca 0.2.0 and works with Apache HTTP
+ Server 2.4.0 and later</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>Set to the path for certificates keyed by transaction, followed by
+ optional suffix.</p>
+
+ <p>Signed certificates will be written to and stored at the path
+ specified by this directive, for record, or later retrieval.
+ Each certificate sign request is written to a file named after the
+ transaction ID, with the default extension <code>cert</code>. This
+ extension can be overridden.</p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CADiskCertificateBySerialPath Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Set to the path for certificates keyed by serial number, followed by optional suffix (defaults to 'pem').</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CADiskCertificateBySerialPath path [suffix]</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Default</td>
+ <td>
+ <code>none</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Context</td>
+ <td>server config, virtual host, directory, .htaccess</td>
+ </tr>
+ <tr>
+ <td>Status</td>
+ <td>
+ <a href="mod_ca.html#backend">Backend</a>
+ </td>
+ </tr>
+ <tr>
+ <td>Module</td>
+ <td>mod_ca_disk</td>
+ </tr>
+ <tr>
+ <td>Compatibility</td>
+ <td>Introduced in mod_ca 0.2.0 and works with Apache HTTP
+ Server 2.4.0 and later</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>Set to the path for certificates keyed by serial number,
+ followed by optional suffix.</p>
+
+ <p>Signed certificates will be written to and stored at the path
+ specified by this directive, for record, or later retrieval.
+ Each certificate sign request is written to a file named after the
+ certificate serial number, with the default extension <code>pem</code>.
+ This extension can be overridden.</p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CADiskSerialFile Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Set to the name of the serial file.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CADiskSerialFile file</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Default</td>
+ <td>
+ <code>none</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Context</td>
+ <td>server config, virtual host, directory, .htaccess</td>
+ </tr>
+ <tr>
+ <td>Status</td>
+ <td>
+ <a href="mod_ca.html#backend">Backend</a>
+ </td>
+ </tr>
+ <tr>
+ <td>Module</td>
+ <td>mod_ca_disk</td>
+ </tr>
+ <tr>
+ <td>Compatibility</td>
+ <td>Introduced in mod_ca 0.2.0 and works with Apache HTTP
+ Server 2.4.0 and later</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>Set to the name of a file containing the last used serial number.</p>
+
+ <p>If this directive is used, this module will increment and return the
+ serial number in the given file to the <code>ca_makeserial</code> hook.</p>
+
+ <p>The serial number file corresponds to and is designed to work with the
+ <code>serial</code> parameter in the <code>openssl.cnf</code> file in
+ OpenSSL.</p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CADiskIndexFile Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Set to the name of the database index file.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CADiskIndexFile file</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Default</td>
+ <td>
+ <code>none</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Context</td>
+ <td>server config, virtual host, directory, .htaccess</td>
+ </tr>
+ <tr>
+ <td>Status</td>
+ <td>
+ <a href="mod_ca.html#backend">Backend</a>
+ </td>
+ </tr>
+ <tr>
+ <td>Module</td>
+ <td>mod_ca_disk</td>
+ </tr>
+ <tr>
+ <td>Compatibility</td>
+ <td>Introduced in mod_ca 0.2.0 and works with Apache HTTP
+ Server 2.4.0 and later</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>Set to the name of a file containing the index database.</p>
+
+ <p>This directive requires the <code>CADiskSerialFile</code> directive
+ to be set for this directive to take effect.</p>
+
+ <p>If this directive is used, this module will add the serial number
+ and subject to the database file in the <code>ca_makeserial</code>
+ hook.</p>
+
+ <p>The database index file corresponds to and is designed to work with the
+ <code>database</code> parameter in the <code>openssl.cnf</code> file in
+ OpenSSL.</p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CADiskIndexUnique Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>If enabled, the certificate subject must be unique.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CADiskIndexUnique flag</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Default</td>
+ <td>
+ <code>CADiskIndexUnique false</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Context</td>
+ <td>server config, virtual host, directory, .htaccess</td>
+ </tr>
+ <tr>
+ <td>Status</td>
+ <td>
+ <a href="mod_ca.html#backend">Backend</a>
+ </td>
+ </tr>
+ <tr>
+ <td>Module</td>
+ <td>mod_ca_disk</td>
+ </tr>
+ <tr>
+ <td>Compatibility</td>
+ <td>Introduced in mod_ca 0.2.0 and works with Apache HTTP
+ Server 2.4.0 and later</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>If enabled, the certificate subject must be unique.</p>
+
+ <p>This directive requires the <code>CADiskSerialFile</code> and
+ <code>CADiskIndexFile</code> directives to be set for this directive
+ to take effect.</p>
+
+ <p>If this directive is used, the serial number
+ and subject being added to the database file in the <code>ca_makeserial</code>
+ hook will fail if the serial number has been used before.</p>
+
+ </div>
+ </section>
+
+ </div>
+ </div>
+ </section>
+
+ </div>
+ </body>
+</html>
+
More information about the rs-commit
mailing list