HTTPS support

Since version 0.0.23 Gretty supports HTTPS protocol out-of-the-box.

HTTPS Auto-configuration

Gretty provides very simple way to auto-configure HTTPS protocol. All you have to do is set httpsEnabled=true and launch Gretty start task. Upon successful start HTTPS is immediately available without any additional configuration.

Syntax

gretty {
  httpsEnabled = true
  // optionally you can specify port. 8443 is the default.
  // httpsPort = 443
}

Effects

On first run:

  1. Gretty generates 1024-bit RSA key

  2. Gretty generates self-signed X.509 certificate using "SHA256WithRSA" signature algorithm

  3. Gretty writes certificate to the file "${project.buildDir}/ssl/cert"

  4. Gretty generates random passwords for key-store and key-manager

  5. Gretty adds key and certificate to a new key-store, using key-manager password

  6. Gretty writes key-store to the file "${project.buildDir}/ssl/keystore", using key-store password

  7. Gretty saves key-store and key-manager passwords to the file "${project.buildDir}/ssl/properties"

  8. Gretty uses key-store "${project.buildDir}/ssl/keystore" for configuring HTTPS-connector

  9. Gretty starts servlet-container server with two connectors: HTTP, listening to httpPort (default 8080) and HTTPS, listening to httpsPort (default 8443).

On consequent runs:

  1. Gretty reads key-store and key-manager passwords from the file "${project.buildDir}/ssl/properties"

  2. Gretty uses key-store "${project.buildDir}/ssl/keystore" for configuring HTTPS-connector

  3. Gretty starts servlet-container server with two connectors: HTTP, listening to httpPort (default 8080) and HTTPS, listening to httpsPort (default 8443).

When you open HTTPS page in the browser for the first time, you typically see the message:

Connection is untrusted

The message is caused by the fact that Gretty uses self-signed certificate, not chained to Certificate Authority (CA). After you click "I understand the risks" and accept the certificate, the web-browser shows your web-app.

Important

Using self-signed certificate is OK for development environment, but not OK for production. Please never use the generated key and certificate files outside of Gretty tasks!
Important

Saving passwords to the file system is inherently unsafe. Please never run Gretty with auto-configured HTTPS on production systems!
Tip

"${project.buildDir}/ssl" directory is preserved between servlet-container runs, so that the same key and certificate are repeatedly used in development. Of course, you can delete the directory "${project.buildDir}/ssl" - it will be recreated on the next run. If you delete it, you’ll see a message "Connection is untrusted" again.
Tip

The self-signed certificate has issuer-DN "CN=gretty-issuer, OU=None, O=Gretty, L=None, C=None", under which it can be easily found and deleted in the browser settings.

HTTPS Manual configuration

Gretty provides the way to specify key-store and trust-store, so that pre-existing key and certificate are used.

Syntax

gretty {
  sslKeyStorePath = '/some/path/keystore'
  sslKeyStorePassword = 'someKeystorePassword'
  sslKeyManagerPassword = 'someKeyManagerPassword'
  sslTrustStorePath = '/another/path/trust_keystore'
  sslTrustStorePassword = 'someTrustStorePassword'
}

All SSL-related properties are optional.

If sslKeyStorePath is not specified, all other SSL-related properties are ignored and HTTPS is auto-configured.

sslKeyManagerPassword defaults to sslKeyStorePassword.

sslTrustStorePath defaults to sslKeyStorePath.

sslTrustStorePassword defaults to sslKeyStorePassword.

sslKeyStorePath and sslTrustStorePath can be set to String or java.io.File. Relative paths will be resolved relative to project.projectDir, project.webAppDir (default is "src/main/webapp"), project.sourceSets.main.output.files (defaults to [ "${project.buildDir}/classes/main", "${project.buildDir}/resources/main" ]).

Passwords may be obfuscated, as described in official Jetty documentation. If you are uncomfortable with saving passwords in the sources, consider using gradle.properties or gradle init scripts for configuring password variables outside of project sources.

Important
 CN attribute of the used certificate must match gretty.host property ("localhost" by default), otherwise servlet-container could not decide, which certificate to use.

Disabling HTTP

You might want to run your web-app with HTTPS only, without HTTP. It’s easy to do so:

gretty {
  httpEnabled = false
  httpsEnabled = true
}