festivalspki

README

Festivals App PKI

The festivals pki repository contains descriptions, workflows and go modules to ensure secure communication between all components of the FestivalsApp.

---

Development • Deployment • Engage • Licensing

---

To secure communication between components the FestivalsApp uses mTLS with self signed certificates. First we need to create a certificate authority (CA) to issue certificates, then we create a certificate for each service and client. You can read more about the exact procedures in the Certification Practice Statements document.

Development

I use easy-rsa, which is maintained by the wonderfull community of OpenVPN, to build and manage the FestivalsApp Root CA. Even tho the details are quite complex, at the basis of a certificate authority stands a single root certificate. The root certificate is self-signed, meaning that we create it ourself. The idea is that every party that is communicating with each other needs a certificate signed with this root certificate.

1. First we need to install easy-rsa and create the FestivalsApp Root CA.

# installing the easy-rsa on macOS
brew install easy-rsa

# init the pki
easyrsa init-pki
# Create our root CA certificate (use at least a 40 character random password for the key file)
easyrsa build-ca

On macOS this will create all neccessary files at /opt/homebrew/etc/pki

1. To create a certificate/key pair for inter-service communication we first create a certificate request with the name of the service node and then sign the request.

# create signing request
easyrsa gen-req <UNIQUE_SERVER_NAME> nopass
# Enter <UNIQUE_SERVER_DOMAIN_NAME>
Common Name (eg: your user, host, or server name): <UNIQUE_SERVER_DOMAIN_NAME>
# sign the request
easyrsa sign-req serverClient <UNIQUE_SERVER_NAME>

2.1 Optionally convert certificates and keys to PEM format (for example for usage with mysql)

openssl x509 -in cert.crt -out cert.pem -outform PEM
openssl rsa -in cert.key -text > cert-key.pem

1. Copy the certificate/key pair to server and move them to their designated location

scp <path/to/cert/key> <user>@<server>:/home/<user>
sudo mv </old/cert/location> <new/cert/key/location>

1. Make the files accessible to the processes and set proper access permissions for certificates and keys

sudo chown <server-user> </cert/key/location>
sudo chmod 640/600 <cert/key/location>

Local Development

If you want to test on your local machine

sudo nano /etc/hosts

# local development on this machine
127.0.0.1       gateway.festivalsapp.dev
127.0.0.1       identity-0.festivalsapp.dev
127.0.0.1       festivals-0.festivalsapp.dev
127.0.0.1       database-0.festivalsapp.dev
127.0.0.1       fileserver-0.festivalsapp.dev
127.0.0.1       website-0.festivalsapp.dev

127.0.0.1       festivalsapp.dev
127.0.0.1       www.festivalsapp.dev
127.0.0.1       website.festivalsapp.dev
127.0.0.1       discovery.festivalsapp.dev
127.0.0.1       api.festivalsapp.dev
127.0.0.1       files.festivalsapp.dev

Development on a test server

If you have an development server in your private network

# local development server for festivalsapp
<ip address>        gateway.festivalsapp.home
<ip address>	      identity-0.festivalsapp.home
<ip address>	      festivals-0.festivalsapp.home
<ip address>	      festivals-1.festivalsapp.home
<ip address>	      database-0.festivalsapp.home
<ip address>        fileserver-0.festivalsapp.home
<ip address>        website-0.festivalsapp.home

<gateway ip address>            festivalsapp.home
<gateway ip address>            www.festivalsapp.home
<gateway ip address>            website.festivalsapp.home
<gateway ip address>            discovery.festivalsapp.home
<gateway ip address>            api.festivalsapp.home
<gateway ip address>            files.festivalsapp.home

Deployment

Add the FestivalsaApp Root CA certificate to the trusted root certificates:

macOS

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/new-root-certificate.crt

Linux (Ubuntu)

sudo cp new-root-certificate.crt /usr/local/share/ca-certificates/new-root-certificate.crt
sudo update-ca-certificates

Engage

I welcome every contribution, whether it is a pull request or a fixed typo. The best place to discuss questions and suggestions regarding the festivals-pki is the issues section. More general information and a good starting point if you want to get involved is the festival-documentation repository.

The following channels are available for discussions, feedback, and support requests:

Type	Channel
General Discussion
Other Requests

Licensing

Copyright (c) 2023-2024 Simon Gaus.

Licensed under the GNU Lesser General Public License v3.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.html.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE for the specific language governing permissions and limitations under the License.

https://docs.bigchaindb.com/projects/server/en/v1.1.0/production-deployment-template/easy-rsa.html#how-to-install-configure-easy-rsa openssl rsa -in /opt/homebrew/etc/pki/private/gateway-server.key -out /opt/homebrew/etc/pki/private/gateway-server-unencrypted.key

Documentation

Index

• func LoadCertificatePool(certFile string) (*x509.CertPool, error)
• func LoadServerCertificateHandler(serverCert string, serverKey string, rootCACert string) func(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
• func LoadServerCertificates(serverCert string, serverKey string, rootCACert string) (*tls.Certificate, error)
• func LoadX509Certificate(certFile string) (*x509.Certificate, error)

Functions

func LoadCertificatePool

func LoadCertificatePool(certFile string) (*x509.CertPool, error)

Creates and returns a certificate pool with the given certificate added to it.

func LoadServerCertificateHandler

func LoadServerCertificateHandler(serverCert string, serverKey string, rootCACert string) func(hello *tls.ClientHelloInfo) (*tls.Certificate, error)

LoadServerCertificatesHandler will return a function that loads the server certificate chain based on the given ClientHelloInfo.

func LoadServerCertificates

func LoadServerCertificates(serverCert string, serverKey string, rootCACert string) (*tls.Certificate, error)

LoadServerCertificates will attempt to load the server certificate chain.

func LoadX509Certificate

func LoadX509Certificate(certFile string) (*x509.Certificate, error)

LoadX509Certificate reads and parses a certificate from a .crt file. The file must contain PEM encoded data. The certificate file may only contain one certificate.