Using a Self-Signed Certificate

Ktor allows you to create and use self-signed certificates for serving HTTPS or HTTP/2 requests.

This function is defined in the method io.ktor.network.tls.certificates.generateCertificate in the artifact io.ktor:ktor-network-tls:$ktor_version.

dependencies { implementation "io.ktor:ktor-network-tls:$ktor_version"}

dependencies { implementation("io.ktor:ktor-network-tls:$ktor_version")}

<project> … <dependencies> <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-network-tls</artifactId> <version>${ktor.version}</version> <scope>compile</scope> </dependency> </dependencies></project>

Table of contents:

To create a self-signed certificate using Ktor, you have to call the generateCertificate function.

  1. io.ktor.network.tls.certificates.generateCertificate(File("mycert.jks"))

Since Ktor requires the certificate when it starts, you have to create the certificate before starting the server.

Create the certificate using gradle

One possible option is to execute the main class generating the certificate before actually running the server:

CertificateGenerator.kt

You can declare a class with a main method that only generates the certificate when it doesn’t exist:

  1. package io.ktor.samples.http2
  3. import io.ktor.network.tls.certificates.generateCertificate
  4. import java.io.File
  6. object CertificateGenerator {
  7.     @JvmStatic
  8.     fun main(args: Array<String>) {
  9.         val jksFile = File("build/temporary.jks").apply {
  10.             parentFile.mkdirs()
  11.         }
  13.         if (!jksFile.exists()) {
  14.             generateCertificate(jksFile) // Generates the certificate
  15.         }
  16.     }
  17. }

build.gradle

In your build.gradle file you can make the run task to depend on a generateJks task that executes the mainclass generating the certificate. For example:

  1. task generateJks(type: JavaExec, dependsOn: 'classes') {
  2.     classpath = sourceSets.main.runtimeClasspath
  3.     main = 'io.ktor.samples.http2.CertificateGenerator'
  4. }
  6. getTasksByName("run", false).first().dependsOn('generateJks')

The HOCON application.conf configuration file

When creating your HOCON configuration file, you have to add the ktor.deployment.sslPort, and the ktor.security.sslproperties to define the ssl port and the keyStore:

resources/application.conf:

  1. ktor {
  2.     deployment {
  3.         port = 8080
  4.         sslPort = 8443
  5.         watch = [ http2 ]
  6.     }
  8.     application {
  9.         modules = [ io.ktor.samples.http2.Http2ApplicationKt.main ]
  10.     }
  12.     security {
  13.         ssl {
  14.             keyStore = build/temporary.jks
  15.             keyAlias = mykey
  16.             keyStorePassword = changeit
  17.             privateKeyPassword = changeit
  18.         }
  19.     }
  20. }

Ktor normal module

After that you can just write a normal plain Ktor module:

Module.kt

  1. package io.ktor.samples.http2
  3. import io.ktor.application.*
  4. import io.ktor.features.*
  5. import io.ktor.http.*
  6. import io.ktor.response.*
  7. import io.ktor.routing.*
  8. import io.ktor.util.*
  9. import java.io.*
  11. fun Application.main() {
  12.     install(DefaultHeaders)
  13.     install(CallLogging)
  14.     install(Routing) {
  15.         get("/") {
  16.             call.push("/style.css")
  18.             call.respondText("""
  19.                 <!DOCTYPE html>
  20.                 <html>
  21.                     <head>
  22.                         <link rel="stylesheet" type="text/css" href="/style.css">
  23.                     </head>
  24.                     <body>
  25.                         <h1>Hello, World!</h1>
  26.                     </body>
  27.                 </html>
  28.             """.trimIndent(), contentType = ContentType.Text.Html)
  29.         }
  31.         get("/style.css") {
  32.             call.respondText("""
  33.                 h1 { color: olive }
  34.             """, contentType = ContentType.Text.CSS)
  35.         }
  36.     }
  37. }

Accessing your server

Then you can point to https://127.0.0.1:8443/ to access your server.Since this is a self-signed certificate, your browser will probably warn you about an invalid certificate, soyou will have to disable that warning.

Full example

Ktor has a full example using self-signed certificates here:

https://github.com/ktorio/ktor/tree/08b173e02fe9a9dbee39f48e7162e6ea7a1f8b16/ktor-samples/ktor-samples-ssl-http2