Use SSL connections between Dispatcher and the render computer:
Operations related to the SSL certificates are bound to third-party products. They are not covered by the Adobe Platinum Maintenance and Support contract.
Configure Dispatcher to communicate with the AEM or CQ render instance using SSL connections.
Before you configure Dispatcher, configure AEM or CQ to use SSL:
When Dispatcher receives an HTTPS request, Dispatcher includes the following headers in the subsequent request that it sends to AEM or CQ:
X-Forwarded-SSL
X-Forwarded-SSL-Cipher
X-Forwarded-SSL-Keysize
X-Forwarded-SSL-Session-ID
A request through Apache-2.4 with mod_ssl
includes headers that are similar to the following example:
X-Forwarded-SSL: on
X-Forwarded-SSL-Cipher: DHE-RSA-AES256-SHA
X-Forwarded-SSL-Session-ID: 814825E8CD055B4C166C2EF6D75E1D0FE786FFB29DEB6DE1E239D5C771CB5B4D
To configure Dispatcher to connect with AEM or CQ over SSL, your dispatcher.any file requires the following properties:
renders
section of the virtual host includes an item that identifies the host name and port of the CQ or AEM instance that uses HTTPS.renders
item includes a property named secure
of value 1
.Note: Create another virtual host for handling HTTP requests, if necessary.
The following example dispatcher.any
file shows the property values for connecting using HTTPS to a CQ instance that is running on host localhost
and port 8443
:
/farms
{
/secure
{
/virtualhosts
{
# select this farm for all incoming HTTPS requests
"https://*"
}
/renders
{
/0001
{
# hostname or IP of the render
/hostname "localhost"
# port of the render
/port "8443"
# connect via HTTPS
/secure "1"
}
}
# the rest of the properties are omitted
}
/non-secure
{
/virtualhosts
{
# select this farm for all incoming HTTP requests
"http://*"
}
/renders
{
/0001
{
# hostname or IP of the render
/hostname "localhost"
# port of the render
/port "4503"
}
}
# the rest of the properties are omitted
}
To use Mutual SSL, configure the connections between Dispatcher and the render computer (typically an AEM or CQ publish instance):
To configure mutual SSL, you require certificates that are signed by a trusted certificate authority (CA). Self-signed certificates are not adequate. You can either act as the CA or use the services of a third-party CA to sign your certificates. To configure mutual SSL, you require the following items:
To configure mutual SSL, perform the following steps:
Create or obtain the CA-signed certificates that authenticate the publish instance and Dispatcher.
If you are acting as the CA, use OpenSSL to create the Certificate Authority that signs the server and client certificates. (You must have the OpenSSL libraries installed.) If you are using a third-party CA, do not perform this procedure.
Open a terminal and change the current directory to the directory that contains the CA.sh
file, such as /usr/local/ssl/misc
.
To create the CA, enter the following command and then provide values when prompted:
./CA.sh -newca
Several properties in the openssl.cnf
file control the behavior of the CA.sh script. Edit this file as required before you create your CA.
Use OpenSSL to create the certificate requests to send to the third-party CA or to sign with your CA.
When you create a certificate, OpenSSL uses the Common Name property to identify the certificate holder. For the certificate of the render instance, use the instance computer’s host name as the Common Name if you are configuring Dispatcher to accept the certificate, and only if it matches the hostname of the Publish instance. (See the DispatcherCheckPeerCN property.)
Open a terminal and change the current directory to the directory that contains the CH.sh file of your OpenSSL libraries.
Enter the following command and provide values when prompted. If necessary, use the host name of the publish instance as the Common Name. The host name is DNS-resolvable name for the IP address of the render:
./CA.sh -newreq
If you are using a third-party CA, send the newreq.pem file to the CA to sign. If you are acting as the CA, continue to step 3.
To sign the certificate using the certificate of your CA, enter the following command:
./CA.sh -sign
Two files named newcert.pem
and newkey.pem
are created in the directory that contains your CA management files. These two files are the public certificate and private key for the render computer, respectively.
Rename newcert.pem
to rendercert.pem
, and rename newkey.pem
to renderkey.pem
.
Repeat steps 2 and 3 to create a certificate and a public key for the Dispatcher module. Ensure that you use a Common Name that is specific to the Dispatcher instance.
Rename newcert.pem
to dispcert.pem
, and rename newkey.pem
to dispkey.pem
.
Configure SSL on the render instance using the rendercert.pem
and renderkey.pem
files.
Use the following command to convert the render certificate, which is a PEM file, to a PKCS#12 file. Also include the certificate of the CA that signed the render certificate:
In a terminal window, change the current directory to the location of the render certificate and private key.
To convert the render certificate, which is a PEM file, to a PKCS#12 file, enter the following command. Also include the certificate of the CA that signed the render certificate:
openssl pkcs12 -export -in rendercert.pem -inkey renderkey.pem -certfile demoCA/cacert.pem -out rendercert.p12
To convert PKCS#12 file to Java™ KeyStore (JKS) format, enter the following command:
keytool -importkeystore -srckeystore servercert.p12 -srcstoretype pkcs12 -destkeystore render.keystore
The Java™ Keystore is created using a default alias. Change the alias if desired:
keytool -changealias -alias 1 -destalias jettyhttp -keystore render.keystore
If you are acting as the CA, import your CA certificate into a keystore. Then, configure the JVM that runs the render instance to trust the keystore.
Use a text editor to open the cacert.pem file and remove all the text that precedes the following line:
-----BEGIN CERTIFICATE-----
Use the following command to import the certificate into a keystore:
keytool -import -keystore cacerts.keystore -alias myca -storepass password -file cacert.pem
To configure the JVM that runs your render instance to trust the keystore, use the following system property:
-Djavax.net.ssl.trustStore=<location of cacerts.keystore>
For example, if you use the crx-quickstart/bin/quickstart script to start your publish instance you can modify the CQ_JVM_OPTS property:
CQ_JVM_OPTS='-server -Xmx2048m -XX:MaxPermSize=512M -Djavax.net.ssl.trustStore=/usr/lib/cq6.0/publish/ssl/cacerts.keystore'
To configure the HTTP service of the render instance to use SSL, use the render certificate with the instructions in the Enable SSL on the Publish Instance section:
To configure Dispatcher to use mutual SSL, prepare the Dispatcher certificate and then configure the web server module.
Combine the Dispatcher certificate and the unencrypted private key into a single PEM file. Use a text editor or the cat
command to create a file that is similar to the following example:
Open a terminal and change the current directory to the location of the dispkey.pem file.
To decrypt the private key, enter the following command:
openssl rsa -in dispkey.pem -out dispkey_unencrypted.pem
Use a text editor or the cat
command to combine the unencrypted private key and the certificate in a single file that is similar to the following example:
-----BEGIN RSA PRIVATE KEY-----
MIICxjBABgkqhkiG9w0B...
...M2HWhDn5ywJsX
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIC3TCCAk...
...roZAs=
-----END CERTIFICATE-----
Add the following properties to the Dispatcher module configuration (in httpd.conf
):
DispatcherCertificateFile
: The path to the Dispatcher unified certificate file, containing the public certificate and the unencrypted private key. This file is used when SSL server requests the Dispatcher client certificate.DispatcherCACertificateFile
: The path to the CA certificate file, used if the SSL server presents a CA that is not trusted by a root authority.DispatcherCheckPeerCN
: Whether to enable ( On
) or disable ( Off
) host name checking for remote server certificates.The following code is an example configuration:
<IfModule disp_apache2.c>
DispatcherConfig conf/dispatcher.any
DispatcherLog logs/dispatcher.log
DispatcherLogLevel 3
DispatcherNoServerHeader 0
DispatcherDeclineRoot 0
DispatcherUseProcessedURL 0
DispatcherPassError 0
DispatcherCertificateFile disp_unified.pem
DispatcherCACertificateFile cacert.pem
DispatcherCheckPeerCN On
</IfModule>