From 15a11283980dbc0b830ad33ad0e80f98faeda700 Mon Sep 17 00:00:00 2001 From: Dalton Hubble Date: Wed, 24 May 2017 10:58:13 -0700 Subject: [PATCH] scripts: Move examples/etc/matchbox to scripts/tls * Use the same TLS cert-gen location in source as in releases --- Documentation/deployment.md | 32 ++++++---- examples/etc/matchbox/README.md | 44 ------------- scripts/dev/release-files | 6 +- scripts/tls/.gitignore | 5 ++ scripts/tls/README.md | 61 +++++++++++++++++++ .../etc/matchbox => scripts/tls}/cert-gen | 4 +- .../etc/matchbox => scripts/tls}/openssl.conf | 0 7 files changed, 91 insertions(+), 61 deletions(-) delete mode 100644 examples/etc/matchbox/README.md create mode 100644 scripts/tls/.gitignore create mode 100644 scripts/tls/README.md rename {examples/etc/matchbox => scripts/tls}/cert-gen (92%) rename {examples/etc/matchbox => scripts/tls}/openssl.conf (100%) diff --git a/Documentation/deployment.md b/Documentation/deployment.md index a9933638..03958571 100644 --- a/Documentation/deployment.md +++ b/Documentation/deployment.md @@ -127,31 +127,39 @@ $ sudo firewall-cmd --zone=MYZONE --add-port=8080/tcp --permanent $ sudo firewall-cmd --zone=MYZONE --add-port=8081/tcp --permanent ``` -## Generate TLS credentials +## Generate TLS Certificates -*Skip this unless you need to enable the gRPC API* +The Matchbox gRPC API allows clients (terraform-provider-matchbox) to create and update Matchbox resources. TLS credentials are needed for client authentication and to establish a secure communication channel. Client machines (those PXE booting) read from the HTTP endpoints and do not require this setup. -The `matchbox` gRPC API allows client apps (terraform-provider-matchbox, Tectonic Installer, etc.) to update how machines are provisioned. TLS credentials are needed for client authentication and to establish a secure communication channel. Client machines (those PXE booting) read from the HTTP endpoints and do not require this setup. +The `cert-gen` helper script generates a self-signed CA, server certificate, and client certificate. **Prefer your organization's PKI, if possible** -If your organization manages public key infrastructure and a certificate authority, create a server certificate and key for the `matchbox` service and a client certificate and key for each client tool. - -Otherwise, generate a self-signed `ca.crt`, a server certificate (`server.crt`, `server.key`), and client credentials (`client.crt`, `client.key`) with the `examples/etc/matchbox/cert-gen` script. Export the DNS name or IP (discouraged) of the provisioner host. +Navigate to the `scripts/tls` directory. + +```sh +$ cd scripts/tls +``` + +Export `SAN` to set the Subject Alt Names which should be used in certificates. Provide the fully qualified domain name or IP (discouraged) where Matchbox will be installed. + +```sh +# DNS or IP Subject Alt Names where matchbox runs +$ export SAN=DNS.1:matchbox.example.com,IP.1:172.18.0.2 +``` + +Generate a `ca.crt`, `server.crt`, `server.key`, `client.crt`, and `client.key`. ```sh -$ cd examples/etc/matchbox -# DNS or IP Subject Alt Names where matchbox can be reached -$ export SAN=DNS.1:matchbox.example.com,IP.1:192.168.1.42 $ ./cert-gen ``` -Place the TLS credentials in the default location: +Move TLS credentials to the matchbox server's default location. ```sh $ sudo mkdir -p /etc/matchbox -$ sudo cp ca.crt server.crt server.key /etc/matchbox/ +$ sudo cp ca.crt server.crt server.key /etc/matchbox ``` -Save `client.crt`, `client.key`, and `ca.crt` to use with a client tool later. +Save `client.crt`, `client.key`, and `ca.crt` for later use (e.g. `~/.matchbox`). ## Start matchbox diff --git a/examples/etc/matchbox/README.md b/examples/etc/matchbox/README.md deleted file mode 100644 index 5cae256f..00000000 --- a/examples/etc/matchbox/README.md +++ /dev/null @@ -1,44 +0,0 @@ - -## gRPC API Credentials - -Create FAKE TLS credentials for running the `matchbox` gRPC API examples. - -**DO NOT** use these certificates for anything other than running `matchbox` examples. Use your organization's production PKI for production deployments. - -Navigate to the example directory which will be mounted as `/etc/matchbox` in examples: - - cd matchbox/examples/etc/matchbox - -Set certificate subject alt names which should be used by exporting `SAN`. Use the DNS name or IP at which `matchbox` is hosted. - - # for examples on metal0 or docker0 bridges - export SAN=IP.1:127.0.0.1,IP.2:172.18.0.2 - - # production example - export SAN=DNS.1:matchbox.example.com - -Create a fake `ca.crt`, `server.crt`, `server.key`, `client.crt`, and `client.key`. Type 'Y' when prompted. - - $ ./cert-gen - Creating FAKE CA, server cert/key, and client cert/key... - ... - ... - ... - ****************************************************************** - WARNING: Generated TLS credentials are ONLY SUITABLE FOR EXAMPLES! - Use your organization's production PKI for production deployments! - -## Inpsect - -Inspect the generated FAKE certificates if desired. - - openssl x509 -noout -text -in ca.crt - openssl x509 -noout -text -in server.crt - openssl x509 -noout -text -in client.crt - -## Verify - -Verify that the FAKE server and client certificates were signed by the fake CA. - - openssl verify -CAfile ca.crt server.crt - openssl verify -CAfile ca.crt client.crt \ No newline at end of file diff --git a/scripts/dev/release-files b/scripts/dev/release-files index 2824a155..8d1d7d09 100755 --- a/scripts/dev/release-files +++ b/scripts/dev/release-files @@ -18,9 +18,9 @@ cp README.md $DEST # scripts mkdir -p $SCRIPTS/tls cp scripts/get-coreos $SCRIPTS -cp examples/etc/matchbox/README.md $SCRIPTS/tls -cp examples/etc/matchbox/cert-gen $SCRIPTS/tls -cp examples/etc/matchbox/openssl.conf $SCRIPTS/tls +cp scripts/tls/README.md $SCRIPTS/tls +cp scripts/tls/cert-gen $SCRIPTS/tls +cp scripts/tls/openssl.conf $SCRIPTS/tls # systemd mkdir -p $CONTRIB/systemd diff --git a/scripts/tls/.gitignore b/scripts/tls/.gitignore new file mode 100644 index 00000000..8371e0f2 --- /dev/null +++ b/scripts/tls/.gitignore @@ -0,0 +1,5 @@ +* +!.gitignore +!README.md +!cert-gen +!openssl.conf \ No newline at end of file diff --git a/scripts/tls/README.md b/scripts/tls/README.md new file mode 100644 index 00000000..59a11dd3 --- /dev/null +++ b/scripts/tls/README.md @@ -0,0 +1,61 @@ +## gRPC TLS Generation + +The Matchbox gRPC API allows clients (`terraform-provider-matchbox`) to create and update Matchbox resources. TLS credentials are used for client authentication and to establish a secure communication channel. When the gRPC API is [enabled](../../Documentation/deployment.md#customization), the server requires a TLS server certificate, key, and CA certificate ([locations](../../Documentation/config.md#files-and-directories)). + +The `cert-gen` helper script generates a self-signed CA, server certificate, and client certificate. **Prefer your organization's PKI, if possible** + +Navigate to the `scripts/tls` directory. + +```sh +$ cd scripts/tls +``` + +Export `SAN` to set the Subject Alt Names which should be used in certificates. Provide the fully qualified domain name or IP (discouraged) where Matchbox will be installed. + +```sh +# DNS or IP Subject Alt Names where matchbox runs +$ export SAN=DNS.1:matchbox.example.com,IP.1:172.18.0.2 +``` + +Generate a `ca.crt`, `server.crt`, `server.key`, `client.crt`, and `client.key`. + +```sh +$ ./cert-gen +Creating FAKE CA, server cert/key, and client cert/key... +... +... +... +****************************************************************** +WARNING: Generated credentials are self-signed. Prefer your +organization's PKI for production deployments. +``` + +Move TLS credentials to the matchbox server's default location. + +```sh +$ sudo mkdir -p /etc/matchbox +$ sudo cp ca.crt server.crt server.key /etc/matchbox +``` + +Save `client.crt`, `client.key`, and `ca.crt` for later use (e.g. `~/.matchbox`). + +*If you are using the local Matchbox [development environment](../../Documentation/getting-started-rkt.md), move server credentials to `examples/etc/matchbox`.* + +## Inpsect + +Inspect the generated certificates if desired. + +```sh +openssl x509 -noout -text -in ca.crt +openssl x509 -noout -text -in server.crt +openssl x509 -noout -text -in client.crt +``` + +## Verify + +Verify that the server and client certificates were signed by the self-signed CA. + +```sh +openssl verify -CAfile ca.crt server.crt +openssl verify -CAfile ca.crt client.crt +``` diff --git a/examples/etc/matchbox/cert-gen b/scripts/tls/cert-gen similarity index 92% rename from examples/etc/matchbox/cert-gen rename to scripts/tls/cert-gen index bec366da..00dd4567 100755 --- a/examples/etc/matchbox/cert-gen +++ b/scripts/tls/cert-gen @@ -41,5 +41,5 @@ openssl ca -batch -config openssl.conf -extensions usr_cert -days 365 -notext -m rm *.csr echo "*******************************************************************" -echo "WARNING: Generating self-signed TLS-credentials. Its recommended to" -echo "use your own organization's public key infrastructure" +echo "WARNING: Generated credentials are self-signed. Prefer your" +echo "organization's PKI for production deployments." diff --git a/examples/etc/matchbox/openssl.conf b/scripts/tls/openssl.conf similarity index 100% rename from examples/etc/matchbox/openssl.conf rename to scripts/tls/openssl.conf