From: Joe Orton <jorton@apache.org>
Date: Wed, 19 Feb 2020 17:04:21 +0000 (+0000)
Subject: Sync PKCS#11 docs from trunk. [skip ci]
X-Git-Tag: 2.4.42~77
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fec6fd9f68486fdf71671a111d957787b8982d60;p=thirdparty%2Fapache%2Fhttpd.git

Sync PKCS#11 docs from trunk. [skip ci]


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1874201 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/mod/mod_ssl.xml b/docs/manual/mod/mod_ssl.xml
index 9ba6069454a..51d9d7a67b7 100644
--- a/docs/manual/mod/mod_ssl.xml
+++ b/docs/manual/mod/mod_ssl.xml
@@ -895,15 +895,16 @@ SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
 
 <directivesynopsis>
 <name>SSLCertificateFile</name>
-<description>Server PEM-encoded X.509 certificate data file</description>
-<syntax>SSLCertificateFile <em>file-path</em></syntax>
+<description>Server PEM-encoded X.509 certificate data file or token identifier</description>
+<syntax>SSLCertificateFile <var>file-path</var>|<var>certid</var></syntax>
 <contextlist><context>server config</context>
 <context>virtual host</context></contextlist>
+<compatibility><var>certid</var> available in 2.5.1 and later.</compatibility>
 
 <usage>
 <p>
-This directive points to a file with certificate data in PEM format.
-At a minimum, the file must include an end-entity (leaf) certificate.
+This directive points to a file with certificate data in PEM format, or the certificate identifier through a configured cryptographic token.
+If using a PEM file, at minimum, the file must include an end-entity (leaf) certificate.
 The directive can be used multiple times (referencing different filenames)
 to support multiple algorithms for server authentication - typically
 RSA, DSA, and ECC. The number of supported algorithms depends on the
@@ -944,6 +945,17 @@ after the certificates using a separate key file. If the private
 key is encrypted, the pass phrase dialog is forced at startup time.
 </p>
 
+<p>As an alternative to storing certificates and private keys in
+files, a certificate identifier can be used to identify a certificate
+stored in a token.  Currently, only <a
+href="https://tools.ietf.org/html/rfc7512">PKCS#11 URIs</a> are
+recognized as certificate identifiers, and can be used in conjunction
+with the OpenSSL <code>pkcs11</code> engine.  If <directive
+module="mod_ssl">SSLCertificateKeyFile</directive> is omitted, the
+certificate and private key can be loaded through the single
+identifier specified with <directive
+module="mod_ssl">SSLCertificateFile</directive>.</p>
+
 <note>
 <title>DH parameter interoperability with primes > 1024 bit</title>
 <p>
@@ -989,7 +1001,10 @@ thus using a custom/suitable length.
 
 <example><title>Example</title>
 <highlight language="config">
+# Example using a PEM-encoded file.
 SSLCertificateFile "/usr/local/apache2/conf/ssl.crt/server.crt"
+# Example use of a certificate and private key from a PKCS#11 token:
+SSLCertificateFile "pkcs11:token=My%20Token%20Name;id=45"
 </highlight>
 </example>
 </usage>
@@ -998,15 +1013,17 @@ SSLCertificateFile "/usr/local/apache2/conf/ssl.crt/server.crt"
 <directivesynopsis>
 <name>SSLCertificateKeyFile</name>
 <description>Server PEM-encoded private key file</description>
-<syntax>SSLCertificateKeyFile <em>file-path</em></syntax>
+<syntax>SSLCertificateKeyFile <var>file-path</var>|<var>keyid</var></syntax>
 <contextlist><context>server config</context>
 <context>virtual host</context></contextlist>
+<compatibility><var>keyid</var> available in 2.5.1 and later.</compatibility>
 
 <usage>
 <p>
 This directive points to the PEM-encoded private key file for the
-server. If the contained private key is encrypted, the pass phrase
-dialog is forced at startup time.</p>
+server, or the key ID through a configured cryptographic token. If the
+contained private key is encrypted, the pass phrase dialog is forced
+at startup time.</p>
 
 <p>
 The directive can be used multiple times (referencing different filenames)
@@ -1022,9 +1039,18 @@ is highly discouraged. If it is used, the certificate files using such
 an embedded key must be configured after the certificates using a separate
 key file.</p>
 
+<p>As an alternative to storing private keys in files, a key
+identifier can be used to identify a private key stored in a
+token.  Currently, only <a href="https://tools.ietf.org/html/rfc7512">PKCS#11 URIs</a> are recognized as private key
+identifiers, and can be used in conjunction with the OpenSSL
+<code>pkcs11</code> engine.</p>
+
 <example><title>Example</title>
 <highlight language="config">
+# To use a private key from a PEM-encoded file:
 SSLCertificateKeyFile "/usr/local/apache2/conf/ssl.key/server.key"
+# To use a private key from a PKCS#11 token:
+SSLCertificateKeyFile "pkcs11:token=My%20Token%20Name;id=45"
 </highlight>
 </example>
 </usage>
@@ -1033,7 +1059,7 @@ SSLCertificateKeyFile "/usr/local/apache2/conf/ssl.key/server.key"
 <directivesynopsis>
 <name>SSLCertificateChainFile</name>
 <description>File of PEM-encoded Server CA Certificates</description>
-<syntax>SSLCertificateChainFile <em>file-path</em></syntax>
+<syntax>SSLCertificateChainFile <var>file-path</var></syntax>
 <contextlist><context>server config</context>
 <context>virtual host</context></contextlist>
 
@@ -1109,7 +1135,7 @@ SSLCACertificatePath "/usr/local/apache2/conf/ssl.crt/"
 <name>SSLCACertificateFile</name>
 <description>File of concatenated PEM-encoded CA Certificates
 for Client Auth</description>
-<syntax>SSLCACertificateFile <em>file-path</em></syntax>
+<syntax>SSLCACertificateFile <var>file-path</var></syntax>
 <contextlist><context>server config</context>
 <context>virtual host</context></contextlist>
 
@@ -1133,7 +1159,7 @@ SSLCACertificateFile "/usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt"
 <name>SSLCADNRequestFile</name>
 <description>File of concatenated PEM-encoded CA Certificates
 for defining acceptable CA names</description>
-<syntax>SSLCADNRequestFile <em>file-path</em></syntax>
+<syntax>SSLCADNRequestFile <var>file-path</var></syntax>
 <contextlist><context>server config</context>
 <context>virtual host</context></contextlist>
 
@@ -1236,7 +1262,7 @@ SSLCARevocationPath "/usr/local/apache2/conf/ssl.crl/"
 <name>SSLCARevocationFile</name>
 <description>File of concatenated PEM-encoded CA CRLs for
 Client Auth</description>
-<syntax>SSLCARevocationFile <em>file-path</em></syntax>
+<syntax>SSLCARevocationFile <var>file-path</var></syntax>
 <contextlist><context>server config</context>
 <context>virtual host</context></contextlist>
 
@@ -1393,7 +1419,7 @@ SSLVerifyDepth 10
 <directivesynopsis>
 <name>SSLSRPVerifierFile</name>
 <description>Path to SRP verifier file</description>
-<syntax>SSLSRPVerifierFile <em>file-path</em></syntax>
+<syntax>SSLSRPVerifierFile <var>file-path</var></syntax>
 <contextlist><context>server config</context>
 <context>virtual host</context></contextlist>
 <compatibility>Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or
@@ -2164,7 +2190,7 @@ SSLProxyCACertificatePath "/usr/local/apache2/conf/ssl.crt/"
 <name>SSLProxyCACertificateFile</name>
 <description>File of concatenated PEM-encoded CA Certificates
 for Remote Server Auth</description>
-<syntax>SSLProxyCACertificateFile <em>file-path</em></syntax>
+<syntax>SSLProxyCACertificateFile <var>file-path</var></syntax>
 <contextlist><context>server config</context> <context>virtual host</context>
 <context>proxy section</context></contextlist>
 <compatibility>The proxy section context is allowed in httpd 2.4.30 and later</compatibility>
@@ -2217,7 +2243,7 @@ SSLProxyCARevocationPath "/usr/local/apache2/conf/ssl.crl/"
 <name>SSLProxyCARevocationFile</name>
 <description>File of concatenated PEM-encoded CA CRLs for
 Remote Server Auth</description>
-<syntax>SSLProxyCARevocationFile <em>file-path</em></syntax>
+<syntax>SSLProxyCARevocationFile <var>file-path</var></syntax>
 <contextlist><context>server config</context> <context>virtual host</context>
 <context>proxy section</context></contextlist>
 <compatibility>The proxy section context is allowed in httpd 2.4.30 and later</compatibility>
@@ -2768,7 +2794,7 @@ One potential use is when a proxy is used for retrieving OCSP queries.</p>
 <directivesynopsis>
 <name>SSLSessionTicketKeyFile</name>
 <description>Persistent encryption/decryption key for TLS session tickets</description>
-<syntax>SSLSessionTicketKeyFile <em>file-path</em></syntax>
+<syntax>SSLSessionTicketKeyFile <var>file-path</var></syntax>
 <contextlist><context>server config</context>
 <context>virtual host</context></contextlist>
 <compatibility>Available in httpd 2.4.0 and later, if using OpenSSL 0.9.8h or later</compatibility>