Authentication and encryption

Server authentication

Dshackle server supports both server and client certificate authentication, and it’s strongly recommended to use TLS to connect to Dshackle server.More to that, the server uses gRPC, which is based on HTTP/2, and most of 3rd party tools and libraries expect it to be encrypted.

Please note that for most of use cases for Dshackle, which is designed to be an internal load balancer, a self-signed Certificates would be enough.In the example below, a certstrap tool is used to generate certificates, but the traditional openssl tool can be used as well.

Setup Server certificate

Generate a Certificate Authority
export SERVER_CA="ca.myhost.dev"
export ORG="My Company"
export ORG_UNIT="Blockchain"

certstrap init --common-name "$SERVER_CA" --passphrase "" -o "$ORG" -ou "$ORG_UNIT CA"
openssl pkcs8 -topk8 -inform PEM -outform PEM -in out/$SERVER_CA.key -out out/$SERVER_CA.p8.key -nocrypt
Generate a Server Certificate
export SERVER_IP="127.0.0.1"

certstrap request-cert -ip $SERVER_IP --common-name $SERVER_IP --passphrase ""  -o "$ORG" -ou "$ORG_UNIT Server"
certstrap sign $SERVER_IP --CA $SERVER_CA

openssl pkcs8 -topk8 -inform PEM -outform PEM -in out/$SERVER_IP.key -out out/$SERVER_IP.p8.key -nocrypt

You are going to get following files now in out directory:

  • ca.myhost.dev.crt your Certification Authority to sign or verify other certificates

  • ca.myhost.dev.p8.key is the private key for Certification Authority in PKSC 8 format

  • 127.0.0.1.crt server certificate, 127.0.0.1 is an IP address supposed to be used by that instance, and we use local host for demo purposes. For production use a real IP must be used.

  • 127.0.0.1.p8.key is private key for certificate in PKCS 8 format, it needed by Dshackle server to use certificate

Copy those files to directory with Dshackle and update configuration.

Update dshackle.yaml to have:
version: v1
port: 2449
tls:
  enabled: true
  server:
    certificate: 127.0.0.1.crt
    key: 127.0.0.1.p8.key
Verify that server uses the certificate
openssl s_client -alpn h2 -connect 127.0.0.1:2449 -CAfile out/ca.myhost.dev.crt

With the configuration above, the server listens using TLS, and the server identity can be verified by a client against a public server certificate. Please note that a server certificate doesn’t prevent a connection from an unauthorized client; it only verifies the server and encrypts a connection.

Use Client Certificate Authentication

To have authentication in both ways, you’ll need to configure client side certificates as well, in that case the server also verifies each incoming connection and allow to connect only by a client with a trusted certificate.

It’s possible to connect a Dshackle server to another one, and to do so you’ll probably want to use TLS as well.

Generate a client certificate
CLIENT_CA="client-ca.myhost.dev"
CLIENT_ID="client_1"
ORG="My Company"
ORG_UNIT="Client"

certstrap init --common-name "$CLIENT_CA" --passphrase "" -o "$ORG" -ou "$ORG_UNIT CA"
certstrap request-cert --common-name "$CLIENT_ID" --passphrase ""
certstrap sign "$CLIENT_ID" --CA $CLIENT_CA

openssl pkcs8 -topk8 -inform PEM -outform PEM -in out/$CLIENT_ID.key -out out/$CLIENT_ID.p8.key -nocrypt

In addition to files mentioned above you got few new files in out directory, including:

  • client-ca.myhost.dev.crt a certificate to validate connecting clients, all their keys much be signed by that certificate.Server don’t need a private key for that certificate because it’s used for verification only.

  • client_1.crt certificate for a client that will connect to the server

  • client_1.p8.key private key for that certificate, needed by client

Copy client-ca.myhost.dev.crt to directory with first Dshackle server.

Update server dshackle.yaml to have:
version: v1
port: 2449
tls:
  enabled: true
  server:
    certificate: 127.0.0.1.crt
    key: 127.0.0.1.p8.key
  client:
    require: true
    ca: client-ca.myhost.dev.crt
Verify connection with client certificate
openssl s_client -alpn h2 -connect 127.0.0.1:2449 -CAfile out/ca.myhost.dev.crt -cert out/client_1.crt -key out/client_1.key

Now you need to setup connection from another Dshackle server. I.e. the server we configured above is going be an upstream to another Dshackle server, which we configure below.

Setup another Dshackle server on the same machine:

Configure dshackle.yaml for second server
version: v1
port: 3449
tls:
  enabled: false

At this case we run another server on port 3449 in unsecure mode.But to connect to an upstream is still uses a TLS certificate as described below

version: v1
cluster:
  upstreams:
    - id: ds
      chain: auto
      provider: dshackle
      connection:
        grpc:
          host: 127.0.0.1
          port: 2449
          tls:
            ca: ca.myhost.dev.crt
            certificate: client_1.crt
            key: client_1.p8.key

Now if you run second server it will connect to first server ("upstream") running on port 2449, will verify upstream with certificate ca.myhost.dev.crt and authenticate itself by using pair of client_1.crt and client_1.p8.key

Server TLS configuration

Name Example Description

enabled

 
tls:
  enabled: true

Enabled or disable TLS. By default it checks if certificate is set, and then enables it. But if you enable the TLS but didn’t specify the certificate or key, then the DShackle will fails to start with error.

server.certificate, server.key

 
tls:
  server:
    certificate: server.com.crt
    key: server.com.p8.key

Path to certificate and certificate private key

client.ca, client.cas, client.required

 
tls:
  client:
    cas:
      - ca1.crt
      - ca2.crt
    required: true

Paths to CA used to authenticate incoming connections, used if required: true