MockServer uses port unification to simplify the configuration so all protocols (i.e. HTTP, HTTPS / SSL, SOCKS, etc) are supported on the same port. This means when a request is sent over TLS (i.e. an HTTPS request) MockServer dynamically detects that the request is encrypted.

MockServer has support for TLS (i.e. HTTPS) in three areas:

  • TLS for inbound connections to support HTTPS for mocking, proxying and control-plane interactions (creating expectations, retrieving logs, etc)
  • mTLS for inbound connections (also called client authentication or two-way TLS) to authenticate any client sending HTTPS requests
  • TLS for outbound connections (also called forward proxy TLS) to authenticate any client sending HTTPS requests

MockServer HTTPS & TLS

The majority of HTTP clients perform the following steps when making an HTTPS request:

  1. establish TCP connection to remote server
  2. perform TLS handshake with remote server and verify trust chain by receiving remote server X.509 Certificate and verifying it is signed by a known Certificate Authority
  3. perform hostname validation by comparing hostname (or IP address) of remote server with Subject Alternative Name (SAN) or Common Name (CN) on X.509

MockServer is able to mock the behaviour of multiple hostnames (i.e. servers) and present a valid X.509 Certificates for them. MockServer achieves this by dynamically generating its X.509 Certificate using an in-memory list of hostnames and ip addresses, this is described in more detail below.

It is important to ensure that any client calling MockServer over TLS trust MockServer as a Certificate Authority (CA) (i.e. trust the MockServer CA X.509) the different approaches to establishing this trust is described below.

MockServer provides multiple ways its TLS can be configured. The following things can be configured:

 

Ensure MockServer Certificates Are Trusted

The MockServer CA X.509 must be considered a valid trust root to ensure MockServer's dynamically generate X.509 certificates are trusted by an HTTP Client. This means the CA X.509 needs to be added into the JVM, HTTP Client or operating system as appropriate.

The MockServer CA X.509 can be found (in PEM format) in the MockServer github repo or can be loaded from the classpath location /org/mockserver/socket/CertificateAuthorityCertificate.pem

Operating System

It is possible to add the MockServer CA X.509 as a trusted root CA to your operating system, this will make most clients applications running on your OS (such as browsers) trust dynamically generated certificates from MockServer.

This is only an acceptable risk if it is done for a short period and the configuration setting dynamicallyCreateCertificateAuthorityCertificate is enabled to generate a local unique CA X.509 and Private Key that is saved to your local disk in the folder configured using directoryToSaveDynamicSSLCertificate.

If the configuration setting dynamicallyCreateCertificateAuthorityCertificate is not enabled, and your OS trusts the MockServer CA X.509, then this would leave your machine open to man-in-the-middle attacks because the corresponding Private Key is in the MockServer github repository. This would allow hackers to compromise all sensitive communicates such as to your bank or other sensitive sites.

Web Browsers

Browsers (such as Chrome, Firefox or IE) may not always trust dynamically generated certificates from MockServer because of Certificate Transparency and Public Key Pinning both of which make it hard to dynamically generate certificates that are trusted.

Some sites will work but others (such as google sites) won't work due to certificate pinning.

Browser that rely on Certificate Transparency will likely not trust dynamically generated certificates from MockServer

Java via Classpath

The following code shows how to load a file from the classpath or a relative filesystem location:

public void doSomething() {
    String mockServerCA = loadFileFromLocation("/org/mockserver/socket/CertificateAuthorityCertificate.pem");
}

public String loadFileFromLocation(String location) {
    location = location.trim().replaceAll("\\\\", "/");

    Path path;
    if (location.toLowerCase().startsWith("file:")) {
        path = Paths.get(URI.create(location));
    } else {
        path = Paths.get(location);
    }

    if (Files.exists(path)) {
        // org.apache.commons.io.FileUtils
        return FileUtils.readFileToString(path.toFile(), "UTF-8");
    } else {
        return loadFileFromClasspath(location);
    }
}

private String loadFileFromClasspath(String location) {
    InputStream inputStream = this.getClass().getResourceAsStream(location);

    if (inputStream == null) {
        inputStream = this.getClass().getClassLoader().getResourceAsStream(location);
    }

    if (inputStream == null) {
        inputStream = ClassLoader.getSystemResourceAsStream(location);
    }

    if (inputStream != null) {
        try {
            // org.apache.commons.io.IOUtils
            return IOUtils.toString(inputStream, Charsets.UTF_8);
        } catch (IOException e) {
            throw new RuntimeException("Could not read " + location + " from the classpath", e);
        }
    }

    throw new RuntimeException("Could not find " + location + " on the classpath");
}

Java DefaultSSLSocketFactory

Another mechanism to ensure the MockServer X.509 is trusted is to configure the DefaultSSLSocketFactory in the JVM using the following line:

HttpsURLConnection.setDefaultSSLSocketFactory(new KeyStoreFactory(new MockServerLogger()).sslContext().getSocketFactory());

This can be used in a test case, as follows:

import org.junit.AfterClass;
import org.junit.BeforeClass;
import org.junit.Test;
import org.mockserver.integration.ClientAndServer;
import org.mockserver.logging.MockServerLogger;
import org.mockserver.socket.PortFactory;
import org.mockserver.socket.tls.KeyStoreFactory;

import javax.net.ssl.HttpsURLConnection;

public class ExampleTestClass {

    private static ClientAndServer mockServer;

    @BeforeClass
    public static void startMockServer() {
        // ensure all connection using HTTPS will use the SSL context defined by
        // MockServer to allow dynamically generated certificates to be accepted
        HttpsURLConnection.setDefaultSSLSocketFactory(new KeyStoreFactory(new MockServerLogger()).sslContext().getSocketFactory());
        mockServer = ClientAndServer.startClientAndServer(PortFactory.findFreePort());
    }

    @AfterClass
    public static void stopMockServer() {
        mockServer.stop();
    }

    @Test
    public void shouldDoSomething() {
        // test system
    }
}

Java Keytool

The Java keytool command can also be used to add the MockServer CA X.509 certificate to the list of trust CA Certificates for a JVM, as follows:

keytool -import -v -keystore /usr/lib/jvm/java-8-openjdk-amd64/jre/lib/security/cacerts -alias mockserver-ca -file CertificateAuthorityCertificate.pem -storepass changeit -trustcacerts -noprompt

An example bash script showing how this can be done can be found in the MockServer github repo

 

Hostname Validation

MockServer is able to mock the behaviour of multiple hostnames (i.e. servers) and present a valid X.509 Certificates for them. MockServer achieves this by dynamically generating its X.509 Certificate using an in-memory list of hostnames and ip addresses. When the list of hostnames or ips addresses changes a new certificate is generated. The list of hostnames is updated, when:

  • configuration for SAN hostnames or SAN IP addresses is specified
  • an expectation is added containing a Host header with a hostname not seen before
  • a request is received containing a Host header with a hostname not seen before
  • a TLS handshake using Server Name Indication (SNI) with a hostname not seen before

Note: if a request is received with a Host header for a hostname not seen before the first request will fail validation because the TLS connection has already been established before the Host header can be read, any subsequent requests with that hostname will pass hostname validation.

   

TLS Configuration:

The following diagram shows where TLS/mTLS configuration settings are used:

MockServer HTTPS & TLS

 

Inbound TLS (for Received Requests)

Dynamic Inbound Certificate Authority X.509 & Private Key

Enable dynamic creation of Certificate Authority X.509 Certificate and Private Key

Enable this property to increase the security of trusting the MockServer Certificate Authority X.509 by ensuring a local dynamic value is used instead of the public value in the MockServer git repo.

These PEM files will be created and saved in the directory specified with configuration property directoryToSaveDynamicSSLCertificate.

A Certificate Authority X.509 Certificate and Private Key will only be created if the files used to save them are not already present. Therefore, if MockServer is re-started multiple times with the same value for directoryToSaveDynamicSSLCertificate. the Certificate Authority X.509 Certificate and Private Key will only be created once.

Type: boolean Default: false

Java Code:

ConfigurationProperties.dynamicallyCreateCertificateAuthorityCertificate(boolean enable)

System Property:

-Dmockserver.dynamicallyCreateCertificateAuthorityCertificate=...

Environment Variable:

MOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATE=...

Property File:

mockserver.dynamicallyCreateCertificateAuthorityCertificate=...

Example:

-Dmockserver.dynamicallyCreateCertificateAuthorityCertificate="true"

Directory used to save the dynamically generated Certificate Authority X.509 Certificate and Private Key.

This directory will only be used if MockServer is configured to create a dynamic Certificate Authority X.509 certificate and private key using dynamicallyCreateCertificateAuthorityCertificate.

Type: string Default: null

Java Code:

ConfigurationProperties.directoryToSaveDynamicSSLCertificate(String directoryToSaveDynamicSSLCertificate)

System Property:

-Dmockserver.directoryToSaveDynamicSSLCertificate=...

Environment Variable:

MOCKSERVER_CERTIFICATE_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATE=...

Property File:

mockserver.directoryToSaveDynamicSSLCertificate=...

Example:

-Dmockserver.directoryToSaveDynamicSSLCertificate="/some/existing/path"

Fixed (i.e. Custom) Inbound Certificate Authority X.509 & Private Key

Location of custom file for Certificate Authority for TLS, the private key must be a PKCS#8 PEM file and must match the TLS Certificate Authority X.509 Certificate.

To convert a PKCS#1 PEM file (i.e. default for Bouncy Castle) to a PKCS#8 PEM file the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt

Type: string Default: null

Java Code:

ConfigurationProperties.certificateAuthorityPrivateKey(String certificateAuthorityPrivateKey)

System Property:

-Dmockserver.certificateAuthorityPrivateKey=...

Environment Variable:

MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY=...

Property File:

mockserver.certificateAuthorityPrivateKey=...

Example:

-Dmockserver.certificateAuthorityPrivateKey="true"

Location of custom file for Certificate Authority for TLS, the certificate must be a X.509 PEM file and must match the TLS Certificate Authority Private Key.

Type: string Default: null

Java Code:

ConfigurationProperties.certificateAuthorityCertificate(String certificateAuthorityCertificate)

System Property:

-Dmockserver.certificateAuthorityCertificate=...

Environment Variable:

MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE=...

Property File:

mockserver.certificateAuthorityCertificate=...

Example:

-Dmockserver.certificateAuthorityCertificate="true"

Dynamic Inbound Private Key & X.509

MockServer dynamically updates the Subject Alternative Name (SAN) values for its TLS certificate to add domain names and IP addresses from request Host headers and Host headers in expectations, this configuration setting disables this automatic update and only uses SAN value provided in TLS Subject Alternative Name Domains and TLS Subject Alternative Name IPs configuration properties.

When this property is enabled the generated X.509 Certificate and Private Key pair are saved to the directoryToSaveDynamicSSLCertificate as Certificate.pem and PKCS8PrivateKey.pem

Type: boolean Default: false

Java Code:

ConfigurationProperties.preventCertificateDynamicUpdate(boolean prevent)

System Property:

-Dmockserver.preventCertificateDynamicUpdate=...

Environment Variable:

MOCKSERVER_PREVENT_CERTIFICATE_DYNAMIC_UPDATE=...

Property File:

mockserver.preventCertificateDynamicUpdate=...

Example:

-Dmockserver.preventCertificateDynamicUpdate="true"

The domain name for auto-generate TLS certificates

Type: string Default: localhost

Java Code:

ConfigurationProperties.sslCertificateDomainName(String domainName)

System Property:

-Dmockserver.sslCertificateDomainName=...

Environment Variable:

MOCKSERVER_SSL_CERTIFICATE_DOMAIN_NAME=...

Property File:

mockserver.sslCertificateDomainName=...

Example:

-Dmockserver.sslCertificateDomainName="localhost"

The Subject Alternative Name (SAN) domain names for auto-generate TLS certificates as a comma separated list

Type: string Default: localhost

Java Code:

ConfigurationProperties.addSslSubjectAlternativeNameDomains(String... additionalSubjectAlternativeNameDomains)
or
ConfigurationProperties.clearSslSubjectAlternativeNameDomains()

System Property:

-Dmockserver.sslSubjectAlternativeNameDomains=...

Environment Variable:

MOCKSERVER_SSL_SUBJECT_ALTERNATIVE_NAME_DOMAINS=...

Property File:

mockserver.sslSubjectAlternativeNameDomains=...

Example:

-Dmockserver.sslSubjectAlternativeNameDomains="localhost,www.foo.bar"

The Subject Alternative Name (SAN) IP addresses for auto-generate TLS certificates as a comma separated list

Type: string Default: 127.0.0.1,0.0.0.0

Java Code:

ConfigurationProperties.addSslSubjectAlternativeNameIps(String... additionalSubjectAlternativeNameIps)
or
ConfigurationProperties.clearSslSubjectAlternativeNameIps()

System Property:

-Dmockserver.sslSubjectAlternativeNameIps=...

Environment Variable:

MOCKSERVER_SSL_SUBJECT_ALTERNATIVE_NAME_IPS=...

Property File:

mockserver.sslSubjectAlternativeNameIps=...

Example:

-Dmockserver.sslSubjectAlternativeNameIps="127.0.0.1,0.0.0.0"

Fixed (i.e. Custom) Inbound Private Key & X.509

File location of a fixed custom private key for TLS connections into MockServer.

The private key must be a PKCS#8 PEM file and must be the private key corresponding to the x509CertificatePath X.509 (public key) configuration.

The certificateAuthorityCertificate configuration must be the Certificate Authority for the corresponding X.509 certificate (i.e. able to valid its signature), see: x509CertificatePath.

To convert a PKCS#1 (i.e. default for Bouncy Castle) to a PKCS#8 the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt

This configuration will be ignored unless x509CertificatePath is also set.

Type: string Default: null

Java Code:

ConfigurationProperties.privateKeyPath(String privateKeyPath)

System Property:

-Dmockserver.privateKeyPath=...

Environment Variable:

MOCKSERVER_TLS_PRIVATE_KEY_PATH=...

Property File:

mockserver.privateKeyPath=...

Example:

-Dmockserver.privateKeyPath="/some/existing/path"

File location of a fixed custom X.509 Certificate for TLS connections into MockServer

The certificate must be a X.509 PEM file and must be the public key corresponding to the privateKeyPath private key configuration.

The certificateAuthorityCertificate configuration must be the Certificate Authority for this certificate (i.e. able to valid its signature).

This configuration will be ignored unless privateKeyPath is also set.

Type: string Default: null

Java Code:

ConfigurationProperties.x509CertificatePath(String x509CertificatePath)

System Property:

-Dmockserver.x509CertificatePath=...

Environment Variable:

MOCKSERVER_TLS_X509_CERTIFICATE_PATH=...

Property File:

mockserver.x509CertificatePath=...

Example:

-Dmockserver.x509CertificatePath="/some/existing/path"

Inbound mTLS Client Authentication (for Received Requests)

Require mTLS (also called client authentication and two-way TLS) for all TLS connections / HTTPS requests to MockServer

Type: boolean Default: false

Java Code:

ConfigurationProperties.tlsMutualAuthenticationRequired(boolean enable)

System Property:

-Dmockserver.tlsMutualAuthenticationRequired=...

Environment Variable:

MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.tlsMutualAuthenticationRequired=...

Example:

-Dmockserver.tlsMutualAuthenticationRequired="true"

File location of custom mTLS (TLS client authentication) X.509 Certificate Chain for Trusting (i.e. signature verification of) Client X.509 Certificates, the certificate chain must be a X.509 PEM file.

This certificate chain will be used if MockServer performs mTLS (client authentication) for inbound TLS connections because tlsMutualAuthenticationRequired is enabled

This configuration property is also used for MockServerClient to trust outbound TLS X.509 certificates i.e. TLS connections to MockServer

Type: string Default: null

Java Code:

ConfigurationProperties.tlsMutualAuthenticationCertificateChain(String certificateChain)

System Property:

-Dmockserver.tlsMutualAuthenticationCertificateChain=...

Environment Variable:

MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=...

Property File:

mockserver.tlsMutualAuthenticationCertificateChain=...

Example:

-Dmockserver.tlsMutualAuthenticationCertificateChain="/some/existing/path"


 

Outbound Client TLS/mTLS (for Forwarded or Proxied Requests)

Configure trusted set of certificates for forwarded or proxied requests (i.e. TLS connections out of MockServer).

MockServer will only be able to establish a TLS connection to endpoints that have a trusted X.509 certificate according to the trust manager type, as follows:

  • ALL - Insecure will trust all X.509 certificates and not perform host name verification.
  • JVM - Will trust all X.509 certificates trust by the JVM.
  • CUSTOM - Will trust all X.509 certificates specified in forwardProxyTLSCustomTrustX509Certificates configuration value.

Type: string Default: ALL

Java Code:

ConfigurationProperties.forwardProxyTLSX509CertificatesTrustManagerType(String trustManagerType)

System Property:

-Dmockserver.forwardProxyTLSX509CertificatesTrustManagerType=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATES_TRUST_MANAGER_TYPE=...

Property File:

mockserver.forwardProxyTLSX509CertificatesTrustManagerType=...

Example:

-Dmockserver.forwardProxyTLSX509CertificatesTrustManagerType="CUSTOM"

Fixed (i.e. Custom) Outbound CA X.509, Private Key & X.509

File location of custom file for trusted X.509 Certificate Authority roots for forwarded or proxied requests (i.e. TLS connections out of MockServer), the certificate chain must be a X.509 PEM file.

MockServer will only be able to establish a TLS connection to endpoints that have an X.509 certificate chain that is signed by one of the provided custom certificates, i.e. where a path can be established from the endpoints X.509 certificate to one or more of the custom X.509 certificates provided.

This configuration only take effect if forwardProxyTLSX509CertificatesTrustManagerType is configured as CUSTOM otherwise this value is ignored.

Type: string Default: null

Java Code:

ConfigurationProperties.forwardProxyTLSCustomTrustX509Certificates(String customX509Certificates)

System Property:

-Dmockserver.forwardProxyTLSCustomTrustX509Certificates=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_TLS_CUSTOM_TRUST_X509_CERTIFICATES=...

Property File:

mockserver.forwardProxyTLSCustomTrustX509Certificates=...

Example:

-Dmockserver.forwardProxyTLSCustomTrustX509Certificates="/some/existing/path"

File location of custom Private Key for forwarded or proxied requests (i.e. TLS connections out of MockServer), the private key must be a PKCS#8 PEM file

To convert a PKCS#1 (i.e. default for Bouncy Castle) to a PKCS#8 the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt

This private key will be used if MockServer needs to perform mTLS (client authentication) for outbound TLS connections.

Type: string Default: null

Java Code:

ConfigurationProperties.forwardProxyPrivateKey(String privateKey)

System Property:

-Dmockserver.forwardProxyPrivateKey=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_TLS_PRIVATE_KEY=...

Property File:

mockserver.forwardProxyPrivateKey=...

Example:

-Dmockserver.forwardProxyPrivateKey="/some/existing/path"

File location of custom X.509 Certificate Chain for forwarded or proxied requests (i.e. TLS connections out of MockServer), the certificates must be a X.509 PEM file

This certificate chain will be used if MockServer needs to perform mTLS (client authentication) for outbound TLS connections.

Type: string Default: null

Java Code:

ConfigurationProperties.forwardProxyCertificateChain(String certificateChain)

System Property:

-Dmockserver.forwardProxyCertificateChain=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATE_CHAIN=...

Property File:

mockserver.forwardProxyCertificateChain=...

Example:

-Dmockserver.forwardProxyCertificateChain="/some/existing/path"
 

MockServer Client

File location of custom mTLS (TLS client authentication) X.509 Certificate Chain for Trusting (i.e. signature verification of) MockServer X.509 Certificates, the certificate chain must be a X.509 PEM file. This certificate chain will only be used if MockServerClient performs TLS to calls to MockServer.

This settings is particularly used when connecting to MockServer via a load-balancer or other TLS terminating network infrastructure with its own X.509 Certificate.

This configuration property is also used for MockServer to trust inbound mTLS client authentication X.509 certificates

Type: string Default: null

Java Code:

ConfigurationProperties.tlsMutualAuthenticationCertificateChain(String certificateChain)

System Property:

-Dmockserver.tlsMutualAuthenticationCertificateChain=...

Environment Variable:

MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=...

Property File:

mockserver.tlsMutualAuthenticationCertificateChain=...

Example:

-Dmockserver.tlsMutualAuthenticationCertificateChain="/some/existing/path"
 

Bouncy Castle

Use BouncyCastle instead of the Java JDK to X.509 Certificate creation, this is helpful if:

  • using the IBM JVM or
  • avoiding bugs in the X509 creation logic Java JDK (i.e. such as the format of SAN and CN)

When enabling this setting the following dependencies must be provided on the classpath (they are not included with MockServer)

<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk15on</artifactId>
  <version>1.65</version>
</dependency>
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcpkix-jdk15on</artifactId>
  <version>1.65</version>
</dependency>

Type: boolean Default: false

Java Code:

ConfigurationProperties.useBouncyCastleForKeyAndCertificateGeneration(boolean enable)

System Property:

-Dmockserver.useBouncyCastleForKeyAndCertificateGeneration=...

Environment Variable:

MOCKSERVER_USE_BOUNCY_CASTLE_FOR_KEY_AND_CERTIFICATE_GENERATION=...

Property File:

mockserver.useBouncyCastleForKeyAndCertificateGeneration=...

Example:

-Dmockserver.useBouncyCastleForKeyAndCertificateGeneration="true"