docs/usecases/contiv/SECURITY.md

   1 # Security
   2
   3 There are two types of security that are utilized in Contiv, and are discussed in this section: [HTTP](#http-security) and [ETCD](#etcd-security).
   4
   5 ## HTTP Security
   6
   7 By default, the access to endpoints (liveness, readiness probe, prometheus stats, ...) served by Contiv-vswitch and
   8 Contiv-ksr is open to anybody. Contiv-vswitch exposes endpoints using port `9999` and contiv-ksr uses `9191`.
   9
  10 To secure access to the endpoints, the SSL/TLS server certificate and basic auth (username password) can be configured.
  11
  12 In Contiv-VPP, this can be done using the Helm charts in [k8s/contiv-vpp folder](https://github.com/contiv/vpp/tree/master/k8s/contiv-vpp).
  13
  14 To generate server certificate the approach described in [ETCD security](#etcd-security) can be leveraged.
  15
  16 ## ETCD Security
  17
  18 By default, the access to Contiv-VPP ETCD is open to anybody. ETCD gets deployed
  19 on the master node, on port `12379`, and is exposed using the NodePort service
  20 on port `32379`, on each node.
  21
  22 To secure access to ETCD, we recommend using the SSL/TLS certificates to authenticate
  23 both the client and server side, and encrypt the communication. In Contiv-VPP, this can be done using the Helm charts in [k8s/contiv-vpp folder](https://github.com/contiv/vpp/tree/master/k8s/contiv-vpp).
  24
  25 The prerequisite for that is the generation of SSL certificates.
  26
  27
  28 ### Generate Self-Signed Certificates
  29 In order to secure ETCD, we need to create our own certificate authority,
  30 and then generate the private keys and certificates for both the ETCD server and ETCD clients.
  31
  32 This guide uses CloudFlare's [cfssl](https://github.com/cloudflare/cfssl) tools to do this job.
  33 It follows the steps described in this [CoreOS guide](https://github.com/coreos/docs/blob/master/os/generate-self-signed-certificates.md).
  34
  35 Perform the following steps to generate private keys and certificates:
  36
  37 ##### 1. Install cfssl
  38 ```
  39 mkdir ~/bin
  40 curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64
  41 curl -s -L -o ~/bin/cfssljson https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64
  42 chmod +x ~/bin/{cfssl,cfssljson}
  43 export PATH=$PATH:~/bin
  44 ```
  45
  46 ##### 2. Initialize a Certificate Authority
  47 ```
  48 echo '{"CN":"CA","key":{"algo":"rsa","size":2048}}' | cfssl gencert -initca - | cfssljson -bare ca -
  49 echo '{"signing":{"default":{"expiry":"43800h","usages":["signing","key encipherment","server auth","client auth"]}}}' > ca-config.json
  50 ```
  51
  52 ##### 3. Generate Server Key + Certificate
  53 Replace the IP address `10.0.2.15` below with the IP address of your master node:
  54 ```
  55 export ADDRESS=127.0.0.1,10.0.2.15
  56 export NAME=server
  57 echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -ca=ca.pem -ca-key=ca-key.pem -hostname="$ADDRESS" - | cfssljson -bare $NAME
  58 ```
  59
  60 ##### 4. Generate Client Key + Certificate
  61 ```
  62 export ADDRESS=
  63 export NAME=client
  64 echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -ca=ca.pem -ca-key=ca-key.pem -hostname="$ADDRESS" - | cfssljson -bare $NAME
  65 ```
  66
  67 The above commands produce the following files that will be needed in order to secure ETCD:
  68  - `ca.pem`: certificate of the certificate authority
  69  - `server.pem`: certificate of the ETCD server
  70  - `server-key.pem`: private key of the ETCD server
  71  - `client.pem`: certificate for the ETCD clients
  72  - `client-key.pem`: private key for the ETCD clients
  73
  74
  75 ### Distribute Certificates and Generate Contiv-VPP Deployment Yaml
  76 There are two options for distributing the certificates to all nodes in a k8s cluster.
  77 You can either distribute the certificates
  78 [manually](#distribute-certificates-manually), or embed the certificates into the deployment yaml file and
  79 distribute them as [k8s secrets](https://kubernetes.io/docs/concepts/configuration/secret/).
  80
  81 ##### Distribute Certificates Manually
  82 In this case, you need to copy the `ca.pem`, `client.pem` and `client-key.pem` files
  83 into a specific folder (`/var/contiv/etcd-secrets` by default) on each worker node.
  84 On the master node, you also need to add the `server.pem` and `server-key.pem` into that location.
  85
  86 Then you can generate the Contiv-VPP deployment YAML as follows:
  87 ```
  88 cd k8s
  89 helm template --name my-release contiv-vpp --set etcd.secureTransport=True > contiv-vpp.yaml
  90 ```
  91 Then you can go ahead and deploy Contiv-VPP using this yaml file.
  92
  93 ##### Embed the certificates into deployment the yaml and use k8s secret to distribute them {: #Embed-certificates }
  94 In this case, you need to copy all 5 generated files into the folder with helm definitions
  95 (`k8s/contiv-vpp`) and generate the Contiv-VPP deployment YAML as follows:
  96 ```
  97 cd k8s
  98 helm template --name my-release contiv-vpp --set etcd.secureTransport=True --set etcd.secrets.mountFromHost=False > contiv-vpp.yaml
  99 ```
 100 Then just deploy Contiv-VPP using this yaml file.
 101
 102 Please note that the path of the mount folder with certificates, as well as the certificate
 103 file names can be customized using the config parameters of the Contiv-VPP chart,
 104 as described in [this README](https://github.com/contiv/vpp/blob/master/k8s/contiv-vpp/README.md).