From 292cd7fa7eb6675b8b1fd17fe72a891fd912ff22 Mon Sep 17 00:00:00 2001 From: Steven Smith <77019920+stevsmit@users.noreply.github.com> Date: Wed, 14 Aug 2024 16:11:13 -0400 Subject: [PATCH] Starts authentication book for Quay (#1072) Co-authored-by: Steven Smith --- deploy_quay/master.adoc | 2 +- modules/configuring-ssl-tls.adoc | 2 +- modules/ssl-create-certs.adoc | 3 ++- modules/ssl-intro.adoc | 7 +------ modules/ssl-testing-cli.adoc | 6 ++++-- modules/testing-ssl-tls-configuration.adoc | 2 +- tls_config/docinfo.xml | 10 ++++++++++ tls_config/master.adoc | 20 ++++++++++++++++++++ tls_config/modules | 1 + 9 files changed, 41 insertions(+), 12 deletions(-) create mode 100644 tls_config/docinfo.xml create mode 100644 tls_config/master.adoc create mode 120000 tls_config/modules diff --git a/deploy_quay/master.adoc b/deploy_quay/master.adoc index fd1cb76ad..6ce240d21 100644 --- a/deploy_quay/master.adoc +++ b/deploy_quay/master.adoc @@ -47,7 +47,7 @@ include::modules/advanced-quay-poc-deployment.adoc[leveloffset=+1] include::modules/ssl-intro.adoc[leveloffset=+2] include::modules/ssl-create-certs.adoc[leveloffset=+3] include::modules/configuring-ssl-tls.adoc[leveloffset=+2] -include::modules/ssl-config-ui.adoc[leveloffset=+3] +//include::modules/ssl-config-ui.adoc[leveloffset=+3] include::modules/ssl-config-cli.adoc[leveloffset=+3] include::modules/testing-ssl-tls-configuration.adoc[leveloffset=+2] include::modules/ssl-testing-cli.adoc[leveloffset=+3] diff --git a/modules/configuring-ssl-tls.adoc b/modules/configuring-ssl-tls.adoc index 9082f482a..a9ec840c7 100644 --- a/modules/configuring-ssl-tls.adoc +++ b/modules/configuring-ssl-tls.adoc @@ -2,4 +2,4 @@ [id="configuring-ssl-tls"] = Configuring SSL/TLS -SSL/TLS can be configured using either the command-line interface (CLI) or the {productname} registry UI. Use one of the following procedures to configure SSL/TLS. \ No newline at end of file +SSL/TLS must be configured by using the command-line interface (CLI) and updating your `config.yaml` file manually. \ No newline at end of file diff --git a/modules/ssl-create-certs.adoc b/modules/ssl-create-certs.adoc index 777d6497c..34a7ce2d9 100644 --- a/modules/ssl-create-certs.adoc +++ b/modules/ssl-create-certs.adoc @@ -2,7 +2,7 @@ [id="creating-a-certificate-authority"] = Creating a Certificate Authority -Use the following procedure to create a Certificate Authority (CA). +To configure {productname} with a self-signed certificate, you must first create a Certificate Authority (CA). Use the following procedure to create a Certificate Authority (CA). .Procedure @@ -63,6 +63,7 @@ Locality Name (eg, city) [Default City]:GALWAY Organization Name (eg, company) [Default Company Ltd]:QUAY Organizational Unit Name (eg, section) []:DOCS Common Name (eg, your name or your server's hostname) []:quay-server.example.com +Email Address []: ---- . Create a configuration file `openssl.cnf`, specifying the server hostname, for example: diff --git a/modules/ssl-intro.adoc b/modules/ssl-intro.adoc index 47eb084af..d2c1c6f46 100644 --- a/modules/ssl-intro.adoc +++ b/modules/ssl-intro.adoc @@ -1,9 +1,4 @@ [id="introduction-using-ssl"] = Using SSL/TLS -To configure {productname} with a self-signed certificate, you must create a Certificate Authority (CA) and a primary key file named `ssl.cert` and `ssl.key`. - -[NOTE] -==== -The following examples assume that you have configured the server hostname `quay-server.example.com` using DNS or another naming mechanism, such as adding an entry in your `/etc/hosts` file. For more information, see "Configuring port mapping for {productname}". -==== \ No newline at end of file +To configure {productname} with a self-signed certificate, you must create a Certificate Authority (CA) and a primary key file named `ssl.cert` and `ssl.key`. \ No newline at end of file diff --git a/modules/ssl-testing-cli.adoc b/modules/ssl-testing-cli.adoc index 4144be32d..b196e3234 100644 --- a/modules/ssl-testing-cli.adoc +++ b/modules/ssl-testing-cli.adoc @@ -2,18 +2,20 @@ [id="testing-ssl-tls-configuration-using-cli"] = Testing the SSL/TLS configuration using the CLI +Your SSL/TLS configuration can be tested by using the command-line interface (CLI). Use the following procedure to test your SSL/TLS configuration. + Use the following procedure to test your SSL/TLS configuration using the CLI. .Procedure -* Enter the following command to attempt to log in to the {productname} registry with SSL/TLS enabled: +. Enter the following command to attempt to log in to the {productname} registry with SSL/TLS enabled: + [source,terminal] ---- $ sudo podman login quay-server.example.com ---- + -Example output +.Example output + [source,terminal] ---- diff --git a/modules/testing-ssl-tls-configuration.adoc b/modules/testing-ssl-tls-configuration.adoc index 84711a854..520db12f7 100644 --- a/modules/testing-ssl-tls-configuration.adoc +++ b/modules/testing-ssl-tls-configuration.adoc @@ -2,4 +2,4 @@ [id="testing-ssl-tls-configuration"] = Testing the SSL/TLS configuration -Your SSL/TLS configuration can be tested using either the command-line interface (CLI) or the {productname} registry UI. Use one of the following procedures to test your SSL/TLS configuration. \ No newline at end of file +Your SSL/TLS configuration can be tested by using the command-line interface (CLI). Use the following procedure to test your SSL/TLS configuration. \ No newline at end of file diff --git a/tls_config/docinfo.xml b/tls_config/docinfo.xml new file mode 100644 index 000000000..ad2d96795 --- /dev/null +++ b/tls_config/docinfo.xml @@ -0,0 +1,10 @@ +{productname} +{producty} +Configuring SSL/TLS for {productname} + + Using SSL/TLS with {productname} + + + Red Hat OpenShift Documentation Team + + diff --git a/tls_config/master.adoc b/tls_config/master.adoc new file mode 100644 index 000000000..cd869faa4 --- /dev/null +++ b/tls_config/master.adoc @@ -0,0 +1,20 @@ +include::modules/attributes.adoc[] + +:_content-type: ASSEMBLY +[id="understanding-ssl-tls-quay"] += SSL/TLS for {productname} + +The Secure Sockets Layer (SSL) protocol was originally developed by Netscape Corporation to provide a mechanism for secure communication over the Internet. Subsequently, the protocol was adopted by the Internet Engineering Task Force (IETF) and renamed to Transport Layer Security (TLS). + +TLS (Transport Layer Security) is a cryptographic protocol used to secure network communications. When hardening system security settings by configuring preferred key-exchange protocols, authentication methods, and encryption algorithms, it is necessary to bear in mind that the broader the range of supported clients, the lower the resulting security. Conversely, strict security settings lead to limited compatibility with clients, which can result in some users being locked out of the system. Be sure to target the strictest available configuration and only relax it when it is required for compatibility reasons. + +{productname} can be configured to use SSL/TLS certificates to ensure secure communication between clients and the Quay server. This configuration involves the use of valid SSL/TLS certificates, which can be obtained from a trusted Certificate Authority (CA) or generated as self-signed certificates for internal use. + +The following sections show you how to enable SSL/TLS for {productname} by generating CAs, configuring SSL/TLS, testing the configuration, configuring Podman to trust the CA, and configuring the system to trust the CA. They should be followed in succession. + +include::modules/ssl-create-certs.adoc[leveloffset=+1] +include::modules/configuring-ssl-tls.adoc[leveloffset=+2] +include::modules/ssl-config-cli.adoc[leveloffset=+3] +include::modules/ssl-testing-cli.adoc[leveloffset=+3] +include::modules/ssl-trust-ca-podman.adoc[leveloffset=+2] +include::modules/ssl-trust-ca-system.adoc[leveloffset=+2] \ No newline at end of file diff --git a/tls_config/modules b/tls_config/modules new file mode 120000 index 000000000..43aab75b5 --- /dev/null +++ b/tls_config/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file