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 map the zip file and certs.properties file into the container.
  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>/certs.properties:/opt/opendaylight/certs/certs.properties
 104           - <Your_Workspace>/keys0.zip:/opt/opendaylight/certs/keys0.zip
 105
 106 Once you have the mount path for your files added into the yaml file you can run the following command::
 107
 108         docker-compose up -d
 109
 110
 111 Clustering:
 112 =============
 113
 114 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.
 115
 116 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:
 117
 118         */root/oom/kubernetes/sdnc/*
 119
 120 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.
 121
 122 Once this is edited you will need to stop the SDNC container with the command:
 123
 124 .. code-block:: bash
 125
 126         helm delete --purge dev-sdnc
 127
 128         make all
 129
 130         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
 131
 132
 133 EXAMPLE: Mounting pnf-simulator
 134 ===============================
 135
 136 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.
 137
 138 To mount your pnf-simulator you must send the following RPC:
 139     *PUT /restconf/config/network-topology:network-topology/topology/topology-netconf/node/pnf-simulator*
 140
 141
 142 You must also send this as the body of the request::
 143
 144     <node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
 145         <node-id>pnf-simulator</node-id>
 146         <key-based xmlns="urn:opendaylight:netconf-node-topology">
 147             <key-id xmlns="urn:opendaylight:netconf-node-topology">ODL_private_key_0</key-id>
 148              <username xmlns="urn:opendaylight:netconf-node-topology">netconf</username>
 149          </key-based>
 150          <host xmlns="urn:opendaylight:netconf-node-topology">IP-ADDRESS</ip-address></host>
 151          <port xmlns="urn:opendaylight:netconf-node-topology">6513</port>
 152          <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
 153              <protocol xmlns="urn:opendaylight:netconf-node-topology">
 154              <name xmlns="urn:opendaylight:netconf-node-topology">TLS</name>
 155          </protocol>
 156          <max-connection-attempts xmlns="urn:opendaylight:netconf-node-topology">2</max-connection-attempts>
 157      </node>
 158
 159
 160 where IP-ADDRESS is the ip-address you are trying to mount the pnf-simulator on.
 161
 162
 163
 164
 165 New secure communication functionality
 166 =================================================================================
 167
 168 In order to ensure secure communication on southband interface a new functionality have been introduced. The Certificate Management Protocol ver. 2 (CMPv2) is handled by the AAF microservice CertService.
 169
 170 SDNC is capable of obtaining certificates signed by an external Certificate Authority to secure external ONAP communication.
 171
 172 Confirmation of this functionality can be performed in OOM using the Contrib projects EJBCA service.
 173
 174 Firstly, CertService will need to be deployed. This will require the global flag *global.cmpv2Enabled* to be set to true in *kubernetes/onap/resources/overrides/aaf-cert-service-environment.yaml*
 175
 176 There is also an additional module that will need to be deployed named platform. This is required for secret creation.
 177
 178 To deploy the EJBCA server the global flag *global.addTestingComponents* in  *kubernetes/onap/values.yaml* will need to be set to true. This flag will load the test configuration from *kubernetes/aaf/charts/aaf-cert-service/resources/test/cmpServers.json*
 179
 180
 181
 182 cmpServers.json:
 183
 184 .. code-block:: json
 185
 186     {
 187       "cmpv2Servers": [
 188         {
 189           "caName": "Client",
 190           "url": "http://aafcert-ejbca:8080/ejbca/publicweb/cmp/cmp",
 191           "issuerDN": "CN=ManagementCA",
 192           "caMode": "CLIENT",
 193           "authentication": {
 194             "iak": "mypassword",
 195             "rv": "mypassword"
 196           }
 197         },
 198         {
 199           "caName": "RA",
 200           "url": "http://aafcert-ejbca:8080/ejbca/publicweb/cmp/cmpRA",
 201           "issuerDN": "CN=ManagementCA",
 202           "caMode": "RA",
 203           "authentication": {
 204             "iak": "mypassword",
 205             "rv": "mypassword"
 206           }
 207         }
 208       ]
 209     }
 210
 211
 212
 213 SDNC invokes the CertService in a new initContainer called certs-init.
 214
 215 There are a number of variables used that can be configured and these are available in *kubernetes/onap/values.yaml* under aaf/certServiceClient
 216
 217
 218
 219 CertService configuration:
 220
 221 .. code-block:: yaml
 222
 223  aaf:
 224     certServiceClient:
 225       image: onap/org.onap.aaf.certservice.aaf-certservice-client:1.0.0
 226       secret:
 227         name: aaf-cert-service-client-tls-secret
 228         mountPath: /etc/onap/aaf/certservice/certs/
 229       envVariables:
 230         # Certificate related
 231         cmpv2Organization: "Linux-Foundation"
 232         cmpv2OrganizationalUnit: "ONAP"
 233         cmpv2Location: "San-Francisco"
 234         cmpv2State: "California"
 235         cmpv2Country: "US"
 236         # Client configuration related
 237         caName: "RA"
 238         requestURL: "https://aaf-cert-service:8443/v1/certificate/"
 239         requestTimeout: "20000"
 240         keystorePath: "/etc/onap/aaf/certservice/certs/certServiceClient-keystore.jks"
 241         keystorePassword: "secret"
 242         truststorePath: "/etc/onap/aaf/certservice/certs/truststore.jks"
 243         truststorePassword: "secret"
 244
 245
 246
 247
 248 For more information:
 249
 250 +------------------------------------------------------------------------------------------+
 251 |https://onap-doc.readthedocs.io/en/latest/submodules/aaf/certservice.git/docs/index.html  |
 252 +------------------------------------------------------------------------------------------+
 253 |https://doc.primekey.com/ejbca                                                            |
 254 +------------------------------------------------------------------------------------------+
 255
 256
 257
 258
 259 APPENDIX:
 260 ===========
 261
 262 ODL Commands
 263 ~~~~~~~~~~~~~
 264 There are three RPC’s needed to configure the keys and certificates for TLS and these are:
 265
 266     1. “add-keystore-entry”
 267     2. “add-private-keys”
 268     3. “add-trusted-certificate”
 269
 270 These three commands will be implemented by scripts in the SDNC container so these will all be implemented automatically.
 271
 272 add-keystore-entry
 273 -----------------------------
 274 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.
 275
 276 The “private-key” data is taken form the client.key file.
 277
 278 add-private-keys
 279 ---------------------------
 280 This is used to associate the private key with the client certificate and CA from the xNF and add it to the ODL keystore.
 281
 282
 283 add-trusted-certificate
 284 -------------------------------------
 285 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.
 286
 287
 288 Checking Correct Certs Installation
 289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 290 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:
 291         *GET http://localhost:8282/restconf/config/netconf-keystore:keystore*
 292
 293 The authorization that is needed to gain access to ODL’s restconf interface is the default SDNC username and password.
 294
 295 You should get a response back which looks like the screenshot below:
 296
 297         .. image:: images/get_keystore.png
 298
 299
 300
 301
 302
 303
 304 ODL APIs:
 305 --------------
 306
 307 The ODL features that are installed by the SDNC script are:
 308
 309         **odl-restconf-all**
 310
 311         **odl-mdsal-all**
 312
 313         **odl-netconf-topology**
 314
 315 When we are using a clustered topology some of these features are replaced by other features.
 316         **odl-netconf-clustered-topology** replaces **odl-netconf-topology**  as these two features cannot be installed together as it will break ODL.
 317
 318         **odl-mdsal-clustering** also gets installed.