proc_manage-quay-ssl.adoc

Using SSL to protect connections to {productname}

This document assumes you have deployed {productname} in a single-node or highly available deployment.

To configure {productname} with a self-signed certificate, you need to create a Certificate Authority (CA), then generate the required key and certificate files. You then enter those files using the {productname} Config Tool or command line.

Create a CA and sign a certificate

1. Create a root CA.

   $ openssl genrsa -out rootCA.key 2048
   $ openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem

   The result are rootCA.key and rootCA.pem files in the current directory.

2. Create certificate and private key: If you are having {productname} handle TLS, you need to create a certificate and private key to provide during configuration. You can get those files from a certificate signing authority. Here we show how to create those files using the self-signed certificate authority you just created.

   In this example, you create device.crt and device.key files, which will be uploaded to {productname} and renamed ssl.cert and ssl.key, respectively.

   Because OpenShift creates long fully qualified domain names, consider using a wildcard to identify the larger domain, instead of the specific route to the {productname} application. For example, use something like *.apps.openshift.example.com when prompted for the server’s hostname:

   Common Name (eg, your name or your server's hostname) []:*apps.openshift.example.com

   $ openssl genrsa -out device.key 2048
   $ openssl req -new -key device.key -out device.csr

   Then sign the certificate with the root CA created earlier:

   $ openssl x509 -req -in device.csr -CA rootCA.pem \
          -CAkey rootCA.key -CAcreateserial -out device.crt -days 500 -sha256

Note

Instead generating the *.key and *.crt files as just shown, you could create an openssl.cnf file. This lets you add more information to the resulting certificate than you can get by just responding to the prompts in the command for generating the certificate request. In this example of an openssl.cnf file, replace DNS.1 and IP.1 with the hostname and IP address of the {productname} server: openssl.cnf [req] req_extensions = v3_req distinguished_name = req_distinguished_name [req_distinguished_name] [ v3_req ] basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectAltName = @alt_names [alt_names] DNS.1 = reg.example.com IP.1 = 12.345.678.9 You could then generate the key as follows: $ openssl x509 -req -in ssl.csr -CA rootCA.pem \ -CAkey rootCA.key -CAcreateserial -out ssl.cert \ -days 356 -extensions v3_req -extfile openssl.cnf

Configure {productname} to use the new certificate

The next step can be accomplished either in the {productname} screen or from the terminal.

Configure SSL from the {productname} Setup screen

Start the Quay container in config mode, as described in each deployment guide. In the server Configuration section, enable SSL as follows:

1. Set the Server Hostname to the appropriate value and check the Enable SSL box, then upload the ssl.key and ssl.cert files (in our example, named device.key and device.crt, respectively):

2. Save the configuration. {productname} will automatically validate the SSL certificate:

3. Restart the container

Configure with the command line

By not using the web interface the configuration checking mechanism built into {productname} is unavailable. It is suggested to use the web interface if possible. For non-OpenShift installations, you can configure SSL from the command-line interface as follows:

1. Copy the ssl.key and ssl.cert into the specified config directory. In this example, the config directory for {productname} is on a host named reg.example.com in a directory named /mnt/quay/config.

   Note	The certificate/key files must be named ssl.key and ssl.cert.

   $ ls
   ssl.cert  ssl.key
   $ scp ssl.* root@reg.example.com:/mnt/quay/config/
   [root@reg.example.com ~]$ ls /mnt/quay/config/
   config.yaml  ssl.cert  ssl.key

2. Modify the PREFERRED_URL_SCHEME: parameter in config.yaml from http to https

   PREFERRED_URL_SCHEME: https

3. Restart the {productname} container:

   $ sudo podman ps
   CONTAINER ID  IMAGE                     COMMAND                 CREATED       STATUS      PORTS                   NAMES
   eaf45a4aa12d  ...redhat.io/rhel8/redis-5 "/usr/bin/redis-serve" 22 hours ago  Up 22 hours 0.0.0.0:6379->6379/tcp  dreamy...
   cbe7b0fa39d8  quay.io/redhat/quay       "/sbin/my_init"         22 hours ago  Up one hour 80/tcp,443/tcp,443/tcp  ferv...
   705fe7311940  rhel8/mysql-80                 "/entrypoint.sh mysql"  23 hours ago  Up 22 hours 0.0.0.0:3306->3306/tcp  mysql
   $ sudo podman restart cbe7b0fa39d8

Test the secure connection

Confirm the configuration by visiting the URL from a browser https://reg.example.com/ "Your Connection is not secure" means the CA is untrusted but confirms that SSL is functioning properly. To avoid these messages, you need to get a certificate from a trusted certificate authority.

Configuring Docker to Trust a Certificate Authority

Docker requires that custom certs be installed to /etc/docker/certs.d/ under a directory with the same name as the hostname private registry. It is also required for the cert to be called ca.crt. Here is how to do that:

1. Copy the rootCA file.

   $ cp tmp/rootCA.pem /etc/docker/certs.d/reg.example.com/ca.crt

2. After you have copied the rootCA.pem file, docker login should authenticate successfully and pushing to the repository should succeed.

   $ sudo docker push reg.example.com/kbrwn/hello
   The push refers to a repository [reg.example.com/kbrwn/hello]
   5f70bf18a086: Layer already exists
   e493e9cb9dac: Pushed
   1770dbc4af14: Pushed
   a7bb4eb71da7: Pushed
   9fad7adcbd46: Pushed
   2cec07a74a9f: Pushed
   f342e0a3e445: Pushed
   b12f995330bb: Pushed
   2016366cdd69: Pushed
   a930437ab3a5: Pushed
   15eb0f73cd14: Pushed
   latest: digest: sha256:c24be6d92b0a4e2bb8a8cc7c9bd044278d6abdf31534729b1660a485b1cd315c size: 7864