Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

Gatling supports HTTPS out of the box and is designed to work with virtually any server certificate configuration, including self-signed and custom Certificate Authority (CA) certificates. As a load testing tool rather than a security scanner, Gatling ships with a permissive TrustManager by default so you can test any server without trust configuration. When you need more control — such as mutual TLS with per-user certificates — Gatling exposes the full KeyManagerFactory configuration down to the individual virtual user level.

​
KeyManager and TrustManager

By default, Gatling uses:
  • The JVM’s default KeyManager.
  • A permissive TrustManager that trusts every server certificate, including self-signed ones and custom CA-issued certificates.
This permissive behavior means Gatling works out of the box with any server setup, which is the right default for a load testing tool focused on performance rather than security enforcement. To override this behavior — typically when your server requires mutual TLS (mTLS) and you must present a client certificate — edit the ssl block in gatling.conf:
gatling.conf (ssl block)
ssl {
  keyStore {
    type = ""        # JKS or PKCS12 (p12)
    file = ""        # path to keystore file
    password = ""
    algorithm = ""   # optional, defaults to SunX509
  }
  trustStore {
    type = ""
    file = ""
    password = ""
    algorithm = ""
  }
}
Gatling accepts keystore and truststore files in JKS and PKCS12 (p12) formats.

​
SSLContext per Virtual User

By default, each virtual user has its own SSLContext and SSLSession. This accurately models real browser traffic where every client maintains an independent TLS handshake state, ensuring your server deals with the proper number of TLS sessions.
A shared SSLContext is only possible when shareConnections is enabled on the HTTP protocol. See the Protocol reference for details.

​
BoringSSL (Default TLS Engine)

Gatling uses BoringSSL — Google’s fork of OpenSSL — as its default TLS implementation. BoringSSL is more efficient than the JDK’s built-in TLS implementation, especially on JDK 8, and is the only supported option for HTTP/2 with JDK 8. To revert to the JDK’s TLS implementation, set the following property in gatling.conf:
gatling.conf
ssl {
  useOpenSsl = false
}

​
SNI (Server Name Indication)

Since JDK 7, SNI is enabled by default. Some misconfigured servers respond with a handshake alert: unrecognized_name exception when SNI is active. Because browsers are more lenient about this than the JDK, you may need to disable SNI to replicate realistic browser behavior against such servers. To disable SNI, set the following property in gatling.conf:
gatling.conf
ssl {
  enableSni = false
}

​
TLSv1.3

Gatling supports TLSv1.3 provided your Java runtime also supports it. TLSv1.3 requires Java 1.8.0_262 or later and is enabled by default when the JVM supports it.

​
Per-User KeyManagerFactory

For advanced mutual TLS scenarios where each virtual user needs to authenticate with a different client certificate, you can supply a factory function that creates a KeyManagerFactory per virtual user. The function receives the virtual user’s numeric ID, which you can use to select the appropriate keystore file or configuration. 
http.perUserKeyManagerFactory(
  userId -> {
    // load the appropriate KeyManagerFactory for this user
    KeyStore ks = KeyStore.getInstance("JKS");
    ks.load(
      getClass().getResourceAsStream("/keystores/user" + userId + ".jks"),
      "password".toCharArray()
    );
    KeyManagerFactory kmf = KeyManagerFactory.getInstance(
      KeyManagerFactory.getDefaultAlgorithm()
    );
    kmf.init(ks, "password".toCharArray());
    return kmf;
  }
);
perUserKeyManagerFactory is not available in the JavaScript/TypeScript SDK. If this feature is important to your workflow, you can express interest via the Gatling public roadmap.
The function input is the virtual user’s ID (a Long) and the return type must be a javax.net.ssl.KeyManagerFactory. This is also configurable at the protocol level via the perUserKeyManagerFactory option on the HttpProtocol.

​
Summary

Default TrustManager

Trusts all server certificates out of the box — including self-signed and custom CA certs — so you can start testing any HTTPS server immediately.

Custom Keystores

Override via gatling.conf ssl block to use your own JKS or PKCS12 keystore for mutual TLS scenarios.

Per-User Certificates

Use perUserKeyManagerFactory on the HTTP protocol to issue different client certificates per virtual user.

TLSv1.3 Ready

TLSv1.3 is supported and enabled by default on Java 1.8.0_262+ with BoringSSL as the high-performance TLS engine.

Build docs developers (and LLMs) love

Get started for freeTalk to us