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
  45     - *url* - Url to CMPv2 server
  46     - *issuerDN* - Distinguished Name of the CA that will sign the certificate
  47     - *caMode* - Issuer mode
  48     - *authentication*
  49
  50         - *iak* - Initial authentication key, used to authenticate request in CMPv2 server
  51         - *rv* - Reference values, used ti 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 HTTP endpoint.
  56
  57
  58 Configuring in local(docker-compose) deployment:
  59 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  60
  61 Static:
  62 """""""
  63
  64 1. Edit *cmpServers.json* file in certservice/compose-resources
  65 2. Start containers::
  66
  67     make start-backend
  68
  69 Dynamic:
  70 """"""""
  71
  72 1. Find CertService docker container name.
  73 2. Enter container::
  74
  75     docker exec -it <certservice-container-name> bash
  76
  77 3. Edit *cmpServers.json* file::
  78
  79     vim /etc/onap/aaf/certservice/cmpServers.json
  80
  81 4. Save
  82 5. Reload configuration::
  83
  84     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
  85
  86
  87 Configuring in OOM deployment:
  88 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  89
  90 Static:
  91 """""""
  92
  93 *Note! This must be executed before calling make all or needs remaking aaf Charts*
  94
  95 1. Edit *cmpServers.json* file
  96
  97    - if it's test deployment - edit *kubernetes/aaf/charts/aaf-cert-service/resources/test/cmpServers.json*
  98    - if it's normal deployment - edit *kubernetes/aaf/charts/aaf-cert-service/resources/default/cmpServers.json*
  99
 100 2. Build and start OOM deployment
 101
 102 Dynamic:
 103 """"""""
 104
 105 1. Encode your configuration to base64 (You can use for example online encoders or command line tool *base64*)
 106 2. Edit secret::
 107
 108     kubectl edit secret <cmp-servers-secret-name> # aaf-cert-service-secret by default
 109
 110 3. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
 111
 112   .. code-block:: yaml
 113
 114         apiVersion: v1
 115         data:
 116           cmpServers.json: <HERE_PLACE_YOUR_BASE64_ENCODED_CONFIG>
 117         kind: Secret
 118         metadata:
 119           creationTimestamp: "2020-04-21T16:30:29Z"
 120           name: aaf-cert-service-secret
 121           namespace: default
 122           resourceVersion: "33892990"
 123           selfLink: /api/v1/namespaces/default/secrets/aaf-cert-service-secret
 124           uid: 6a037526-83ed-11ea-b731-fa163e2144f6
 125         type: Opaque
 126
 127 4. Save and exit
 128 5. New configuration will be automatically mounted to CertService pod, but reload is needed.
 129 6. Enter CertService pod::
 130
 131     kubectl exec -it <cert-service-pod-name> bash
 132
 133 7. Reload configuration::
 134
 135     curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
 136
 137
 138 Generating certificates for CertService and CertService Client
 139 --------------------------------------------------------------
 140 CertService and CertService client use mutual TLS for communication. Certificates are generated using Makefile.
 141
 142 Local:
 143 ^^^^^^
 144
 145 Certificates are mounted to containers by docker volumes:
 146
 147     - CertService volumes are defined in certservice/docker-compose.yaml
 148     - CertClient volumes are defined in certservice/Makefile
 149
 150 All certificates are stored in *certservice/certs* directory. To recreate certificates go to *certservice/certs* directory and execute::
 151
 152     make clear all
 153
 154 This will clear existing certs and generate new ones.
 155
 156 OOM:
 157 ^^^^
 158
 159 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*.
 160 Secrets take certificates from *kubernetes/aaf/charts/aaf-cert-service/resources* directory. Certificates are generated automatically during building(using Make) OOM repository.
 161
 162 *kubernetes/aaf/charts/aaf-cert-service/Makefile* is similar to the one stored in certservice repository. It actually generates certificates.
 163 This Makefile is executed by *kubernetes/aaf/Makefile*, which is automatically executed during OOM build.
 164
 165
 166 Configuring EJBCA server for testing
 167 ------------------------------------
 168
 169 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.
 170
 171 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.
 172
 173 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.
 174
 175 Currently the recommended mode is single-layer RA mode.
 176
 177
 178 Default Values:
 179
 180 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 181 |  Name               | Value                                                                                                                           |
 182 +=====================+=================================================================================================================================+
 183 | Request URL         | http://aaf-ejbca:8080/ejbca/publicweb/cmp/cmpRA                                                                                 |
 184 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 185 | Response Type       | PKI Response                                                                                                                    |
 186 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 187 | caMode              | RA                                                                                                                              |
 188 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 189 | alias               | cmpRA                                                                                                                           |
 190 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 191
 192
 193 If you wish to configure the EJBCA server, you can find Documentation for EJBCA here: https://doc.primekey.com/ejbca/
 194
 195 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
 196