SSL and certificates
In most cases, your Ktor services are placed behind a reverse proxy such as Nginx or Apache. This means that a reverse proxy server handles security concerns, including SSL.
If necessary, you can configure Ktor to serve SSL directly by providing a path to a certificate. Ktor uses Java KeyStore (JKS) as a storage facility for certificates. You can use keytool to convert and manage certificates stored in KeyStore. This might be useful if you need to convert a PEM certificate issued by a certificate authority to the JKS format supported by Ktor.
Generate a self-signed certificate
Generate a certificate in code
Ktor provides the ability to generate self-signed certificates for testing purposes by calling the buildKeyStore function, which returns a KeyStore instance. To use this function, you need to add the ktor-network-tls-certificates
artifact in the build script:
The code snippet below shows how to generate a certificate and save it to a keystore file:
Since Ktor requires a certificate when it starts, you have to create a certificate before starting the server. You can find the full example here: ssl-embedded-server.
Generate a certificate using keytool
You can use keytool to generate a self-singed certificate:
After executing this command, keytool
suggests you specify a keystore password and then generates a JKS file.
Convert PEM certificates to JKS
If your certificate authority issues certificates in a PEM format, you need to convert it to the JKS format before configuring SSL in Ktor. You can use openssl
and keytool
utilities to do this. For example, if you have a private key in the key.pem
file and a public certificate in cert.pem
, a conversion process might look as follows:
Convert PEM into the PKCS12 format using
openssl
by using the following command:openssl pkcs12 -export -in cert.pem -inkey key.pem -out keystore.p12 -name "sampleAlias"You will be prompted to enter a passphrase for
key.pem
and a new password forkeystore.p12
.Convert PKCS12 to the JKS format using
keytool
:keytool -importkeystore -srckeystore keystore.p12 -srcstoretype pkcs12 -destkeystore keystore.jksYou will be prompted to enter a password for the
keystore.p12
file and a new password forkeystore.jks
. Thekeystore.jks
will be generated.
Configure SSL in Ktor
Specifying SSL settings in Ktor depends on the way used to configure a Ktor server: by using a configuration file or in code using the embeddedServer
function.
Configuration file
If your server is configured in the application.conf
or application.yaml
configuration file, you can enable SSL using the following properties:
Specify the SSL port using the
ktor.deployment.sslPort
property:ktor { deployment { sslPort = 8443 } }ktor: deployment: sslPort: 8443Provide keystore settings in a separate
security
group:ktor { security { ssl { keyStore = keystore.jks keyAlias = sampleAlias keyStorePassword = foobar privateKeyPassword = foobar } } }ktor: security: ssl: keyStore: keystore.jks keyAlias: sampleAlias keyStorePassword: foobar privateKeyPassword: foobar
You can find the full example here: ssl-engine-main.
embeddedServer
If you use the embeddedServer
function to run your server, you need to pass a custom environment and provide SSL settings there using sslConnector:
You can find the full example here: ssl-embedded-server.