docs/cert_installation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 ============================================================
   5 Installing Keys and Certificates in ODL for NETCONF over TLS
   6 ============================================================
   7
   8 The purpose of this document is to help you with the setup needed for the installation of xNF keys and certificates inside of OpenDaylight(ODL) in SDNC.
   9
  10 To use NETCONF over TLS, ODL needs to be configured with Keys and Certificates to use for TLS connections.
  11
  12 Preparing Required Key and Certificate Files
  13 ============================================
  14
  15 The first step to adding the keys and certificates for ODL is to have configured a zip file made up of your keys and certificates that ODL needs.
  16
  17 There are three files required in the zip file and those are:
  18     1. client.crt
  19     2. client.key
  20     3. trustedCertificates.crt which contains a list of trusted certificates - normally one or more CA or sub-CA certificates, or xNF self-signed certificate(s) for testing only
  21
  22 Client.crt represents the client certificate and the client.key is the private key that is to be used.
  23 Only a single client/client cert is supported as of the Dublin release and multiple clients are not supported.
  24
  25 These files will all be needed when configuring ODL’s private key, own certificate and trusted certificates.
  26
  27 An example of the three required files that are needed in the zip folder can be seen  in the screenshots below:
  28
  29
  30         .. image:: images/client_certificate.png
  31            :align: center
  32
  33
  34         .. image:: images/client_key.png
  35            :align: center
  36
  37
  38         .. image:: images/trusted_certificate.png
  39            :align: center
  40
  41
  42
  43 Once you have these three files created you need to create a zip file from these files.
  44 You will then have to add the name of this zip file to a file called certs.properties file.
  45 You should use the naming convention “keys<IncrementedNumber>.zip” that is used in the screenshot below and that between each zip file there is a new line with “\*****” between each zip file.
  46 Since the Dublin release only supports a single client this means that there should be only one zip file present.
  47
  48 Below is an image of how the certs.properties files should be written:
  49
  50         .. image:: images/certs_properties.png
  51
  52
  53
  54 How to Install Certs and Keys when deploying SDNC/ODL with OOM in K8s environment
  55 =================================================================================
  56
  57 At setup time, you will need to place the zip file along with the certs.properties file in the following file path:
  58    */docker-data/sdnc/certs/*
  59
  60 Placing the files in this location will ensure that your files are mounted into the SDNC container at run time in the /tmp folder.
  61
  62 If you are running in a Kubernetes container and would like to edit the default mount path you need to go to the following path:
  63         *oom/kubernetes/sdnc/values.yaml*
  64
  65
  66 If you have your zip file and the certs.properties file set up correctly at setup-time, these RPC’s will automatically be called from the installCerts.py file and your keys and certificates will be added to the ODL keystore for you.
  67
  68 The last step that is needed once you have your zip file and certs.properties file in the correct folder you need to run the following command to deploy ONAP:
  69
  70 .. code-block:: bash
  71
  72         helm deploy dev local/onap -f /root/oom/kubernetes/onap/resources/environments/public-cloud.yaml -f /root/integration-override.yaml --namespace onap --verbose
  73
  74 Or if you do not want to deploy the full ONAP but just SDNC container run:
  75
  76 .. code-block:: bash
  77
  78         helm upgrade -i dev-sdnc <path to sdnc chart> --namespace onap  -f <path to global override> -f <path to sdnc sub chart>
  79
  80 Example of this full command is:
  81
  82 .. code-block:: bash
  83
  84         helm upgrade -i dev-sdnc /root/.helm/plugins/deploy/cache/onap-subcharts/sdnc --namespace onap -f /root/.helm/plugins/deploy/cache/onap/global-overrides.yaml -f /root/.helm/plugins/deploy/cache/onap-subcharts/sdnc/subchart-overrides.yaml
  85
  86
  87 How to Install Certs and Keys when deploying SDNC/ODL with docker-compose
  88 =========================================================================
  89
  90 If you want to do a local installation of SDNC/ODL with docker-compose you need to first download the OAM repo from the gerrit repo with the following URL.
  91
  92         *git clone https://gerrit.onap.org/r/sdnc/oam*
  93
  94 Once you have this downloaded you need to go the following location.
  95
  96         */oam/installation/src/main/yaml*
  97
  98 Once you are there you need to edit the docker-compose.yaml file to include your directory where you have the zip file and certs.properties located.
  99
 100 You need to add in the following lines into the yaml file just below *container_name: sdnc_controller_container* in the file::
 101
 102         volumes:
 103           - <Your_Workspace>:/opt/opendaylight/current/certs
 104
 105 Once you have the mount path for your files added into the yaml file you can run the following command::
 106
 107         docker-compose up -d
 108
 109
 110 Clustering:
 111 =============
 112
 113 For running a Kubernetes cluster using a pre-built SDNC image the keys and certificates only need to be placed on a single mount point and not put on each image individually as the keys and certificates will be replicated across all instances in the cluster.
 114
 115 To get your Kubernetes running in a cluster, you need to SSH into your Rancher machine that your pods are running on and go to the directory:
 116
 117         */root/oom/kubernetes/sdnc/*
 118
 119 In this directory you will find the values.yaml file which is the one you will need to edit. You need to find the variable *replicaCount* which is the default number of instances and change that value to 3 for clustering and also look for config: enableClustering and ensure that it is set to true.
 120
 121 Once this is edited you will need to stop the SDNC container with the command:
 122
 123 .. code-block:: bash
 124
 125         helm delete --purge dev-sdnc
 126
 127         make all
 128
 129         helm upgrade -i dev-sdnc /root/oom/kubernetes/sdnc --namespace onap -f /root/.helm/plugins/deploy/cache/onap/global-overrides.yaml -f /root/.helm/plugins/deploy/cache/onap-subcharts/sdnc/subchart-overrides.yaml
 130
 131
 132 EXAMPLE: Mounting pnf-simulator
 133 ===============================
 134
 135 If you want to mount a pnf-simulator onto the SDNC container the you must have the pnf-simulator container up and running and the SDNC container running with the keys and certificates in the ODL keystore.
 136
 137 To mount your pnf-simulator you must send the following RPC:
 138     *PUT /restconf/config/network-topology:network-topology/topology/topology-netconf/node/pnf-simulator*
 139
 140
 141 You must also send this as the body of the request::
 142
 143     <node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
 144         <node-id>pnf-simulator</node-id>
 145         <key-based xmlns="urn:opendaylight:netconf-node-topology">
 146             <key-id xmlns="urn:opendaylight:netconf-node-topology">ODL_private_key_0</key-id>
 147              <username xmlns="urn:opendaylight:netconf-node-topology">netconf</username>
 148          </key-based>
 149          <host xmlns="urn:opendaylight:netconf-node-topology">IP-ADDRESS</ip-address></host>
 150          <port xmlns="urn:opendaylight:netconf-node-topology">6513</port>
 151          <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
 152              <protocol xmlns="urn:opendaylight:netconf-node-topology">
 153              <name xmlns="urn:opendaylight:netconf-node-topology">TLS</name>
 154          </protocol>
 155          <max-connection-attempts xmlns="urn:opendaylight:netconf-node-topology">2</max-connection-attempts>
 156      </node>
 157
 158
 159 where IP-ADDRESS is the ip-address you are trying to mount the pnf-simulator on.
 160
 161
 162
 163 APPENDIX:
 164 ===========
 165
 166 ODL Commands
 167 ~~~~~~~~~~~~~
 168 There are three RPC’s needed to configure the keys and certificates for TLS and these are:
 169
 170     1. “add-keystore-entry”
 171     2. “add-private-keys”
 172     3. “add-trusted-certificate”
 173
 174 These three commands will be implemented by scripts in the SDNC container so these will all be implemented automatically.
 175
 176 add-keystore-entry
 177 -----------------------------
 178 This is used to add the client private key from the xNF and a key-id to ODL’s TLS keystore. This is triggered with a POST command on ODL’s keystore operations.
 179
 180 The “private-key” data is taken form the client.key file.
 181
 182 add-private-keys
 183 ---------------------------
 184 This is used to associate the private key with the client certificate and CA from the xNF and add it to the ODL keystore.
 185
 186
 187 add-trusted-certificate
 188 -------------------------------------
 189 This is used to add the list of CA’s and server certificates from the xnf as trusted certificates. The trustedCertificates.crt file is needed for this action as it contains the list of CA’s.
 190
 191
 192 Checking Correct Certs Installation
 193 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 194 If you would like to run a check to make sure that your keys and certificates were installed correctly in ODL you can run the following command in Postman REST client:
 195         *GET http://localhost:8282/restconf/config/netconf-keystore:keystore*
 196
 197 The authorization that is needed to gain access to ODL’s restconf interface is the default SDNC username and password.
 198
 199 You should get a response back which looks like the screenshot below:
 200
 201         .. image:: images/get_keystore.png
 202
 203
 204
 205
 206
 207
 208 ODL APIs:
 209 --------------
 210
 211 The ODL features that are installed by the SDNC script are:
 212
 213         **odl-restconf-all**
 214
 215         **odl-mdsal-all**
 216
 217         **odl-netconf-topology**
 218
 219 When we are using a clustered topology some of these features are replaced by other features.
 220         **odl-netconf-clustered-topology** replaces **odl-netconf-topology**  as these two features cannot be installed together as it will break ODL.
 221
 222         **odl-mdsal-clustering** also gets installed.