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 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 3. Edit *cmpServers.json* file::
  80
  81     vim /etc/onap/aaf/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/aaf/certservice/certs/root.crt --cert-type p12 --cert /etc/onap/aaf/certservice/certs/certServiceServer-keystore.p12 --pass secret
  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 aaf Charts.
 100
 101
 102 1. Edit *cmpServers.json* file. If OOM *global.addTestingComponents* flag is set to:
 103
 104     - *true* - edit *kubernetes/aaf/charts/aaf-cert-service/resources/test/cmpServers.json*
 105     - *false* - edit *kubernetes/aaf/charts/aaf-cert-service/resources/default/cmpServers.json*
 106
 107 2. Build and start OOM deployment
 108
 109 When CertService is deployed:
 110 """""""""""""""""""""""""""""
 111
 112 1. Encode your configuration to base64::
 113
 114     echo "CONFIGURATION_TO_ENCODE" | base64
 115
 116 2. Edit secret::
 117
 118     kubectl edit secret <cmp-servers-secret-name> # aaf-cert-service-secret by default
 119
 120 3. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
 121
 122   .. code-block:: yaml
 123
 124         apiVersion: v1
 125         data:
 126           cmpServers.json: <HERE_PLACE_YOUR_BASE64_ENCODED_CONFIG>
 127         kind: Secret
 128         metadata:
 129           creationTimestamp: "2020-04-21T16:30:29Z"
 130           name: aaf-cert-service-secret
 131           namespace: default
 132           resourceVersion: "33892990"
 133           selfLink: /api/v1/namespaces/default/secrets/aaf-cert-service-secret
 134           uid: 6a037526-83ed-11ea-b731-fa163e2144f6
 135         type: Opaque
 136
 137 4. Save and exit
 138 5. New configuration will be automatically mounted to CertService pod, but application configuration reload is needed.
 139 6. To reload configuration enter CertService pod::
 140
 141     kubectl exec -it <cert-service-pod-name> bash
 142
 143 7. Reload configuration::
 144
 145     curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
 146
 147 8. Exit container::
 148
 149     exit
 150
 151
 152 Generating certificates for CertService and CertService Client
 153 --------------------------------------------------------------
 154 CertService and CertService client use mutual TLS for communication. Certificates are generated during CertService installation.
 155
 156 Docker mode:
 157 ^^^^^^^^^^^^
 158
 159 Certificates are mounted to containers by docker volumes:
 160
 161     - CertService volumes are defined in certservice/docker-compose.yaml
 162     - CertService Client volumes are defined in certservice/Makefile
 163
 164 All certificates are stored in *certservice/certs* directory. To recreate certificates go to *certservice/certs* directory and execute::
 165
 166     make clear all
 167
 168 This will clear existing certs and generate new ones.
 169
 170 ONAP OOM installation:
 171 ^^^^^^^^^^^^^^^^^^^^^^
 172
 173 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*.
 174 Secrets take certificates from *kubernetes/aaf/charts/aaf-cert-service/resources* directory. Certificates are generated automatically during building (using Make) OOM repository.
 175
 176 *kubernetes/aaf/charts/aaf-cert-service/Makefile* is similar to the one stored in certservice repository. It actually generates certificates.
 177 This Makefile is executed by *kubernetes/aaf/Makefile*, which is automatically executed during OOM build.
 178
 179
 180 Using external certificates for CertService and CertService Client
 181 ------------------------------------------------------------------
 182
 183 This section describes how to use custom, external certificates for CertService and CertService Client communication in OOM installation.
 184
 185 1. Set *tls.certificateExternalSecret* flag to true in *kubernetes/aaf/charts/aaf-cert-service/values.yaml*
 186 2. Prepare secret for CertService. It must be provided before OOM installation. It must contain four files:
 187
 188     - *certServiceServer-keystore.jks*  - keystore in jks format. Signed by some Root CA
 189     - *certServiceServer-keystore.p12* - same keystore in p12 format
 190     - *truststore.jks* - truststore in jks format, containing certificates of the Root CA that signed CertService Client certificate
 191     - *root.crt* - certificate of the RootCA that signed Client certificate in crt format
 192
 193 3. Name the secret properly - the name should match *tls.server.secret.name* value from *kubernetes/aaf/charts/aaf-cert-service/values.yaml* file
 194
 195 4. Prepare secret for CertService Client. It must be provided before OOM installation. It must contain two files:
 196
 197     - *certServiceClient-keystore.jks*  - keystore in jks format. Signed by some Root CA
 198     - *truststore.jks* - truststore in jks format, containing certificates of the RootCA that signed CertService certificate
 199
 200 5. Name the secret properly - the name should match *global.aaf.certService.client.secret.name*
 201
 202 6. Provide keystore and truststore passwords for CertService. It can be done in two ways:
 203
 204     - by inlining them into *kubernetes/aaf/charts/aaf-cert-service/values.yaml*:
 205
 206         - override *credentials.tls.keystorePassword* value with keystore password
 207         - override *credentials.tls.truststorePassword* value with truststore password
 208
 209     - or by providing them as secrets:
 210
 211         - uncomment *credentials.tls.keystorePasswordExternalSecret* value and provide keystore password
 212         - uncomment *credentials.tls.truststorePasswordExternalSecret* value and provide truststore password
 213
 214 7. Override default keystore and truststore passwords for CertService Client in *kubernetes/onap/values.yaml* file:
 215
 216     - override *global.aaf.certServiceClient.envVariables.keystorePassword* value with keystore password
 217     - override *global.aaf.certServiceClient.envVariables.truststorePassword* value with truststore password
 218
 219
 220 Configuring EJBCA server for testing
 221 ------------------------------------
 222
 223 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.
 224
 225 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.
 226
 227 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.
 228
 229 Currently the recommended mode is single-layer RA mode.
 230
 231
 232 Default Values:
 233
 234 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 235 |  Name               | Value                                                                                                                           |
 236 +=====================+=================================================================================================================================+
 237 | Request URL         | http://aaf-ejbca:8080/ejbca/publicweb/cmp/cmpRA                                                                                 |
 238 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 239 | Response Type       | PKI Response                                                                                                                    |
 240 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 241 | caMode              | RA                                                                                                                              |
 242 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 243 | alias               | cmpRA                                                                                                                           |
 244 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 245
 246
 247 If you wish to configure the EJBCA server, you can find Documentation for EJBCA here: https://doc.primekey.com/ejbca/
 248
 249 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
 250