APIO Core

Appearance

SSL Certificates ​

This page describes how to replace the SSL/TLS certificate served by nginx in front of APIO Core.

INFO

The customer must provide the new certificate (full chain) and its private key, generated and signed by their Certificate Authority. The private key must not be password protected.

The procedure must be run on all APIO Core instances.

Preparation ​

Locate the current certificates ​

Connect to the server via SSH:

bash
ssh root@<apio-core-ip>

The nginx configuration for APIO Core is in /etc/nginx/conf.d/apio-core.conf:

bash
cd /etc/nginx/conf.d/
ls -lrt
cat apio-core.conf

Example output:

nginx
server {
    listen 443 ssl;

    server_name apio.example.com;

    access_log  /var/log/nginx/apio_api_access.log;
    error_log   /var/log/nginx/apio_api_error.log notice;

    ssl_certificate     /etc/ssl/certs/fullchain.crt;
    ssl_certificate_key /etc/ssl/private/server.key;

    ssl_protocols TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:...";
    ...
}

The ssl_certificate and ssl_certificate_key directives give the location of the files to replace. In this example:

  • Certificate: /etc/ssl/certs/fullchain.crt
  • Private key: /etc/ssl/private/server.key

INFO

File names and paths differ between deployments. Always use the paths shown in your own apio-core.conf.

Backup the current certificates ​

Save a copy of both files, to be used in case of rollback:

bash
cd /etc/ssl/certs/
ls -lrt fullchain.crt
cp -p fullchain.crt fullchain_OLD.crt

cd /etc/ssl/private/
ls -lrt server.key
cp -p server.key server_OLD.key

Installation ​

Install the new certificates ​

Copy the new certificate and key to a temporary folder on the server, for example /tmp. In this example the new files are named new.crt and new.key.

Move them to the configured locations, renaming them to the names used in apio-core.conf, and set the owner and permissions:

bash
cd /tmp
mv new.crt /etc/ssl/certs/fullchain.crt
mv new.key /etc/ssl/private/server.key

cd /etc/ssl/certs
chown root:root fullchain.crt
chmod 644 fullchain.crt

cd /etc/ssl/private
chown root:root server.key
chmod 600 server.key

WARNING

The private key must not be world-readable. 600 (owner root) is sufficient, because the nginx master process runs as root and reads the key at startup.

Activate the new certificates ​

Before activating the new certificates, check the nginx configuration for errors:

bash
nginx -t

Expected output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If there are no errors, restart nginx to load the new certificates:

bash
systemctl restart nginx

Then check the service status:

bash
systemctl status nginx

Example output:

● nginx.service - nginx - high performance web server
   Loaded: loaded (/usr/lib/systemd/system/nginx.service; enabled; vendor preset: disabled)
   Active: active (running) since ...
     Docs: http://nginx.org/en/docs/
 Main PID: 13486 (nginx)
   CGroup: /system.slice/nginx.service
           ├─13486 nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf
           ├─13487 nginx: worker process
           └─13488 nginx: worker process

Check that nginx serves the new certificate (subject and validity dates):

bash
openssl s_client -connect apio.example.com:443 -servername apio.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

Rollback ​

If nginx fails to start or the new certificate is not valid, restore the backup files and restart nginx:

bash
cp -p /etc/ssl/certs/fullchain_OLD.crt /etc/ssl/certs/fullchain.crt
cp -p /etc/ssl/private/server_OLD.key /etc/ssl/private/server.key

nginx -t
systemctl restart nginx