scripts: Move examples/etc/matchbox to scripts/tls

* Use the same TLS cert-gen location in source as in releases

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

scripts/tls/.gitignore

@@ -0,0 +1,5 @@
+*
+!.gitignore
+!README.md
+!cert-gen
+!openssl.conf

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
+```

scripts/tls/cert-gen

@@ -0,0 +1,45 @@
+#!/bin/bash -e
+# note: Script uses -batch and -subj, instead of interactive prompts.
+
+rm -f ca.key ca.crt server.key server.csr server.crt client.key client.csr client.crt index.* serial*
+rm -rf certs crl newcerts
+
+if [ -z $SAN ]
+  then echo "Set SAN with a DNS or IP for matchbox (e.g. export SAN=DNS.1:matchbox.example.com,IP.1:192.168.1.42)."
+  exit 1
+fi
+
+echo "Creating example CA, server cert/key, and client cert/key..."
+
+# basic files/directories
+mkdir -p {certs,crl,newcerts}
+touch index.txt
+echo 1000 > serial
+
+# CA private key (unencrypted)
+openssl genrsa -out ca.key 4096
+# Certificate Authority (self-signed certificate)
+openssl req -config openssl.conf -new -x509 -days 3650 -sha256 -key ca.key -extensions v3_ca -out ca.crt -subj "/CN=fake-ca"
+
+# End-entity certificates
+
+# Server private key (unencrypted)
+openssl genrsa -out server.key 2048
+# Server certificate signing request (CSR)
+openssl req -config openssl.conf -new -sha256 -key server.key -out server.csr -subj "/CN=fake-server"
+# Certificate Authority signs CSR to grant a certificate
+openssl ca -batch -config openssl.conf -extensions server_cert -days 365 -notext -md sha256 -in server.csr -out server.crt -cert ca.crt -keyfile ca.key
+
+# Client private key (unencrypted)
+openssl genrsa -out client.key 2048
+# Signed client certificate signing request (CSR)
+openssl req -config openssl.conf -new -sha256 -key client.key -out client.csr -subj "/CN=fake-client"
+# Certificate Authority signs CSR to grant a certificate
+openssl ca -batch -config openssl.conf -extensions usr_cert -days 365 -notext -md sha256 -in client.csr -out client.crt -cert ca.crt -keyfile ca.key
+
+# Remove CSR's
+rm *.csr
+
+echo "*******************************************************************"
+echo "WARNING: Generated credentials are self-signed. Prefer your"
+echo "organization's PKI for production deployments."

scripts/tls/openssl.conf

@@ -0,0 +1,82 @@
+# OpenSSL configuration file.
+# Adapted from github.com/dghubble/pegasus
+
+# default environment variable values
+SAN =
+
+[ ca ]
+# `man ca`
+default_ca = CA_default
+
+[ CA_default ]
+# Directory and file locations.
+dir               = .
+certs             = $dir/certs
+crl_dir           = $dir/crl
+new_certs_dir     = $dir/newcerts
+database          = $dir/index.txt
+serial            = $dir/serial
+# certificate revocation lists.
+crlnumber         = $dir/crlnumber
+crl               = $dir/crl/intermediate-ca.crl
+crl_extensions    = crl_ext
+default_crl_days  = 30
+default_md        = sha256
+
+name_opt          = ca_default
+cert_opt          = ca_default
+default_days      = 375
+preserve          = no
+policy            = policy_loose
+
+[ policy_loose ]
+# Allow the CA to sign a range of certificates.
+countryName             = optional
+stateOrProvinceName     = optional
+localityName            = optional
+organizationName        = optional
+organizationalUnitName  = optional
+commonName              = supplied
+emailAddress            = optional
+
+[ req ]
+# `man req`
+default_bits        = 4096
+distinguished_name  = req_distinguished_name
+string_mask         = utf8only
+default_md          = sha256
+
+[ req_distinguished_name ]
+countryName                    = Country Name (2 letter code)
+stateOrProvinceName            = State or Province Name
+localityName                   = Locality Name
+0.organizationName             = Organization Name
+organizationalUnitName         = Organizational Unit Name
+commonName                     = Common Name
+
+# Certificate extensions (`man x509v3_config`)
+
+[ v3_ca ]
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid:always,issuer
+basicConstraints = critical, CA:true, pathlen:0
+keyUsage = critical, digitalSignature, cRLSign, keyCertSign
+
+[ usr_cert ]
+basicConstraints = CA:FALSE
+nsCertType = client
+nsComment = "OpenSSL Generated Client Certificate"
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer
+keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
+extendedKeyUsage = clientAuth
+
+[ server_cert ]
+basicConstraints = CA:FALSE
+nsCertType = server
+nsComment = "OpenSSL Generated Server Certificate"
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer:always
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+subjectAltName = $ENV::SAN