1. V-Raptor Internal CA
   1. The Root and Signing CA configuration files
   2. Adjusting certificate lifetimes
2. Public certificates
   1. Manual Installation
   2. Self-signed public certificates
   3. Generating a CA
      1. Creating the folder structure
   4. Generating V-Raptor certificates
   5. Installing into Kubernetes

V-Raptors make extensive use of certificates for authentication and encryption purposes. Each micro-service deployed to the V-Raptor will need a public and private key in order to authenticate with other services when using the RPC layer. This certificate can also be used to encrypt data at rest. Moreover, integrators that make use of REST APIs for device integrations will also need a set of certificates in order to generate a Bearer token for authentication. Each V-Raptor will therefore require a certificate authority through which certificates can be issued. As these certificates can be complex to manage, the V-Raptor comes with a built-in CA facility.

In addition to certificates used for authentication purposes, the V-Raptor also requires one or more sets of certificates issued on the Raptor’s public domain name. These certificates should preferably be issued by a trusted authority, as they will be used for inbound communication from devices and APIs which often times do not support self-signed chains of trust.

V-Raptor Internal CA

The V-Raptor can generate its own CA using OpenSSL as part of the installation process through which certificates can be issued and renewed as required. Once running, this CA should not be modified in any way. However, if the CA is compromised, a new CA can be generated by using the Raptor installation agent’s CA recovery mode.

Note: All certificates that have been issued will need to be re-issued if the CA is re-generated. For this reason it is recommended that a separate PKI be used to issue certificates that need to be installed on physical devices.

Before installing a V-Raptor, the certificate characteristics - such as certificate lifetimes - can be adjusted by configuring the OpenSSL template config files. There are three files that control the root, signing and service certificates respectively.

Note: Sections in curly braces are templates used by the V-Raptor CA service and should not be altered.

The Root and Signing CA configuration files

The following sections in the CA config files can be modified. Be arned though that specifying a weak hashing algorithm will cause some software components to fail. By default the root CA is set to expire after 10 years, with each issued certificate set to expire after 2 years.

To specify the hashing function and key size, the following can be modified in the config files:

[ req ]
default_bits            = 2048
default_md              = sha256

The organisational name displayed in the certificate can be set by altering the following line in the root.conf and signing.conf config files:

[ ca_dn ]
organizationName        = "IoT.nxt"

And for issued certificates, the service.conf config file can be edited:

[ server_dn ]
organizationName        = "IoT.nxt"

Note: This name must be the same in all three config files.

Adjusting certificate lifetimes

The lifetime of the root and signing CA, as well as issued certificates can be adjusted by modifying the default_days value in all three config files.

For the root certificate, it will be located in the following section:

[ root_ca ]
default_days            = 3652

To change the duration of server certificate issued by the V-Raptor, modify the following line in the signing.conf file:

default_days            = 730

Public certificates

The Raptor will make use of the public certificates to serve HTTP requests to APIs and web applications. These certificates should be issued by trusted authorities on the domain name that the V-Raptor will be reachable.

The V-Raptor currently supports RSA and EC public certificates, but only one pair of each may be installed.

Prior to installation, the certificates can be added to Kubernetes manually so that the ingress service starts up after installation. Once all services are running these certificates can be managed by using the deployment agent’s certificate management API.

Manual Installation

Trusted certificates are placed in Kubernetes ConfigMaps and Secrets. This is done so that multiple public certificates can be added and mounted into each container. Certificates should be placed in the following locations:

Note: If adding an EC certificate, the names will be public.ec.xxx for example public.ec.crt.

If no trusted authority is available or there is no way to issue a certificate from a trusted issuer like Let’s Encrypt, a self signed certificate may be used as a placeholder until such time as a certificate can be obtained.

Note: Self-signed certificates will required that the CA chain be installed on the user’s computer and/or web browser in order for web applications and API calls to work correctly.

Self-signed public certificates

The same configuration files can be used as those provided in the CA setup. However, the templates sections will need to be replaced. You will also need OpenSSL on your machine.

In the root and signing CA config files, change the following lines where the placeholders are located.

[ ca_dn ]
0.domainComponent       = "io"
1.domainComponent       = "commander"
organizationName        = "Your Organisation"
organizationalUnitName  = "Your Organisation"
commonName              = "You Organisation V-Raptor Root/Signing CA"

In the service certificate config file, be sure to add the domain components as required, along with an Subject Alternative Names (SAN):

[ default ]
SAN                     = DNS:vraptor01-organisation.commander.io
[ server_dn ]
0.domainComponent       = "io"
1.domainComponent       = "commander"
commonName              = "vraptor01-organisation.commander.io"
organizationalUnitName  = "vraptor01-organisation.commander.io"

Generating a CA

This step need only be done once, since the CA can be re-used for other V-Raptors hosted by the organisation.

Creating the folder structure

# Create working directories
mkdir vraptor-ca
cd vraptor-ca

mkdir -p ca/root-ca/private
mkdir -p ca/root-ca/db
mkdir -p ca/signing-ca/private
mkdir -p ca/signing-ca/db
mkdir etc
mkdir certs
mkdir crl

# Create the required files
touch  ca/root-ca/db/root-ca.db
touch  ca/root-ca/db/root-ca.db.attr
echo 01 >  ca/root-ca/db/root-ca.crt.srl
echo 01 >  ca/root-ca/db/root-ca.crl.srl

touch ca/signing-ca/db/signing-ca.db
touch ca/signing-ca/db/signing-ca.db.attr
echo 01 > ca/signing-ca/db/signing-ca.crt.srl
echo 01 > ca/signing-ca/db/signing-ca.crl.srl

Place the config files inside the etc folder and run the following steps:

# Assign your root pass
ROOT_PASS=


# Create CA request
openssl req -new -config etc/root-ca.conf -out ca/root-ca.csr -passout pass:$ROOT_PASS -keyout ca/root-ca/private/root-ca.key

# Create self-signed root certificates
openssl ca -selfsign -config etc/root-ca.conf -in ca/root-ca.csr -out ca/root-ca.crt -key $ROOT_PASS -extensions root_ca_ext -batch

You have now generated a Root CA. Next, we will generate a Signing CA.

# Assign your signing pass
SIGNING_PASS=

# Create Signing CA request
openssl req -new -config etc/signing-ca.conf -out ca/signing-ca.csr -passout pass:$SIGNING_PASS -keyout ca/signing-ca/private/signing-ca.key

# Create Signing CA certificates
openssl ca -config etc/root-ca.conf -in ca/signing-ca.csr -out ca/signing-ca.crt -key $ROOT_PASS -extensions signing_ca_ext -batch

From here on, the signing CA can be used to generate new certificates. The root-ca.crt and signing-ca.crt located in the ca folder should be installed on the user’s PC as well as in the web browser. Be sure to keep the root and signing certificate private keys and passwords securely stored.

Generating V-Raptor certificates

Once the CA has been generated, a certificate can be issued for the V-Raptor to serve as its public certificate.

# Create V-Raptor certificate request
openssl req -new -config etc/service.conf -out certs/public.rsa.csr -passout pass:$SIGNING_PASS -keyout certs/public.rsa.key

# Create V-Raptor certificate
openssl ca -config etc/signing-ca.conf -in certs/public.rsa.csr -out certs/public.rsa.crt -key $SIGNING_PASS -extensions server_ext -batch

# Create fullchain cert

cat ca/signing-ca.crt >> certs/public.rsa.crt


# Create PFX file (leave password blank)

openssl pkcs12 -export -in certs/public.rsa.crt -inkey certs/public.rsa.key -out certs/public.rsa.pfx

Note: If the same CA is used for all V-Raptors, then this need only be done once.

Installing into Kubernetes

Finally, the certificates can be added to the Kubernetes namespace where they will serve as temporary trusted certificates for the Raptor’s ingress.

kubectl -n vraptor01-organisation create configmap trusted-certs --from-file=certs/public.rsa.crt \
&& kubectl -n vraptor01-organisation create secret generic trusted-keys --from-file=certs/public.rsa.key \
&& kubectl -n vraptor01-organisation create secret generic trusted-pfx --from-file=certs/public.rsa.pfx