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