docs/sections/configuration.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2020-2021 NOKIA
   4
   5 Configuration
   6 ==============
   7
   8
   9 Configuring Cert Service
  10 ------------------------
  11 Cert Service keeps configuration of  CMP Servers in file *cmpServers.json*.
  12
  13 Example cmpServers.json file:
  14
  15 .. code-block:: json
  16
  17     {
  18       "cmpv2Servers": [
  19         {
  20           "caName": "Client",
  21           "url": "http://oomcert-ejbca:8080/ejbca/publicweb/cmp/cmp",
  22           "issuerDN": "CN=ManagementCA",
  23           "authentication": {
  24             "iak": "mypassword",
  25             "rv": "mypassword"
  26           }
  27         },
  28         {
  29           "caName": "RA",
  30           "url": "http://oomcert-ejbca:8080/ejbca/publicweb/cmp/cmpRA",
  31           "issuerDN": "CN=ManagementCA",
  32           "authentication": {
  33             "iak": "mypassword",
  34             "rv": "mypassword"
  35           }
  36         }
  37       ]
  38     }
  39
  40 This contains list of CMP Servers, where each server has following properties:
  41
  42     - *caName* - name of the external CA server. It's used to match *CA_NAME* sent by CertService client in order to match proper configuration.
  43     - *url* - URL to CMPv2 server
  44     - *issuerDN* - Distinguished Name of the CA that will sign the certificate
  45     - *authentication*
  46
  47         - *iak* - Initial authentication key, used to authenticate request in CMPv2 server
  48         - *rv* - Reference value, used to authenticate request in CMPv2 server
  49
  50
  51
  52 This configuration is read on the application start. It can also be reloaded in runtime, by calling HTTPS endpoint.
  53
  54 Next sections explain how to configure Cert Service in local (docker-compose) and OOM Deployments.
  55
  56
  57 Configuring in local (docker-compose) deployment:
  58 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  59
  60 Before application start:
  61 """""""""""""""""""""""""
  62
  63 1. Edit *cmpServers.json* file in certservice/compose-resources
  64 2. Start containers::
  65
  66     make start-backend
  67
  68 When application is running:
  69 """"""""""""""""""""""""""""
  70
  71 1. Find CertService docker container name.
  72 2. Enter container::
  73
  74     docker exec -it <certservice-container-name> bash
  75
  76     e.g.
  77     docker exec -it oomcert-service bash
  78
  79 3. Edit *cmpServers.json* file::
  80
  81     vim /etc/onap/oom/certservice/cmpServers.json
  82
  83 4. Save the file. Note that this file is mounted as volume, so change will be persistent.
  84 5. Reload configuration::
  85
  86     curl -I https://localhost:8443/reload --cacert /etc/onap/oom/certservice/certs/root.crt --cert-type p12 --cert /etc/onap/oom/certservice/certs/certServiceServer-keystore.p12 --pass $KEYSTORE_PASSWORD
  87
  88 6. Exit container::
  89
  90     exit
  91
  92
  93 Configuring in OOM deployment:
  94 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  95
  96 Before OOM installation:
  97 """"""""""""""""""""""""
  98
  99 Note! This must be executed before calling *make all* (from OOM Installation) or needs remaking OOM charts.
 100
 101
 102 1. Edit *cmpServers.json* file. If OOM *global.addTestingComponents* flag is set to:
 103
 104     - *true* - edit *kubernetes/platform/components/oom-cert-service/resources/test/cmpServers.json*
 105     - *false* - edit *kubernetes/platform/components/oom-cert-service/resources/default/cmpServers.json*
 106
 107 2. Build and start OOM deployment
 108
 109 When CertService is deployed:
 110 """""""""""""""""""""""""""""
 111
 112 1. Create file with configuration
 113
 114 2. Encode your configuration to base64::
 115
 116     cat <configuration_file> | base64
 117
 118 3. Edit secret::
 119
 120     kubectl -n onap edit secret <cmp-servers-secret-name>
 121
 122     e.g.
 123     kubectl -n onap edit secret oom-cert-service-secret
 124
 125 4. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
 126
 127   .. code-block:: yaml
 128
 129         apiVersion: v1
 130         data:
 131           cmpServers.json: <HERE_PLACE_YOUR_BASE64_ENCODED_CONFIG>
 132         kind: Secret
 133         metadata:
 134           creationTimestamp: "2020-04-21T16:30:29Z"
 135           name: oom-cert-service-secret
 136           namespace: default
 137           resourceVersion: "33892990"
 138           selfLink: /api/v1/namespaces/default/secrets/oom-cert-service-secret
 139           uid: 6a037526-83ed-11ea-b731-fa163e2144f6
 140         type: Opaque
 141
 142 5. Save and exit
 143 6. New configuration will be automatically mounted to CertService pod, but application configuration reload is needed.
 144 7. To reload configuration enter CertService pod::
 145
 146     kubectl -n onap exec -it <cert-service-pod-name> bash
 147
 148     e.g.
 149     kubectl -n onap exec -it $(kubectl -n onap get pods | grep cert-service | awk '{print $1}') bash
 150
 151 8. Reload configuration::
 152
 153     curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
 154
 155 9. Exit container::
 156
 157     exit
 158
 159
 160 Generating certificates for CertService and CMPv2 certificate provider
 161 ----------------------------------------------------------------------
 162 CertService and CMPv2 certificate provider use mutual TLS for communication. Certificates are generated during CertService installation.
 163
 164 Docker mode:
 165 ^^^^^^^^^^^^
 166
 167 Certificates are mounted to containers by docker volumes:
 168
 169     - CertService volumes are defined in certservice/docker-compose.yaml
 170
 171 All certificates are stored in *certservice/certs* directory. To recreate certificates go to *certservice/certs* directory and execute::
 172
 173     make clear all
 174
 175 This will clear existing certs and generate new ones.
 176
 177 ONAP OOM installation:
 178 ^^^^^^^^^^^^^^^^^^^^^^
 179
 180 Certificates are stored in secrets, which are mounted to pods as volumes. For CMPv2 certificate provider, certificates are delivered in CMPv2Issuer as secrets name with corresponding keys.
 181
 182 Both secrets definitions are stored in *kubernetes/platform/components/oom-cert-service/values.yaml* as *secrets:* key.
 183
 184 During platform component deployment, certificates in secrets are generated automatically using *Certificate* resources from cert-manager.
 185 Their definitions are stored in *kubernetes/platform/components/oom-cert-service/values.yaml* as *certificates:* key.
 186
 187
 188 Using external certificates for CertService and CMPv2 certificate provider
 189 --------------------------------------------------------------------------
 190
 191 This section describes how to use custom, external certificates for CertService and CMPv2 certificate provider communication in OOM installation.
 192
 193 1. Remove *certificates:* section from *kubernetes/platform/components/oom-cert-service/values.yaml*
 194
 195 2. Prepare secret for CertService. It must be provided before OOM installation. It must contain four files:
 196
 197     - *keystore.jks*  - keystore in JKS format. Signed by some Root CA
 198     - *keystore.p12* - same keystore in PKCS#12 format
 199     - *truststore.jks* - truststore in JKS format, containing certificates of the Root CA that signed CertService Client certificate
 200     - *ca.crt* - certificate of the RootCA that signed Client certificate in CRT format
 201
 202 3. Name the secret properly - the name should match *tls.server.secret.name* value from *kubernetes/platform/components/oom-cert-service/values.yaml* file
 203
 204 4. Prepare secret for CMPv2 certificate provider. It must be provided before OOM installation. It must contain three files:
 205
 206     - *tls.crt* - certificate in CRT format. Signed by some Root CA
 207     - *tls.key* - private key in KEY format
 208     - *ca.crt* - certificate of the RootCA that signed CertService certificate in CRT format
 209
 210 5. Name the secret properly - the name should match *global.oom.certService.client.secret.name* value from *kubernetes/onap/values.yaml* file
 211
 212 6. Provide keystore and truststore passwords (the same for both) for CertService. It can be done in two ways:
 213
 214     - by inlining them into *kubernetes/platform/components/oom-cert-service/values.yaml*:
 215
 216         - override *credentials.tls.certificatesPassword* value with keystore and truststore password
 217
 218     - or by providing them as secrets:
 219
 220         - uncomment *credentials.tls.certificatesPasswordExternalSecret* value and provide keystore and truststore password
 221
 222
 223 Configuring EJBCA server for testing
 224 ------------------------------------
 225
 226 To instantiate an EJBCA server for testing purposes with an OOM deployment, cmpv2Enabled and cmpv2Testing have to be changed to true in oom/kubernetes/platform/values.yaml.
 227
 228 cmpv2Enabled has to be true to enable oom-cert-service to be instantiated and used with an external Certificate Authority to get certificates for secure communication.
 229
 230 If cmpv2Testing is enabled then an EJBCA test server will be instantiated in the OOM deployment as well, and will come pre-configured with a test CA to request a certificate from.
 231
 232 Currently the recommended mode is single-layer RA mode.
 233
 234
 235 Default Values:
 236
 237 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 238 |  Name               | Value                                                                                                                           |
 239 +=====================+=================================================================================================================================+
 240 | Request URL         | http://ejbca:8080/ejbca/publicweb/cmp/cmpRA                                                                                     |
 241 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 242 | Response Type       | PKI Response                                                                                                                    |
 243 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 244 | caMode              | RA                                                                                                                              |
 245 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 246 | alias               | cmpRA                                                                                                                           |
 247 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 248
 249
 250 If you wish to configure the EJBCA server, you can find Documentation for EJBCA here: https://doc.primekey.com/ejbca/
 251
 252 If you want to understand how CMP works on EJBCA in more detail, you can find Details here: https://download.primekey.com/docs/EJBCA-Enterprise/6_14_0/CMP.html
 253