TLS setup

It is recommended to use TLS for protecting traffic between nray’s server and nodes, including mutual authentication if required. This quick start guide describes a portable and working approach to generate a CA and all required keys and certificates as well as how to use them. The goal is to provide an easy to follow guide, nevertheless a basic understanding of TLS and PKI is recommended.

This guide relies on cloudflare’s open source cfssl. Cherry-picked from here and here and here and of course here.

If you manage to get this up and running using keys and certificates generated by OpenSSL, Microsoft PKI, vim macro or your favorite solution not listed yet, we would love to know how you did it - simply edit this page and send a pull request!

CFSSL: Generate local CA, keys and certificates

  1. Get cfssl: go get -u github.com/cloudflare/cfssl/cmd/cfssl and go get -u github.com/cloudflare/cfssl/cmd/cfssljson
  2. Generate a CSR and save it to a file, e.g. csr.json. It contains basic information about the CA:
{
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C":  "DE",
            "L":  "Munich",
            "O":  "nray-scanner"
        }
    ]
}
  1. Generate a local CA: cfssl genkey -initca csr.json | cfssljson -bare ca. This creates ca-key.pem, the CA’s private key, as well as ca.pem, the certificate and ca.csr which is of no further use and may be deleted.
  2. Generate server certificate. If the host where nray is going to run has a DNS name, you may include it here, otherwise keep localhost: cfssl gencert -ca ca.pem -ca-key ca-key.pem -hostname=localhost csr.json | cfssljson -bare server. This creates files analogous to our CA, but with server* in their names.
  3. (if node auth is desired) Generate node certificate. Analogous to server. You may omit the hostname field and ignore the warning. Repeat for every node or reuse certificate.

As you do not need the csr’s anymore, you may delete them if you want.

What you need for operation

Server

  • ca.pem (This is public knowledge btw)
  • server.pem (public if you want)
  • server-key.pem (private)

Node

  • ca.pem (This is public knowledge btw)
  • client.pem (public if you want)
  • client-key.pem (private)

HowTo run

Trust every server, no client auth

  • Server: Set TLS.enabled: true, TLS.CA: "/path/to/your/ca.pem", TLS.cert: /path/to/your/server.pem, and TLS.key: /path/to/your/server-key.pem
  • Node: ./nray node -s <ip-or-dnsname> -p 8601 --use-tls --tls-insecure. This is insecure and traffic may be intercepted/modified by a 3rd party!. This mode of operation only protects from somebody occasionally scrolling over the traffic in Wireshark.

Trust only this server, no client auth

  • Server: Set TLS.enabled: true, TLS.CA: "/path/to/your/ca.pem", TLS.cert: /path/to/your/server.pem, and TLS.key: /path/to/your/server-key.pem
  • Node: ./nray node -s <ip-or-dnsname> -p 8601 --use-tls --tls-ca-cert /path/to/your/ca.pem --tls-server-SAN "<hostname>". If the nray-server has actually a DNS name that is also reflected in the cert, you can omit --tls-server-SAN, but if you are in an ad-hoc scenario or there is no DNS available and nray complains that the server name is missing, --tls-server-SAN is your friend.

Trust only this server, client authentication

  • Server: Set TLS.enabled: true, TLS.CA: "/path/to/your/ca.pem", TLS.cert: /path/to/your/server.pem, and TLS.key: /path/to/your/server-key.pem
  • Node: ./nray-node -s <ip-or-dnsname> -p 8601 --use-tls --tls-ca-cert /path/to/your/ca.pem --tls-server-SAN "<hostname>" --tls-client-cert /path/to/your/client.pem --tls-client-key /path/to/your/client-key.pem. If the nray-server has actually a DNS name that is also reflected in the cert, you can omit --tls-server-SAN, but if you are in an ad-hoc scenario or there is no DNS available and nray complains that the server name is missing, --tls-server-SAN is your friend.