From e1b4dbb663d8dfb7f43d3846b536af89043a58e9 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 23 May 2014 15:28:53 +0000
Subject: [PATCH] Backport CR-3569 Fix for OPENDJ-1461: Setting up SSL for AD pass thru
---
opends/src/main/docbkx/admin-guide/chap-change-certs.xml | 8 +
opends/src/main/docbkx/admin-guide/chap-connection-handlers.xml | 234 +++++++++++++++++++++++++++++++++++++++++++---
2 files changed, 222 insertions(+), 20 deletions(-)
diff --git a/opends/src/main/docbkx/admin-guide/chap-change-certs.xml b/opends/src/main/docbkx/admin-guide/chap-change-certs.xml
index f57bfd5..885e646 100644
--- a/opends/src/main/docbkx/admin-guide/chap-change-certs.xml
+++ b/opends/src/main/docbkx/admin-guide/chap-change-certs.xml
@@ -207,6 +207,7 @@
-keyalg RSA \
-validity 7300 \
-keysize 2048 \
+ -ext "san=dns:opendj.example.com" \
-dname "CN=opendj.example.com, O=Administration Connector Self-Signed Certificate" \
-keystore admin-keystore \
-storepass `cat admin-keystore.pin` \
@@ -288,7 +289,12 @@
Extensions:
-#1: ObjectId: 2.5.29.14 Criticality=false
+#1: ObjectId: 2.5.29.17 Criticality=false
+SubjectAlternativeName [
+ DNSName: opendj.example.com
+]
+
+#2: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: FE 33 69 67 FF E8 64 F6 D3 FB CD 14 1C D3 01 44 .3ig..d........D
diff --git a/opends/src/main/docbkx/admin-guide/chap-connection-handlers.xml b/opends/src/main/docbkx/admin-guide/chap-connection-handlers.xml
index 9c1350c..b175d48 100644
--- a/opends/src/main/docbkx/admin-guide/chap-connection-handlers.xml
+++ b/opends/src/main/docbkx/admin-guide/chap-connection-handlers.xml
@@ -241,23 +241,36 @@
<procedure xml:id="new-ca-signed-cert">
<title>To Request and Install a CA-Signed Certificate</title>
- <para>First you create a server certificate in a Java Key Store. Next you
- issue a signing request to the CA, and get the CA-signed certificate as a
- reply. Then you set up the Key Manager Provider and Trust Manager Provider
- to rely on your new server certificate stored in the OpenDJ key store.</para>
+ <para>
+ First you create a server private key and public key certificate
+ in a Java Key Store.
+ Next you issue a signing request to the CA,
+ and get the CA-signed certificate as a reply.
+ Then you set up the Key Manager Provider and Trust Manager Provider
+ to rely on your new server certificate stored in the OpenDJ key store.
+ </para>
<step>
- <para>Generate the server certificate by using the Java
- <command>keytool</command> command.</para>
+ <para>
+ Generate the server private key and public key certificate
+ by using the Java <command>keytool</command> command.
+ </para>
- <para>The CN attribute value is the FQDN for OpenDJ directory server, which
- you can see under Server Details in the OpenDJ Control Panel.</para>
+ <para>
+ The FQDN for OpenDJ directory server,
+ which you can see under Server Details in the OpenDJ Control Panel,
+ is set both as a <literal>DNSName</literal>
+ in the certificate's <literal>SubjectAlternativeName</literal> list,
+ and also in the CN of the certificate's subject name DN
+ for backwards compatibility.
+ </para>
<screen>
$ <userinput>keytool \
-genkey \
-alias server-cert \
-keyalg rsa \
+ -ext "san=dns:opendj.example.com" \
-dname "CN=opendj.example.com,O=Example Corp,C=FR" \
-keystore /path/to/opendj/config/keystore \
-storepass changeit \
@@ -268,6 +281,28 @@
<option>-keypass</option> options take identical password arguments.
OpenDJ requires that you use the same password to protect both the keystore
and also the private key.</para></note>
+
+ <para>
+ If the server can respond on multiple FQDNs,
+ then specify multiple subject alternative names
+ when using the <command>keytool</command> command's
+ <option>-ext</option> option.
+ In the following example
+ the primary FQDN is <literal>opendj.example.com</literal>
+ and the alternative is <literal>ldap.example.com</literal>.
+ </para>
+
+ <screen>
+$ <userinput>keytool \
+ -genkey \
+ -alias server-cert \
+ -keyalg rsa \
+ -ext "san=dns:opendj.example.com,dns:ldap.example.com" \
+ -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
+ -keystore /path/to/opendj/config/keystore \
+ -storepass changeit \
+ -keypass changeit</userinput>
+ </screen>
</step>
<step>
@@ -323,7 +358,7 @@
$ openssl x509 -req -in server-cert.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server-cert.crt
Signature ok
-subject=/C=FR/O=Example Corp/CN=openam.example.com
+subject=/C=FR/O=Example Corp/CN=opendj.example.com
Getting CA Private Key
Enter pass phrase for ca.key:
@@ -355,6 +390,7 @@
<screen>
$ <userinput>keytool \
-import \
+ -trustcacerts \
-keystore /path/to/opendj/config/keystore \
-file ca.crt \
-alias ca-cert \
@@ -443,10 +479,100 @@
</step>
<step>
- <para>Configure the File Based Trust Manager Provider for JKS to use the
- key store and PIN as well.</para>
+ <para>
+ Configure the File Based Trust Manager Provider.
+ </para>
- <screen>
+ <para>
+ By convention and by default,
+ the OpenDJ File Based Trust Manager Provider uses a Java Key Store file,
+ <filename>opendj/config/truststore</filename>,
+ to hold trusted public key certificates.
+ Follow these steps to set up the trust store file,
+ and to configure the trust manager provider.
+ </para>
+
+ <substeps>
+ <step>
+ <para>
+ If you imported your own CA certificate into the key store,
+ also import the file into the trust store.
+ </para>
+
+ <screen>
+$ <userinput>keytool \
+ -import \
+ -trustcacerts \
+ -keystore /path/to/opendj/config/truststore \
+ -file ca.crt \
+ -alias ca-cert \
+ -storepass changeit</userinput>
+<computeroutput>Owner: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
+Issuer: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
+Serial number: d4586ea05c878b0c
+Valid from: Tue Jan 29 09:30:31 CET 2013 until: Mon Jan 24 09:30:31 CET 2033
+Certificate fingerprints:
+ MD5: 8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA
+ SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA
+ SHA256: 5D:20:F1:86:CC:CD:64:50:...:DF:15:43:07:69:44:00:FB:36:CF
+ Signature algorithm name: SHA1withRSA
+ Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.35 Criticality=false
+AuthorityKeyIdentifier [
+KeyIdentifier [
+0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
+0010: 03 D4 56 7B ..V.
+]
+[EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR]
+SerialNumber: [ d4586ea0 5c878b0c]
+]
+
+#2: ObjectId: 2.5.29.19 Criticality=false
+BasicConstraints:[
+ CA:true
+ PathLen:2147483647
+]
+
+#3: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
+0010: 03 D4 56 7B ..V.
+]
+]
+
+Trust this certificate? [no]:</computeroutput> <userinput>yes</userinput>
+<computeroutput>Certificate was added to keystore</computeroutput>
+ </screen>
+ </step>
+
+ <step>
+ <para>
+ Import the signed server certificate into the trust store.
+ </para>
+
+ <screen>
+$ <userinput>keytool \
+ -import \
+ -trustcacerts \
+ -alias server-cert \
+ -file ~/Downloads/server-cert.crt \
+ -keystore /path/to/opendj/config/keystore \
+ -storepass changeit \
+ -keypass changeit</userinput>
+<computeroutput>Certificate was added to keystore</computeroutput>
+ </screen>
+ </step>
+
+ <step>
+ <para>
+ Configure the File Based Trust Manager Provider to use the trust store.
+ </para>
+
+ <screen>
$ <userinput>dsconfig \
set-trust-manager-provider-prop \
--hostname opendj.example.com \
@@ -455,11 +581,13 @@
--bindPassword password \
--provider-name JKS \
--set enabled:true \
- --set trust-store-file:config/keystore \
+ --set trust-store-file:config/truststore \
--set trust-store-pin:changeit \
--trustAll \
--no-prompt</userinput>
- </screen>
+ </screen>
+ </step>
+ </substeps>
<para>At this point, OpenDJ directory server can use your new CA-signed
certificate, for example for StartTLS and LDAPS connection handlers.</para>
@@ -508,6 +636,7 @@
-genkey \
-alias server-cert \
-keyalg rsa \
+ -ext "san=dns:opendj.example.com" \
-dname "CN=opendj.example.com,O=Example Corp,C=FR" \
-keystore /path/to/opendj/config/keystore \
-storepass changeit \
@@ -526,6 +655,28 @@
key store and also the private key.</para>
</note>
+ <para>
+ If the server can respond on multiple FQDNs,
+ then specify multiple subject alternative names
+ when using the <command>keytool</command> command's
+ <option>-ext</option> option.
+ In the following example
+ the primary FQDN is <literal>opendj.example.com</literal>
+ and the alternative is <literal>ldap.example.com</literal>.
+ </para>
+
+ <screen>
+$ <userinput>keytool \
+ -genkey \
+ -alias server-cert \
+ -keyalg rsa \
+ -ext "san=dns:opendj.example.com,dns:ldap.example.com" \
+ -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
+ -keystore /path/to/opendj/config/keystore \
+ -storepass changeit \
+ -keypass changeit</userinput>
+ </screen>
+
<para>Keep track of the password provided to the <option>-storepass</option>
and <option>-keypass</option> options.</para>
</step>
@@ -569,12 +720,55 @@
</screen>
</step>
<step>
- <para>Configure the File Based Trust Manager Provider for JKS to use the
- key store and PIN as well.</para>
+ <para>
+ Configure the File Based Trust Manager Provider for JKS
+ to use the new server certificate.
+ </para>
- <para>If you skipped the previous step, you can also skip this step.</para>
+ <para>
+ By convention and by default,
+ the OpenDJ File Based Trust Manager Provider uses a Java Key Store file,
+ <filename>opendj/config/truststore</filename>,
+ to hold trusted public key certificates.
+ Follow these steps to set up the trust store file,
+ and to configure the trust manager provider.
+ </para>
+
+ <substeps>
+ <step>
+ <para>
+ Set up a trust store containing the server's public key certificate.
+ </para>
+
+ <screen>
+$ <userinput>keytool \
+ -export \
+ -alias server-cert \
+ -keystore /path/to/opendj/config/keystore \
+ -storepass changeit \
+ -file server-cert.crt</userinput>
+<computeroutput>Certificate stored in file <server-cert.crt></computeroutput>
+$ <userinput>keytool \
+ -import \
+ -trustcacerts \
+ -alias server-cert \
+ -file server-cert.crt \
+ -keystore /path/to/opendj/config/truststore \
+ -storepass changeit</userinput>
+<computeroutput>...
+Trust this certificate? [no]: </computeroutput><userinput>yes</userinput>
+<computeroutput>Certificate was added to keystore</computeroutput>
+ </screen>
+ </step>
+
+ <step>
+ <para>
+ Configure the trust manager provider to use the trust store.
+ </para>
<screen>
+$ <userinput>echo changeit > /path/to/opendj/config/truststore.pin</userinput>
+$ <userinput>chmod 600 /path/to/opendj/config/truststore.pin</userinput>
$ <userinput>dsconfig \
set-trust-manager-provider-prop \
--hostname opendj.example.com \
@@ -583,11 +777,13 @@
--bindPassword password \
--provider-name JKS \
--set enabled:true \
- --set trust-store-file:config/keystore \
- --set trust-store-pin-file:config/keystore.pin \
+ --set trust-store-file:config/truststore \
+ --set trust-store-pin-file:config/truststore.pin \
--trustAll \
--no-prompt</userinput>
</screen>
+ </step>
+ </substeps>
<para>At this point, OpenDJ directory server can use your new self-signed
certificate, for example for StartTLS and LDAPS or HTTPS connection
--
Gitblit v1.10.0