skip to content

In WireMock, what do --https-port, --https-keystore and --keystore-password do?

level: juniorimportance: must knowfreq 64%

answer

  1. an extra listener, not a replacement
  2. TLS needs a certificate from somewhere
  3. bundled self-signed certificate is the default
  4. a Java keystore, not a bare PEM
  5. WireMock --https-keystore plus --keystore-password

basics

~20 s

WireMock's --https-port opens an extra TLS listener on that port. --https-keystore points at a Java keystore holding the certificate WireMock presents there, and --keystore-password unlocks it. Omit both and WireMock serves its own bundled self-signed certificate instead.

solid answer

~50 s

In WireMock, `--https-port 8443` adds a **second listener** that speaks TLS; the stub set is untouched, so a mapping registered for `GET /call-sheets/v1/shows/42/calls` answers a caller arriving over TLS exactly as it answers one arriving in the clear. With no other flag WireMock presents a self-signed certificate it ships with, which is fine for a client you have configured to accept it and useless for one that checks the issuer. WireMock's `--https-keystore` points at a **Java keystore** holding the certificate and key you want presented instead, and `--keystore-password` is the password that opens that keystore; if it cannot be opened the HTTPS listener never comes up. Matching happens after the connection is established, so a trust failure and a missing mapping look nothing alike. The client side is the other half: it must accept whatever certificate WireMock presents, or the call never lands.

code

bash · 7 lines
bash
java -jar wiremock-standalone.jar \
  --https-port 8443 \
  --https-keystore /etc/callsheet/callsheet-stub.jks \
  --keystore-password s3cr3t-callsheet

curl --cacert /etc/callsheet/callsheet-stub-ca.pem \
  https://localhost:8443/call-sheets/v1/shows/42/calls

go deeper

for a junior

Be ready to name the flag that opens WireMock's TLS listener and to say that stubs already registered answer on it unchanged. Knowing that WireMock's --https-keystore exists and needs a password is enough at this stage.

for a middle

Explain where the certificate comes from in each case: WireMock's bundled self-signed one, or the keystore behind --https-keystore that --keystore-password unlocks. Say what the client must trust for the call to succeed at all.

for a senior

Show how a trusted certificate reaches a CI job - a keystore built and mounted per environment - and how you tell a handshake failure apart from a mapping failure when a suite goes red overnight.

for a principal

Own whether suites should talk to stub servers over TLS at all, and who holds the keystores if they do. Weigh the fidelity gained against certificates and passwords nobody has agreed to rotate.

## What WireMock's `--https-port` actually opens WireMock standalone serves its stubs over plain HTTP. Passing WireMock's `--https-port 8443` does not move that service anywhere: it adds a **second listener**, on the port you name, that speaks TLS. Both listeners front the same server and the same stub set, so a mapping registered for `GET /call-sheets/v1/shows/42/calls` answers a stage-crew client that arrives over TLS exactly as it answers one that arrives in the clear. Request matching happens once the connection has been established and the request parsed, and that ordering is the single most useful thing to carry away from this flag: **anything that goes wrong while the connection is being set up never reaches your mappings at all.** It also tells you exactly what the client has to change — the scheme, the host and the port it dials, and nothing else. A suite that used `http://localhost:8080/call-sheets/v1/shows/42/calls` now uses `https://localhost:8443/call-sheets/v1/shows/42/calls`, and every mapping, matcher and canned body stays as it was. ## Where the certificate comes from A TLS listener has to present a certificate, and WireMock gives you two ways to decide which one: - **You supply nothing.** WireMock presents a **self-signed certificate that it ships with**. That is enough when the caller is a test client you can configure to accept it, and it is useless for any caller that validates who issued the certificate. - **You supply a keystore.** `--https-keystore /etc/callsheet/callsheet-stub.jks` points WireMock at a **Java keystore** containing the certificate and private key you want it to present, and `--keystore-password` is the password that opens that keystore. Two details are worth being precise about. First, WireMock's `--https-keystore` wants a *keystore*, not a bare `.pem` or `.crt` file; handing it a certificate file is the commonest first-attempt failure. Second, the password is not optional bookkeeping. If the keystore cannot be opened, the HTTPS listener does not come up, and the failure surfaces while the server is starting rather than as a certificate error on the first call. ## Getting a call-sheet client through the connection 1. **Point the client at the TLS listener.** Change its base URL to `https://localhost:8443`, leaving the paths alone. 2. **Make the certificate acceptable.** Either give WireMock a certificate the client already accepts, using `--https-keystore` with `--keystore-password`, or add the certificate WireMock presents to the trust store the client reads. 3. **Read the failure correctly.** A trust failure dies before any HTTP response exists; a missing mapping produces an HTTP response from a perfectly healthy server. Those two are never the same bug. ## The flags people mix up | WireMock flag | what it decides | |---|---| | `--https-port` | whether WireMock listens for TLS at all, and on which port | | `--https-keystore` with `--keystore-password` | which certificate that listener presents, and how WireMock unlocks the keystore | | `--ca-keystore` | the signing keystore for certificates WireMock mints while browser proxying | | `--trust-all-proxy-targets` | what WireMock accepts from an upstream it proxies to, not what your client accepts from WireMock | The last two rows cause most of the confusion. `--ca-keystore` and the certificate served at `GET /__admin/certs/wiremock-ca.crt` belong to `--enable-browser-proxying`, where WireMock is acting as a proxy and must answer for hosts it has no fixed certificate for. Neither is part of running a straightforward HTTPS listener with your own keystore. ## The same job in the other two products | product | how HTTPS is served | |---|---| | WireMock | `--https-port` opens a dedicated TLS listener; `--https-keystore` with `--keystore-password` supplies the certificate | | MockServer | one port serves both schemes, the behaviour its documentation calls *port unification*, so there is no second port to configure | | Mountebank | `https` is one of the protocols an imposter can be created with, alongside `tcp` and `smtp` | That table is also the attribution discipline this subject demands. The flags above are **WireMock's**. Every stub server in this space can serve HTTPS somehow, and reaching for one product's flag while describing another is the mistake an interviewer notices fastest. ## Failure modes to recognise - **The HTTPS listener is simply absent.** Usually WireMock could not open the keystore: wrong `--keystore-password`, wrong path, or a file that is not a Java keystore. - **The client rejects the certificate.** WireMock is running correctly; the client's trust store has not been told about the certificate the listener presents. - **The client connects and gets an unexpected body or status.** That is a matching problem. The connection already succeeded, so nothing about the keystore is involved. - **The team repoints everything because "HTTP is off now".** It is not off. WireMock's `--https-port` is additive, and both listeners serve the same stubs. - **Trust is added on a developer's own machine and a container is expected to inherit it.** Trust lives wherever the client reads it from, and the container reads a different store. - **Someone reaches for `--ca-keystore` to fix this.** That keystore is for WireMock's browser-proxy signing; it does not change what the `--https-port` listener presents.

  • In WireMock, does adding --https-port mean you must register call-sheet stubs twice?
    No. In WireMock the stub set belongs to the server, not to a listener. The mapping you registered for `GET /call-sheets/v1/shows/42/calls` is matched after the connection has been established and the request parsed, so the same mapping answers a plain call and a TLS one. Only the scheme, host and port the client dials change.
  • Your JVM suite still refuses the certificate WireMock presents on the HTTPS port. What do you change?
    Either present something the client already accepts — build a keystore whose certificate your test JVM trusts and pass it with `--https-keystore` plus `--keystore-password` — or add WireMock's certificate to the trust store that suite reads. Note that `GET /__admin/certs/wiremock-ca.crt` is not the fix here: it returns the CA WireMock signs browser-proxy certificates with, which is a different certificate from the one this listener presents.

saying these in an interview costs you the question

  • Thinks --https-port replaces WireMock's plain HTTP listener
  • Says stubs must be re-registered for the HTTPS listener
  • Claims WireMock cannot serve HTTPS unless you supply a keystore
  • Points WireMock's --https-keystore at a bare PEM file
  • Confuses WireMock's --https-keystore with its browser-proxy --ca-keystore