Added test for two-way SSL.

Made a couple of small improvements to how errors are reported for a couple of the scenarios in this test too.

Author: rjrudin

marklogic-client-api/src/main/java/com/marklogic/client/impl/OkHttpServices.java

@@ -185,6 +185,14 @@ private FailedRequest extractErrorFields(Response response) {
 				failure.setStatusString("Forbidden");
 				failure.setStatusCode(STATUS_FORBIDDEN);
 				return failure;
+			} else if (response.code() == STATUS_FORBIDDEN && "".equals(responseBody)) {
+				// When the responseBody is empty, this seems preferable vs the "Server (not a REST instance?)" message
+				// which is very confusing given that the app server usually is a REST instance.
+				FailedRequest failure = new FailedRequest();
+				failure.setMessageString("No message received from server.");
+				failure.setStatusString("Forbidden");
+				failure.setStatusCode(STATUS_FORBIDDEN);
+				return failure;
 			}
 
 			InputStream is = new ByteArrayInputStream(responseBody.getBytes(StandardCharsets.UTF_8));
@@ -515,6 +523,13 @@ private Response sendRequestOnce(Request request) {
     try {
       return getConnection().newCall(request).execute();
     } catch (IOException e) {
+		if (e instanceof SSLException) {
+			String message = e.getMessage();
+			if (message != null && message.contains("readHandshakeRecord")) {
+				throw new MarkLogicIOException(String.format("SSL error occurred: %s; ensure you are using a valid certificate " +
+					"if the MarkLogic app server requires a client certificate for SSL.", message));
+			}
+		}
 		String message = String.format(
 			"Error occurred while calling %s; %s: %s " +
 				"; possible reasons for the error include that a MarkLogic app server may not be listening on the port, " +

marklogic-client-api/src/test/java/com/marklogic/client/test/TwoWaySSLTest.java

@@ -0,0 +1,330 @@
+package com.marklogic.client.test;
+
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.marklogic.client.DatabaseClient;
+import com.marklogic.client.DatabaseClientFactory;
+import com.marklogic.client.ForbiddenUserException;
+import com.marklogic.client.MarkLogicIOException;
+import com.marklogic.client.document.DocumentDescriptor;
+import com.marklogic.client.eval.EvalResultIterator;
+import com.marklogic.client.io.StringHandle;
+import com.marklogic.client.test.junit5.RequireSSLExtension;
+import com.marklogic.mgmt.ManageClient;
+import com.marklogic.mgmt.resource.appservers.ServerManager;
+import com.marklogic.rest.util.Fragment;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.api.io.TempDir;
+import org.springframework.util.FileCopyUtils;
+
+import javax.net.ssl.KeyManagerFactory;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.X509TrustManager;
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.file.Path;
+import java.security.KeyStore;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.function.Consumer;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+@ExtendWith(RequireSSLExtension.class)
+public class TwoWaySSLTest {
+
+	// Used for creating a temporary JKS (Java KeyStore) file.
+	@TempDir
+	Path tempDir;
+
+	private DatabaseClient securityClient;
+	private ManageClient manageClient;
+	private File keyStoreFile;
+
+
+	@BeforeEach
+	void setup() throws Exception {
+		// Create a client using the java-unittest app server - which requires SSL via RequiresSSLExtension - and that
+		// talks to the Security database.
+		securityClient = Common.newClientBuilder()
+			.withUsername(Common.SERVER_ADMIN_USER).withPassword(Common.SERVER_ADMIN_PASS)
+			.withSSLProtocol("TLSv1.2")
+			.withTrustManager(Common.TRUST_ALL_MANAGER)
+			.withSSLHostnameVerifier(DatabaseClientFactory.SSLHostnameVerifier.ANY)
+			.withDatabase("Security").build();
+
+		final String certificateAuthorityId = createCertificateAuthority();
+		ClientCertificate clientCertificate = createClientCertificate();
+		makeAppServerRequireTwoWaySSL(certificateAuthorityId);
+
+		writeClientCertificateFilesToTempDir(clientCertificate, tempDir);
+		createPkcs12File(tempDir);
+		createKeystoreFile(tempDir);
+		keyStoreFile = new File(tempDir.toFile(), "client.jks");
+	}
+
+	@AfterEach
+	void teardown() {
+		removeTwoWaySSLConfig();
+		deleteCertificateAuthority();
+	}
+
+	/**
+	 * After two-way SSL is configured on the java-unittest app server, verify that a DatabaseClient using a proper
+	 * SSLContext can connect to the app server.
+	 */
+	@Test
+	void testTwoWaySSL() throws Exception {
+		if (Common.USE_REVERSE_PROXY_SERVER) {
+			return;
+		}
+
+		final String uri = "/optic/test/musician1.json";
+
+		// This client uses our Java KeyStore file with a client certificate in it, so it should work.
+		DatabaseClient clientWithCert = Common.newClientBuilder()
+			.withSSLHostnameVerifier(DatabaseClientFactory.SSLHostnameVerifier.ANY)
+			.withSSLContext(createSSLContextWithClientCertificate(keyStoreFile))
+			.withTrustManager(RequireSSLExtension.newTrustManager())
+			.build();
+
+		DocumentDescriptor descriptor = clientWithCert.newJSONDocumentManager().exists(uri);
+		assertNotNull(descriptor);
+		assertEquals(uri, descriptor.getUri());
+
+		// This client uses a new SSL context without the client certificate, so it should fail.
+		DatabaseClient clientWithoutCert = Common.newClientBuilder()
+			.withSSLHostnameVerifier(DatabaseClientFactory.SSLHostnameVerifier.ANY)
+			.withSSLProtocol("TLSv1.2")
+			.withTrustManager(RequireSSLExtension.newTrustManager())
+			.build();
+
+		MarkLogicIOException ex = assertThrows(MarkLogicIOException.class,
+			() -> clientWithoutCert.newJSONDocumentManager().exists(uri));
+		assertTrue(ex.getMessage().contains("SSL error occurred: readHandshakeRecord; ensure you are using a " +
+				"valid certificate if the MarkLogic app server requires a client certificate for SSL."),
+			"Unexpected exception: " + ex.getMessage());
+
+		// And now a client that doesn't even try to use SSL. It's not clear if a ForbiddenUserException is correct
+		// here, but it's what the Java Client was throwing when this test was written.
+		ForbiddenUserException userException = assertThrows(ForbiddenUserException.class,
+			() -> Common.newClient().newJSONDocumentManager().exists(uri));
+		assertTrue(userException.getMessage().contains("User is not allowed to check the existence of documents"),
+			"Unexpected exception: " + userException.getMessage());
+	}
+
+	private SSLContext createSSLContextWithClientCertificate(File keystoreFile) throws Exception {
+		KeyStore keyStore = KeyStore.getInstance("JKS");
+		keyStore.load(new FileInputStream(keystoreFile), "password".toCharArray());
+		KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance("SunX509");
+		keyManagerFactory.init(keyStore, "password".toCharArray());
+		SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
+		sslContext.init(
+			keyManagerFactory.getKeyManagers(),
+			new X509TrustManager[]{RequireSSLExtension.newTrustManager()},
+			null);
+		return sslContext;
+	}
+
+	/**
+	 * See https://docs.marklogic.com/pki:create-authority for more information. This results in both a new
+	 * CA in MarkLogic and a new "secure credential".
+	 */
+	private String createCertificateAuthority() {
+		String xquery = "xquery version \"1.0-ml\";\n" +
+			"import module namespace pki = \"http://marklogic.com/xdmp/pki\" at \"/MarkLogic/pki.xqy\";\n" +
+			"declare namespace x509 = \"http://marklogic.com/xdmp/x509\";\n" +
+			"\n" +
+			"pki:create-authority(\n" +
+			"  \"java-client-test\", \"Java Client Certificate Authority\",\n" +
+			"  element x509:subject {\n" +
+			"    element x509:countryName            {\"US\"},\n" +
+			"    element x509:stateOrProvinceName    {\"California\"},\n" +
+			"    element x509:localityName           {\"San Carlos\"},\n" +
+			"    element x509:organizationName       {\"MarkLogicJavaClientTest\"},\n" +
+			"    element x509:organizationalUnitName {\"Engineering\"},\n" +
+			"    element x509:commonName             {\"JavaClientCA\"},\n" +
+			"    element x509:emailAddress           {\"java-client@example.org\"}\n" +
+			"  },\n" +
+			"  fn:current-dateTime(),\n" +
+			"  fn:current-dateTime() + xs:dayTimeDuration(\"P365D\"),\n" +
+			"  (xdmp:permission(\"admin\",\"read\")))";
+
+		return securityClient.newServerEval().xquery(xquery).evalAs(String.class);
+	}
+
+	/**
+	 * See https://docs.marklogic.com/pki:authority-create-client-certificate for more information.
+	 */
+	private ClientCertificate createClientCertificate() {
+		String xquery = "xquery version \"1.0-ml\";\n" +
+			"import module namespace sec = \"http://marklogic.com/xdmp/security\" at \"/MarkLogic/security.xqy\"; \n" +
+			"import module namespace pki = \"http://marklogic.com/xdmp/pki\" at \"/MarkLogic/pki.xqy\";\n" +
+			"declare namespace x509 = \"http://marklogic.com/xdmp/x509\";\n" +
+			"\n" +
+			"pki:authority-create-client-certificate(\n" +
+			"  xdmp:credential-id(\"java-client-test\"),\n" +
+			"  element x509:subject {\n" +
+			"    element x509:countryName            {\"US\"},\n" +
+			"    element x509:stateOrProvinceName    {\"California\"},\n" +
+			"    element x509:localityName           {\"San Carlos\"},\n" +
+			"    element x509:organizationName       {\"ProgressMarkLogic\"},\n" +
+			"    element x509:organizationalUnitName {\"Engineering\"},\n" +
+			"    element x509:commonName             {\"ElmerFudd\"},\n" +
+			"    element x509:emailAddress           {\"elmer.fudd@example.org\"}\n" +
+			"  },\n" +
+			"  fn:current-dateTime(),\n" +
+			"  fn:current-dateTime() + xs:dayTimeDuration(\"P365D\"))\n";
+
+		EvalResultIterator iter = securityClient.newServerEval().xquery(xquery).eval();
+		String cert = null;
+		String key = null;
+		while (iter.hasNext()) {
+			if (cert == null) {
+				cert = iter.next().getString();
+			} else {
+				key = iter.next().getString();
+			}
+		}
+		return new ClientCertificate(cert, key);
+	}
+
+	private static class ClientCertificate {
+		final String pemEncodedCertificate;
+		final String privateKey;
+
+		public ClientCertificate(String pemEncodedCertificate, String privateKey) {
+			this.pemEncodedCertificate = pemEncodedCertificate;
+			this.privateKey = privateKey;
+		}
+	}
+
+	/**
+	 * Via the RequiresSSLExtension, the app server already requires a 1-way SSL connection. This configures the
+	 * app server to both require a client certificate and have that client certificate associated with the
+	 * CA that was created earlier in the test.
+	 */
+	private void makeAppServerRequireTwoWaySSL(String certificateAuthorityId) {
+		String certificateAuthorityCertificate = getCertificateAuthorityCertificate(certificateAuthorityId);
+
+		manageClient = Common.newManageClient();
+		ObjectNode payload = Common.newServerPayload()
+			.put("ssl-require-client-certificate", true)
+			.put("ssl-client-issuer-authority-verification", true);
+		payload.putArray("ssl-client-certificate-pem").add(certificateAuthorityCertificate);
+		new ServerManager(manageClient).save(payload.toString());
+	}
+
+	/**
+	 * Couldn't find a Manage API endpoint that returns the CA certificate, so directly accessing the Security
+	 * database and reading a known URI to get an XML document associated with the CA's secure credential, which has
+	 * the certificate in it.
+	 */
+	private String getCertificateAuthorityCertificate(String certificateAuthorityId) {
+		String certificateUri = String.format("http://marklogic.com/xdmp/credentials/%s", certificateAuthorityId);
+		String xml = securityClient.newXMLDocumentManager().read(certificateUri, new StringHandle()).get();
+		return new Fragment(xml).getElementValue("/sec:credential/sec:credential-certificate");
+	}
+
+	private void deleteCertificateAuthority() {
+		String xquery = "xquery version \"1.0-ml\";\n" +
+			"import module namespace pki = \"http://marklogic.com/xdmp/pki\" at \"/MarkLogic/pki.xqy\";\n" +
+			"\n" +
+			"pki:delete-authority(\"java-client-test\")";
+
+		securityClient.newServerEval().xquery(xquery).evalAs(String.class);
+	}
+
+	/**
+	 * Restores the app server back to only requiring 1-way SSL.
+	 */
+	private void removeTwoWaySSLConfig() {
+		ObjectNode payload = Common.newServerPayload()
+			.put("ssl-require-client-certificate", false)
+			.put("ssl-client-issuer-authority-verification", false);
+		payload.putArray("ssl-client-certificate-pem");
+		new ServerManager(manageClient).save(payload.toString());
+	}
+
+	/**
+	 * Writes the client certificate PEM and private keys to disk so that they can accessed by the openssl program.
+	 *
+	 * @param clientCertificate
+	 * @param tempDir
+	 * @throws IOException
+	 */
+	private void writeClientCertificateFilesToTempDir(ClientCertificate clientCertificate, Path tempDir) throws IOException {
+		File certFile = new File(tempDir.toFile(), "cert.pem");
+		FileCopyUtils.copy(clientCertificate.pemEncodedCertificate.getBytes(), certFile);
+		File keyFile = new File(tempDir.toFile(), "client.key");
+		FileCopyUtils.copy(clientCertificate.privateKey.getBytes(), keyFile);
+	}
+
+	/**
+	 * See https://stackoverflow.com/a/8224863/3306099 for where this approach was obtained from.
+	 */
+	private void createPkcs12File(Path tempDir) throws Exception {
+		ProcessBuilder builder = new ProcessBuilder();
+		builder.directory(tempDir.toFile());
+		builder.command("openssl", "pkcs12", "-export",
+			"-in", "cert.pem", "-inkey", "client.key",
+			"-out", "client.p12",
+			"-name", "my-client",
+			"-passout", "pass:password");
+
+		ExecutorService executorService = Executors.newSingleThreadExecutor();
+		Process process = builder.start();
+		executorService.submit(new StreamGobbler(process.getInputStream(), System.out::println));
+		executorService.submit(new StreamGobbler(process.getErrorStream(), System.err::println));
+		int exitCode = process.waitFor();
+		assertEquals(0, exitCode, "Unable to create pkcs12 file using openssl");
+	}
+
+	private void createKeystoreFile(Path tempDir) throws Exception {
+		ProcessBuilder builder = new ProcessBuilder();
+		builder.directory(tempDir.toFile());
+		builder.command("keytool", "-importkeystore",
+			"-deststorepass", "password",
+			"-destkeypass", "password",
+			"-destkeystore", "client.jks",
+			"-srckeystore", "client.p12",
+			"-srcstoretype", "PKCS12",
+			"-srcstorepass", "password",
+			"-alias", "my-client");
+
+		Process process = builder.start();
+		ExecutorService executorService = Executors.newSingleThreadExecutor();
+		executorService.submit(new StreamGobbler(process.getInputStream(), System.out::println));
+		executorService.submit(new StreamGobbler(process.getErrorStream(), System.err::println));
+		int exitCode = process.waitFor();
+		assertEquals(0, exitCode, "Unable to create keystore using keytool");
+	}
+
+	/**
+	 * Copied from https://www.baeldung.com/run-shell-command-in-java .
+	 */
+	private static class StreamGobbler implements Runnable {
+		private InputStream inputStream;
+		private Consumer<String> consumer;
+
+		public StreamGobbler(InputStream inputStream, Consumer<String> consumer) {
+			this.inputStream = inputStream;
+			this.consumer = consumer;
+		}
+
+		@Override
+		public void run() {
+			new BufferedReader(new InputStreamReader(inputStream)).lines()
+				.forEach(consumer);
+		}
+	}
+}