Skip to content

Commit 4d2a01b

Browse files
rjrudinrjrudin
authored
Merge pull request #323 from jkerr5/feature/ssl-2way-project
Added 2-way ssl project example
2 parents a9adda5 + 68faabb commit 4d2a01b

File tree

8 files changed

+488
-0
lines changed

8 files changed

+488
-0
lines changed

‎examples/ssl-2way-project/README.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
This project shows how to create an SSLContext to support deploying modules when 2-way SSL is configured
2+
for an app server.
3+
4+
2-way SSL requires a certificate template to be configured on the MarkLogic app server,
5+
"ssl require client certificate" set to true and one or more "ssl client certificate authorities"
6+
selected indicating which CAs the client certificates must be signed by.
7+
8+
Follow instructions here https://docs.marklogic.com/guide/security/SSL to setup SSL for
9+
the MarkLogic app server.
10+
11+
To make this work, you will need a certificate authority (CA) that can sign certificates for you.
12+
You can either use a known 3rd party or setup your own CA for testing. The rest of the instructions
13+
assume that the same CA is used to sign both the client and the server certificates.
14+
15+
## Create a server certificate
16+
If the server does not yet have a certificate signed by your CA, you will need to get one and imort
17+
it to the server. If you already have server certificated signed by the CA, you can skip this step.
18+
19+
1) Using the certificate template created above, generate and download a certificate request (CSR). Use
20+
that CSR to request a certificate from the CA (or generate one yourself if you have your own CA).
21+
22+
_Important: Your CSR will have the values for country, state/province, city/town, organization,
23+
organizational unit and email address from the certificate template. Your CA will have requirements
24+
for what must be in each of those fields. If using your own CA to sign certificates, you will need
25+
to configure openssl to be able to process CSRs with the values from the template or set the template
26+
values to the values needed for your openssl CA configuration before generating the server CSR._
27+
28+
The following are helpful resources if considering setting up your own CA for testing:
29+
* https://www.area536.com/projects/be-your-own-certificate-authority-with-openssl/
30+
* https://jamielinux.com/docs/openssl-certificate-authority/create-the-root-pair.html
31+
32+
1) Once you have the signed server certificate, import it into the server using the "Import" tab of
33+
the certificate template used to generate the CSR.
34+
35+
_Important: The CN in the server cert will be the hostname of the MarkLogic host as seen from the "Hosts" list in
36+
the admin UI. This will need to be the hostname you use to connect to MarkLogic if hostname verification is
37+
being used._
38+
39+
## Create a client certificate
40+
Since we are using ml-gradle which uses the MarkLogic Java Client under the covers, we need to use the
41+
Java SSL libraries to setup the client SSL configuration. Java uses a "keystore" to manage client and
42+
CA certificates. We will use the Java _keytool_ commandline tool to setup a keystore for the client.
43+
44+
The follow instructions were guided by the following helpful resources:
45+
* https://docs.oracle.com/cd/E19509-01/820-3503/ggfen/index.html
46+
* https://www.digitalocean.com/community/tutorials/java-keytool-essentials-working-with-java-keystores
47+
48+
1) Create a keystore
49+
```
50+
keytool -keystore clientkeystore -genkey -alias client
51+
```
52+
53+
You will be prompted for a password for the keystore. Remember this and use it as the `mlKeystorePassword`
54+
in the `gradle.properties` file.
55+
56+
You will be propted to enter values for your name (CN), country, state/province, city/town, organization and
57+
organizational unit. Enter values as required by your CA but make sure to use the MarkLogic username that will
58+
be using the certificate when propted for "your first and last name". This is the CN stored in the certificate.
59+
60+
_Important: The CN in client certificate needs to match the user name that you will use to connect to
61+
MarkLogic or authentication will fail._
62+
63+
If you want a different password on the client certificate, enter one when prompted and use this as the
64+
`mlKeystoreCertPassword` in the `gradle.properties` file. Otherwise, hit enter to use the same password as the
65+
keystore.
66+
67+
When complete, this will create a file called `clientkeystore` (you can name this file whatever you want though).
68+
Use this as the value for `mlKeystore` in the `gradle.properties` file.
69+
70+
1) Create a client CSR
71+
```
72+
keytool -keystore clientkeystore -certreq -alias client -keyalg rsa -file client.csr
73+
```
74+
75+
1) Use the CSR to have a CA to generate a signed client certificate (or generate one using your own CA)
76+
77+
1) Import the CA certificate
78+
```
79+
keytool -import -keystore clientkeystore -file ca.crt -alias theCARoot
80+
```
81+
82+
1) Import the signed client certificate
83+
```
84+
keytool -import -keystore clientkeystore -file client.crt -alias client
85+
```
86+
87+
88+
89+
90+
s

‎examples/ssl-2way-project/build.gradle‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
plugins {
2+
id "com.marklogic.ml-gradle" version "3.2.1"
3+
}
4+
5+
6+
/*
7+
You can use the Java keytool utility to import a MarkLogic certificate into a keystore.
8+
See the Java JSSE documentation for details on the use of the keytool and your keystore options.
9+
10+
You can explicitly specify a keystore, as shown in this example, or you can specify a null
11+
keystore. Specifying a null keystore causes the TrustManagerFactory to locate your default
12+
keystore, as described in the Java Secure Socket Extension (JSSE) Reference Guide.
13+
*/
14+
15+
import java.io.FileInputStream;
16+
import javax.net.ssl.KeyManager;
17+
import javax.net.ssl.KeyManagerFactory;
18+
import javax.net.ssl.TrustManager;
19+
import javax.net.ssl.TrustManagerFactory;
20+
import javax.net.ssl.X509TrustManager;
21+
import javax.net.ssl.sslContext;
22+
import java.security.KeyStore;
23+
import java.security.cert.X509Certificate;
24+
import java.security.cert.CertificateException;
25+
import com.marklogic.client.DatabaseClientFactory;
26+
27+
if (project.hasProperty("mlKeystore")) {
28+
29+
ext {
30+
// mlAppConfig is an instance of com.marklogic.appdeployer.AppConfig
31+
mlAppConfig {
32+
33+
// This uses the same keystore for server cert validation as well as the client cert
34+
// These could be different though
35+
KeyStore trustedKeyStore = KeyStore.getInstance("JKS")
36+
trustedKeyStore.load(new FileInputStream(mlKeystore), mlKeystorePassword.toCharArray())
37+
38+
TrustManager[] trust = null
39+
40+
// This doesn't validate the server cert unless you set mlValidateServerCert=true
41+
if (project.hasProperty("mlValidateServerCert") && mlValidateServerCert.toBoolean()) {
42+
// Build trust manager to validate server certificates using the specified key store.
43+
TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance("SunX509")
44+
trustManagerFactory.init(trustedKeyStore)
45+
46+
trust = trustManagerFactory.getTrustManagers()
47+
} else {
48+
trust = [
49+
new X509TrustManager() {
50+
public X509Certificate[] getAcceptedIssuers() {
51+
return [];
52+
}
53+
54+
public void checkClientTrusted(X509Certificate[] chain,
55+
String authType) throws CertificateException {
56+
}
57+
58+
public void checkServerTrusted(X509Certificate[] chain,
59+
String authType) throws CertificateException {
60+
}
61+
}
62+
]
63+
}
64+
65+
// Load key store with client certificates.
66+
KeyStore clientKeyStore = KeyStore.getInstance("JKS")
67+
clientKeyStore.load(new FileInputStream(mlKeystore), mlKeystorePassword.toCharArray())
68+
69+
if (! project.hasProperty("mlKeystoreCertPassword")) {
70+
mlKeystoreCertPassword = mlKeystorePassword
71+
}
72+
73+
// Get key manager to provide client certificate
74+
KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance("SunX509")
75+
keyManagerFactory.init(clientKeyStore, mlKeystoreCertPassword.toCharArray())
76+
77+
KeyManager[] key = keyManagerFactory.getKeyManagers()
78+
79+
// Initialize the SSL context with key and trust managers.
80+
SSLContext sslContext = SSLContext.getInstance("SSLv3")
81+
sslContext.init(key, trust, null)
82+
83+
restSslContext = sslContext
84+
85+
// This turns off hostname verification unless mlVerifyServerHostname=true
86+
if (project.hasProperty("mlVerifyServerHostname") && mlVerifyServerHostname.toBoolean()) {
87+
restSslHostnameVerifier = DatabaseClientFactory.SSLHostnameVerifier.COMMON // change to STRICT if needed
88+
} else {
89+
restSslHostnameVerifier = DatabaseClientFactory.SSLHostnameVerifier.ANY
90+
}
91+
}
92+
}
93+
94+
}

‎examples/ssl-2way-project/gradle.properties‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
mlAppName=2way-ssl
2+
3+
mlHost=localhost
4+
mlRestPort=8180
5+
6+
# This username must be the CN in the client certificate
7+
mlUsername=<client user>
8+
mlPassword=<client password>
9+
10+
# Use this for 1-way SSL with no server cert validation and no hostname verification
11+
#mlSimpleSsl=true
12+
13+
# If this is set, additional SSL configuration will be done
14+
# This needs to be a JKS created with the keytool utility
15+
mlKeystore=<keystore file>
16+
mlKeystorePassword=<password>
17+
18+
# This is the password on the client cert. If not set, the mlKeystorePassword will be used
19+
#mlKeystoreCertPassword=<password>
20+
21+
# If this is true, the CA that signed the server cert must be in the specified keystore
22+
mlValidateServerCert=false
23+
24+
# If this is true, the CN in server cert needs to match the hostname used to connect
25+
# (the mlHost parameter above)
26+
mlVerifyServerHostname=false

‎examples/ssl-2way-project/gradle/wrapper/gradle-wrapper.jar‎

53.5 KB
Binary file not shown.

‎examples/ssl-2way-project/gradle/wrapper/gradle-wrapper.properties‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#Mon Oct 30 21:26:19 EDT 2017
2+
distributionBase=GRADLE_USER_HOME
3+
distributionPath=wrapper/dists
4+
zipStoreBase=GRADLE_USER_HOME
5+
zipStorePath=wrapper/dists
6+
distributionUrl=https\://services.gradle.org/distributions/gradle-3.5-bin.zip

‎examples/ssl-2way-project/gradlew‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
#!/usr/bin/env sh
2+
3+
##############################################################################
4+
##
5+
## Gradle start up script for UN*X
6+
##
7+
##############################################################################
8+
9+
# Attempt to set APP_HOME
10+
# Resolve links: $0 may be a link
11+
PRG="$0"
12+
# Need this for relative symlinks.
13+
while [ -h "$PRG" ] ; do
14+
ls=`ls -ld "$PRG"`
15+
link=`expr "$ls" : '.*-> \(.*\)$'`
16+
if expr "$link" : '/.*' > /dev/null; then
17+
PRG="$link"
18+
else
19+
PRG=`dirname "$PRG"`"/$link"
20+
fi
21+
done
22+
SAVED="`pwd`"
23+
cd "`dirname \"$PRG\"`/" >/dev/null
24+
APP_HOME="`pwd -P`"
25+
cd "$SAVED" >/dev/null
26+
27+
APP_NAME="Gradle"
28+
APP_BASE_NAME=`basename "$0"`
29+
30+
# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
31+
DEFAULT_JVM_OPTS=""
32+
33+
# Use the maximum available, or set MAX_FD != -1 to use that value.
34+
MAX_FD="maximum"
35+
36+
warn ( ) {
37+
echo "$*"
38+
}
39+
40+
die ( ) {
41+
echo
42+
echo "$*"
43+
echo
44+
exit 1
45+
}
46+
47+
# OS specific support (must be 'true' or 'false').
48+
cygwin=false
49+
msys=false
50+
darwin=false
51+
nonstop=false
52+
case "`uname`" in
53+
CYGWIN* )
54+
cygwin=true
55+
;;
56+
Darwin* )
57+
darwin=true
58+
;;
59+
MINGW* )
60+
msys=true
61+
;;
62+
NONSTOP* )
63+
nonstop=true
64+
;;
65+
esac
66+
67+
CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
68+
69+
# Determine the Java command to use to start the JVM.
70+
if [ -n "$JAVA_HOME" ] ; then
71+
if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
72+
# IBM's JDK on AIX uses strange locations for the executables
73+
JAVACMD="$JAVA_HOME/jre/sh/java"
74+
else
75+
JAVACMD="$JAVA_HOME/bin/java"
76+
fi
77+
if [ ! -x "$JAVACMD" ] ; then
78+
die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
79+
80+
Please set the JAVA_HOME variable in your environment to match the
81+
location of your Java installation."
82+
fi
83+
else
84+
JAVACMD="java"
85+
which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
86+
87+
Please set the JAVA_HOME variable in your environment to match the
88+
location of your Java installation."
89+
fi
90+
91+
# Increase the maximum file descriptors if we can.
92+
if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
93+
MAX_FD_LIMIT=`ulimit -H -n`
94+
if [ $? -eq 0 ] ; then
95+
if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
96+
MAX_FD="$MAX_FD_LIMIT"
97+
fi
98+
ulimit -n $MAX_FD
99+
if [ $? -ne 0 ] ; then
100+
warn "Could not set maximum file descriptor limit: $MAX_FD"
101+
fi
102+
else
103+
warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
104+
fi
105+
fi
106+
107+
# For Darwin, add options to specify how the application appears in the dock
108+
if $darwin; then
109+
GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
110+
fi
111+
112+
# For Cygwin, switch paths to Windows format before running java
113+
if $cygwin ; then
114+
APP_HOME=`cygpath --path --mixed "$APP_HOME"`
115+
CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
116+
JAVACMD=`cygpath --unix "$JAVACMD"`
117+
118+
# We build the pattern for arguments to be converted via cygpath
119+
ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
120+
SEP=""
121+
for dir in $ROOTDIRSRAW ; do
122+
ROOTDIRS="$ROOTDIRS$SEP$dir"
123+
SEP="|"
124+
done
125+
OURCYGPATTERN="(^($ROOTDIRS))"
126+
# Add a user-defined pattern to the cygpath arguments
127+
if [ "$GRADLE_CYGPATTERN" != "" ] ; then
128+
OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
129+
fi
130+
# Now convert the arguments - kludge to limit ourselves to /bin/sh
131+
i=0
132+
for arg in "$@" ; do
133+
CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
134+
CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option
135+
136+
if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition
137+
eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
138+
else
139+
eval `echo args$i`="\"$arg\""
140+
fi
141+
i=$((i+1))
142+
done
143+
case $i in
144+
(0) set -- ;;
145+
(1) set -- "$args0" ;;
146+
(2) set -- "$args0" "$args1" ;;
147+
(3) set -- "$args0" "$args1" "$args2" ;;
148+
(4) set -- "$args0" "$args1" "$args2" "$args3" ;;
149+
(5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
150+
(6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
151+
(7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
152+
(8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
153+
(9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
154+
esac
155+
fi
156+
157+
# Escape application args
158+
save ( ) {
159+
for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
160+
echo " "
161+
}
162+
APP_ARGS=$(save "$@")
163+
164+
# Collect all arguments for the java command, following the shell quoting and substitution rules
165+
eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS"
166+
167+
# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
168+
if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then
169+
cd "$(dirname "$0")"
170+
fi
171+
172+
exec "$JAVACMD" "$@"

0 commit comments

Comments
 (0)