Configuring SSL

Configuring SSL for REST API and OSv GUI Dashboard

The server is using SSL for both client and server authentication. In these scheme we can distinguish three parties:

• the server
• the client(s)
• Certificate Authority (CA)

CA is trusted by both server and client. It's responsible for signing certificates for both the server and the client. Only a trusted client can connect to the server.

The table below shows which artifacts are needed to set this up and which parties need to hold them.

| cacert.pem | cakey.pem | server.pem | server.key | client.pem | client.key | client.p12 ---|------------|------------|------------|------------|------------|------------|-------- CA | Yes, to sign certs | Yes, to sign certs | No | No | No | No | No | No server | Yes, to verify client cert | No | Yes, presents to client | Yes, used as authentication key | No | No | No client | Yes, to verify server cert | No | No | No | Yes, presents to server | Yes, used as authentication key. | Yes, if using NSS. Combines both client.pem and client.key. Browsers work with this format.

Generating SSL artifacts in development environment

If you are building OSv from sources you can use the certs module. This module will generate all keys and certifiactes for you. You can find the artifacts in modules/certs/build/. The module, when included, will put all server-side artifacts in the image. So all you need to do to get SSL configured is to include the module in the image like this:

make image=httpserver,certs

Generating certificates manually

TODO

You can check modules/certs/Makefile for reference.

Configuring the server

The OSv's httpserver expects to find server-side artifact in the following locations in the image:

• /etc/pki/CA/cacert.pem - CA certificate
• /etc/pki/server.pem - server's certificate
• /etc/pki/private/server.key - server's private key

In the cloud

When you start an instance in the cloud you can enable SSL and pass the artifacts via cloud init configuration using the following YAML syntax:

httpserver:
  ssl: yes
files:
   /etc/pki/server.pem: |
      server.pem contents goes here
   /etc/pki/private/server.key: |
      server.key contents goes here
   /etc/pki/CA/cacert.pem: |
      cacert.pem contents goes here

You can generate such configuration using this script, assuming you have server.pem, server.key and cacert.pem in your current directory:

cat <<EOF
httpserver:
   ssl: yes
files:
   /etc/pki/server.pem: |
$(awk '{ print "         "$0; }' server.pem)
   /etc/pki/private/server.key: |
$(awk '{ print "         "$0; }' server.key)
   /etc/pki/CA/cacert.pem: |
$(awk '{ print "         "$0; }' cacert.pem)
EOF

For information on how to pass such configuration to the instance check out this page: Configuring instances in the cloud

In development environment

Build the image with the certs module. You can pick up client-side artifacts from modules/certs/build/. To enable SSL you need to pass the --ssl command line argument to httpserver. You can use the .fg_ssl run configuration which does exactly that:

make image=httpserver.fg_ssl,certs

Another option is to use cloud-init to configure the server. The certs module produces a cloud init configuration which can be used directly (modules/certs/build/cloud-init.yaml). Build and run like this:

# Need to make the certs module, if it hasn't been made before
pushd modules/certs
make
popd

make image=httpserver.fg,cloud-init

sudo scripts/ec2-simulator -f modules/certs/build/cloud-init.yaml &
sudo scripts/run.py -nv

Configuring client side

Clients need to present a valid certificate when connecting to server. In addition to that, the client needs to have access to the CA certificate so that he can verify that server's certificate can be trusted. How this is done depends on which client/library you use to connect to the server. The configuration of the most common clients is described below.

curl

Invoke curl like this:

$ curl --cacert cacert.pem --cert ./client.pem --key client.key https://osv:8000/os/version

OSv tools

Tools like scripts/trace.py and scripts/top.py are invoked similarly to curl:

$ scripts/trace.py download --cacert cacert.pem --cert client.pem --key client.key --url https://osv:8000
$ scripts/top.py --cacert cacert.pem --cert client.pem --key client.key [host] [port]

When SSL options are not passed these tools will assume plain HTTP transport is used.

Google-Chrome browser

Google chrome picks up certs from the local NSS store.

If you're in the development environment and generated artifacts using certs module, you can execute helper script:

cd modules/certs && ./import-to-nss.sh

To import it manually follow these steps:

1. Generate PKCS12 certificate:

openssl pkcs12 -export -out client.p12 \
    -inkey client.key \
    -in client.pem \
    -certfile cacert.pem \
    -name osv-client

2. Import PKCS12 into NSS store:

pk12util -d sql:$HOME/.pki/nssdb -i client.p12

3. Import CA cert into NSS store:

certutil -d sql:$HOME/.pki/nssdb -A -t PC -n osv-CA -i cacert.pem