> Docs > Http Server > Server SSL Configuration

Server SSL Configuration

SSL Ports

SSL can be enabled on an HttpServer by adding sslPort(...)

server.conf()
    .port   (  80 )
    .sslPort( 443 )
    .sslKeyStore( "./server-certs.jks", PASSWORD )

The same port can be used to server both plain and SSL connections; this is convenient for local development.

server.conf()
    .port   ( 8080 )
    .sslPort( 8080 )
    .sslKeyStore( "./localhost.jks", "password" )

Server Certificates

The key store file for server certificates can be specified by sslKeyStore(filePath,password); it's a convenience method for sslContext and SslConf, equivalent to

server.conf().sslContext( new SslConf()
        .keyStoreFile(filePath)
        .keyStorePass(password)
        .createContext()
);

SNI

To enable SNI support on the server side, we need the "PKIX" KeyManagerFactory algorithm

server.conf().sslContext( new SslConf()
        .keyStoreFile("./server-certs.jks")
        .keyStorePass(PASSWORD)
        .keyManagerFactoryAlgorithm("PKIX") // for SNI
        .createContext()
);

Client Certificates

If the server needs or wants client certificates, do it in sslEngineConf.

server.conf().sslEngineConf(engine ->
        engine.setWantClientAuth(true)
);

In HttpHandler, the client certificate chain is available at HttpRequest.certs().

Trusting client certificates

By default, client certificates must be signed by root CAs shipped with JVM, typically stored in trust store JAVA-HOME/lib/security/cacerts.

The server may want to specify a different trustStoreFile for validating client certificates. The trust store may contain a different CA (possibly operated by the server's organization), or it may directly contain individual client certificates.

server.conf().sslContext( new SslConf()
        .keyStoreFile("./server-certs.jks")
        .keyStorePass(PASSWORD)
        .trustStoreFile("./client-certs.jks")  // trust store for client certs
        .createContext()
);

The server may also choose to accept all client certificates, including all self-signed ones; by trustAll()

server.conf().sslContext( new SslConf()
        .keyStoreFile("./server-certs.jks")
        .keyStorePass(PASSWORD)
        .trustAll()                            // accept all client certs
        .createContext()
);

Using keytool

Here are some examples of using Java's keytool.

Create a self-signed server certificate for localhost

> keytool -genkeypair -alias localhost -keyalg RSA -validity 10000 -keystore localhost.jks -storepass password

What is your first and last name?
  [Unknown]:  localhost

The certificate is stored in file localhost.jks, with password password. To review it,

> keytool -list -v -keystore localhost.jks -storepass password

To export the certificate to localhost.cer

> keytool -exportcert -alias localhost -file localhost.cer -keystore localhost.jks -storepass password

Create a server certificate for multiple domains

To create a server certificate valid for server domain red.local, blue.local, and server IP 127.0.0.1

> keytool -genkeypair -alias color -keyalg RSA -validity 10000 -keystore colors.jks -storepass password -ext SAN=DNS:red.local,DNS:blue.local,IP:127.0.0.1

Client certificates

To generate a public-private key pair for client "Jane"

> keytool -genkeypair -alias jane -keyalg RSA -validity 10000 -storetype pkcs12 -keystore jane.p12 -storepass password

The client needs to import file jane.p12 to her browser.

To export the certificate to jane.cer

> keytool -exportcert -alias jane -file jane.cer -storetype pkcs12 -keystore jane.p12 -storepass password

The server can import jane.cer to its trust store client-certs.jks

> keytool -importcert -alias jane -file jane.cer -keystore client-certs.jks -storepass password

bayou.io