[rs-commit] r91 - in /rs-manual/trunk/src: main/modules.xml site/resources/images/mod_ca_engine-1.png site/resources/images/mod_ca_engine-2.png site/xhtml5/mod/mod_ca_engine.xhtml5
rs-commit at redwax.eu
rs-commit at redwax.eu
Thu Oct 17 14:28:16 CEST 2019
Author: minfrin at redwax.eu
Date: Thu Oct 17 14:28:15 2019
New Revision: 91
Log:
Add cocs for mod_ca_engine.
Added:
rs-manual/trunk/src/site/resources/images/mod_ca_engine-1.png (with props)
rs-manual/trunk/src/site/resources/images/mod_ca_engine-2.png (with props)
rs-manual/trunk/src/site/xhtml5/mod/mod_ca_engine.xhtml5
Modified:
rs-manual/trunk/src/main/modules.xml
Modified: rs-manual/trunk/src/main/modules.xml
==============================================================================
--- rs-manual/trunk/src/main/modules.xml (original)
+++ rs-manual/trunk/src/main/modules.xml Thu Oct 17 14:28:15 2019
@@ -9,5 +9,6 @@
<module type="backend">mod_ca</module>
<module type="backend">mod_ca_crl</module>
<module type="backend">mod_ca_disk</module>
+ <module type="backend">mod_ca_engine</module>
<module type="backend">mod_ca_simple</module>
</modules>
Added: rs-manual/trunk/src/site/resources/images/mod_ca_engine-1.png
==============================================================================
Binary file - no diff available.
Propchange: rs-manual/trunk/src/site/resources/images/mod_ca_engine-1.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: rs-manual/trunk/src/site/resources/images/mod_ca_engine-2.png
==============================================================================
Binary file - no diff available.
Propchange: rs-manual/trunk/src/site/resources/images/mod_ca_engine-2.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: rs-manual/trunk/src/site/xhtml5/mod/mod_ca_engine.xhtml5
==============================================================================
--- rs-manual/trunk/src/site/xhtml5/mod/mod_ca_engine.xhtml5 (added)
+++ rs-manual/trunk/src/site/xhtml5/mod/mod_ca_engine.xhtml5 Thu Oct 17 14:28:15 2019
@@ -0,0 +1,798 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+ <head>
+ <title>mod_ca_engine Module</title>
+ <meta name="description" content="Sign certificates using certificates and keys on a smartcard or HSM using the OpenSSL ENGINE mechanism." />
+ <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>Engine Backend Module</h2>
+ <p>Sign certificates using certificates and keys on a smartcard or HSM using the OpenSSL ENGINE mechanism.</p>
+
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>What does it do?</h3>
+ </header>
+ <div class="content">
+
+ <p>This module provides set of signing functions that can be
+ used to sign certificate sign requests backed with the OpenSSL ENGINE
+ mechanism.
+ </p>
+
+ <p>
+ Based on the configuration, this module
+ performs signing of an incoming certificate sign request using
+ a certificate and key stored on an HSM or smartcard.
+ </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_engine</code>
+ module is a
+ <a href="mod_ca.html#backend">backend module</a>
+ and will not do anything useful until
+ <code>mod_ca_engine</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_engine</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_engine-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 signs the certificate sign
+ request using a certificate on the local disk, and a key on an HSM or
+ smartcard using the OpenSSL ENGINE mechanism.</p>
+ <p>Both the <a href="#CAEngineCertificate">CAEngineCertificate</a>
+ directive and the <a href="#CAEngineKey">CASimpleKey</a>
+ directive enables the <a href="mod_ca.html#ca_sign">Sign Request Hook</a>
+ in <a href="mod_ca_engine.html">mod_ca_engine</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_pkcs12</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_getchain">Get Chain Hook</a>
+ </h3>
+ </header>
+ <div class="content">
+ <p>When this hook is triggered, this module returns the intermediate certificate
+ chain used to sign certificate sign requests, if any and present.</p>
+ <p>The <a href="#CAEngineCertificate">CAEngineCertificate</a>
+ directive enables the <a href="mod_ca.html#ca_getchain">Get Chain Hook</a>
+ in <a href="mod_ca_engine.html">mod_ca_engine</a>.</p>
+ <table>
+ <tbody>
+ <tr>
+ <td>
+ <a href="mod_ca_engine.html#ca_getchain">mod_ca_engine</a>
+ </td>
+ <td>This hook returns the certificate chain of a certificate provided by
+ an OpenSSL provided crypto engine such as a smartcard.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </section>
+
+ <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, the
+ <a href="mod_ca.html#ca_sign">Sign Request Hook</a> asks for a serial
+ number to use when signing the certificate.</p>
+ <table>
+ <tbody>
+ <tr>
+ <td>
+ <a href="mod_ca_simple.html#ca_makeserial">mod_ca_simple</a>
+ </td>
+ <td>This hook returns a random serial number, or a serial
+ number extracted from the certificate subject.
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>
+ <a href="mod_ca.html#ca_gettime">Get Time Hook</a>
+ </h3>
+ </header>
+ <div class="content">
+ <p>When this hook is triggered, the
+ <a href="mod_ca.html#ca_sign">Sign Request Hook</a> asks for the time
+ to use when signing the certificate.</p>
+ <table>
+ <tbody>
+ <tr>
+ <td>
+ <a href="mod_ca_simple.html#ca_gettime">mod_ca_simple</a>
+ </td>
+ <td>This hook returns the time to be used to sign a certificate sign
+ request, derived from the system time.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </section>
+
+ </div>
+
+ <div>
+ <img src="../images/mod_ca_engine-2.png" style="width: 100%;" />
+ </div>
+
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>
+ <a href="mod_ca.html#ca_getca">Get Certificate Authority Hook</a>
+ </h3>
+ </header>
+ <div class="content">
+ <p>When this hook is triggered, this module returns the root CA certificate
+ used to sign certificate sign requests.</p>
+ <p>The <a href="#CAEngineCertificate">CAEngineCertificate</a>
+ directive enables the <a href="mod_ca.html#ca_getca">Get Certificate Authority Hook</a>
+ in <a href="mod_ca_engine.html">mod_ca_engine</a>.</p>
+ <table>
+ <tbody>
+ <tr>
+ <td>
+ <a href="mod_ocsp.html">mod_ocsp</a>
+ </td>
+ <td>Respond with the revocation status of a certificate.</td>
+ </tr>
+ <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>
+
+ <section>
+ <header>
+ <h3>
+ <a href="mod_ca.html#ca_getnextca">Get Next Certificate Authority Hook</a>
+ </h3>
+ </header>
+ <div class="content">
+ <p>When this hook is triggered, this module returns the next root CA certificate
+ that will in future be used to sign certificate sign requests.</p>
+ <p>The <a href="#CAEngineNextCertificate">CAEngineNextCertificate</a>
+ directive enables the <a href="mod_ca.html#ca_getnextca">Get Next Certificate Authority Hook</a>
+ in <a href="mod_ca_engine.html">mod_ca_engine</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>
+ </section>
+
+
+ <section class="wrapper style1 align-center"
+ id="directive-reference">
+ <div class="inner">
+ <h2>Examples</h2>
+ <div class="index align-left">
+
+ <section>
+ <header>
+ <h3>Basic Example</h3>
+ </header>
+ <div class="content">
+ <p>The simplest case: issue a certificate to anybody who wants one.</p>
+<pre><code><![CDATA[
+# global configuration
+<IfModule mod_ca_engine.c>
+ CAEngineDevice dynamic
+ CAEnginePreCommand SO_PATH /usr/lib64/engines-1.1/pkcs11.so
+ CAEnginePreCommand ID pkcs11
+ CAEnginePreCommand LIST_ADD 1
+ CAEnginePreCommand LOAD
+ CAEnginePreCommand MODULE_PATH /usr/lib64/opensc-pkcs11.so
+ CAEnginePreCommand PIN ${KEYPIN}
+</IfModule>
+
+# backend configuration:
+<IfModule mod_ca_simple.c>
+ # use system clock as the time source
+ CASimpleTime on
+ # assign a random serial number
+ CASimpleSerialRandom on
+</IfModule>
+<IfModule mod_ca_engine.c>
+ # sign with this certificate...
+ CAEngineCertificate /etc/pki/tls/ca-cert.pem
+ # ...and private key
+ CAEngineKey "${KEYURI}"
+ # add extensions for a typical CA
+ CAEngineExtension basicConstraints CA:FALSE
+ CAEngineExtension keyUsage critical,nonRepudiation,digitalSignature,keyEncipherment
+ CAEngineExtension extendedKeyUsage OID:1.3.6.1.5.5.7.3.2
+ CAEngineExtension subjectKeyIdentifier hash
+ CAEngineExtension authorityKeyIdentifier keyid,issuer
+</IfModule>
+
+# frontend configuration:
+<IfModule mod_csr.c>
+ <Location /csr>
+ SetHandler csr
+ # use subject from the certificate sign request unmodified
+ CsrSubjectRequest *
+ </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>CAEngineCertificate Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Filename of certificate chain: signing certificate first, CA certificate last.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CAEngineCertificate 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_engine</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 filename of the signing certificate, including the
+ certificate chain: signing certificate first, CA certificate last.
+ </p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CAEngineKey Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Set to the URI of the signing key on the smartcard or HSM.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CAEngineKey uri</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_engine</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 URI of the signing key on the smartcard or HSM.
+ </p>
+
+ <p>Examples of URIs include:
+ </p>
+
+<pre><code><![CDATA[
+# backend configuration:
+<IfModule mod_ca_engine.c>
+ CAEngineKey "pkcs11:model=PKCS%2315;manufacturer=EnterSafe;serial=1234567890123456;token=User%20PIN%20%28My%20Token%29;object=Certificate"
+</IfModule>
+]]></code></pre>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CAEngineNextCertificate Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Filename of the next CA certificate to follow this one, if any.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CAEngineNextCertificate 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_engine</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 filename of the next CA certificate to follow this
+ one, if any.
+ </p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CAEngineDays Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Set to the number of days the certificate must be signed for.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CAEngineDays days</code>
+ </td>
+ </tr>
+ <tr>
+ <td>Default</td>
+ <td>
+ <code>CAEngineDays 365</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_engine</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 number of days the certificate must be signed for.</p>
+
+ <p>Defaults to 365 days.</p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CAEngineExtension Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Certificate extension to add to the certificate when signed.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CAEngineExtension string</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_engine</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>Certificate extension to add to the certificate when signed.
+ </p>
+
+ <p>Examples of certificate extensions include:
+ </p>
+
+<pre><code><![CDATA[
+# backend configuration:
+<IfModule mod_ca_engine.c>
+ CAEngineExtension basicConstraints CA:FALSE
+ CAEngineExtension keyUsage critical,nonRepudiation,digitalSignature,keyEncipherment
+ CAEngineExtension extendedKeyUsage OID:1.3.6.1.5.5.7.3.2
+ CAEngineExtension subjectKeyIdentifier hash
+ CAEngineExtension authorityKeyIdentifier keyid,issuer
+</IfModule>
+]]></code></pre>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CAEngineDevice Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Name of the OpenSSL crypto engine to use.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CAEngineDevice string</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_engine</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>Name of the OpenSSL crypto engine to use.
+ </p>
+
+ <p>Examples of crypto engines include:
+ </p>
+
+<pre><code><![CDATA[
+# backend configuration:
+<IfModule mod_ca_engine.c>
+ CAEngineDevice dynamic
+</IfModule>
+]]></code></pre>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CAEnginePreCommand Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Commands to process before the engine is initialised.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CAEnginePreCommand string</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_engine</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>Commands to process before the engine is initialised.
+ </p>
+
+ </div>
+ </section>
+
+ <section>
+ <header>
+ <h3>CAEnginePostCommand Directive</h3>
+ </header>
+ <div class="content">
+
+ <table>
+ <tbody>
+ <tr>
+ <td>Description</td>
+ <td>Commands to process after the engine is initialised.</td>
+ </tr>
+ <tr>
+ <td>Syntax</td>
+ <td>
+ <code>CAEnginePostCommand string</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_engine</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>Commands to process after the engine is initialised.
+ </p>
+
+ </div>
+ </section>
+
+ </div>
+ </div>
+ </section>
+
+ </div>
+ </body>
+</html>
+
More information about the rs-commit
mailing list