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 Standalone docker container
   9 ---------------------------
  10
  11 Certification Service Client image:
  12
  13 .. code-block::
  14
  15   nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
  16
  17
  18 1. Create file with environments as in example below.
  19
  20 .. code-block::
  21
  22   #Client envs
  23   REQUEST_URL=http://aaf-cert-service:8080/v1/certificate/
  24   REQUEST_TIMEOUT=1000
  25   OUTPUT_PATH=/var/certs
  26   CA_NAME=RA
  27   #Csr config envs
  28   COMMON_NAME=onap.org
  29   ORGANIZATION=Linux-Foundation
  30   ORGANIZATION_UNIT=ONAP
  31   LOCATION=San-Francisco
  32   STATE=California
  33   COUNTRY=US
  34   SANS=test.onap.org:onap.com
  35
  36
  37 2. Run docker container with environments file and docker network (API and client must be running in same network).
  38
  39 .. code-block:: bash
  40
  41   AAFCERT_CLIENT_IMAGE=nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
  42   DOCKER_ENV_FILE= <path to environment file>
  43   NETWORK_CERT_SERVICE= <docker network of cert service>
  44   DOCKER_VOLUME="<absolute path to local dir>:<output path>"
  45
  46   docker run --env-file $DOCKER_ENV_FILE --network $NETWORK_CERT_SERVICE --volume $DOCKER_VOLUME $AAFCERT_CLIENT_IMAGE
  47
  48
  49 Configuring Cert Service
  50 ------------------------
  51 Cert Service keeps configuration of  CMP Servers in file *cmpServers.json*.
  52
  53 Example cmpServers.json file:
  54
  55 .. code-block:: json
  56
  57     {
  58       "cmpv2Servers": [
  59         {
  60           "caName": "Client",
  61           "url": "http://aafcert-ejbca:8080/ejbca/publicweb/cmp/cmp",
  62           "issuerDN": "CN=ManagementCA",
  63           "caMode": "CLIENT",
  64           "authentication": {
  65             "iak": "mypassword",
  66             "rv": "mypassword"
  67           }
  68         },
  69         {
  70           "caName": "RA",
  71           "url": "http://aafcert-ejbca:8080/ejbca/publicweb/cmp/cmpRA",
  72           "issuerDN": "CN=ManagementCA",
  73           "caMode": "RA",
  74           "authentication": {
  75             "iak": "mypassword",
  76             "rv": "mypassword"
  77           }
  78         }
  79       ]
  80     }
  81
  82 This contains list of CMP Servers, where each server has following properties:
  83
  84     - *caName* - name of the external CA server
  85     - *url* - Url to CMPv2 server
  86     - *issuerDN* - Distinguished Name of the CA that will sign the certificate
  87     - *caMode* - Issuer mode
  88     - *authentication*
  89
  90         - *iak* - Initial authentication key, used to authenticate request in CMPv2 server
  91         - *rv* - Reference values, used ti authenticate request in CMPv2 server
  92
  93
  94
  95 This configuration is read on the application start. It can also be reloaded in runtime, by calling HTTP endpoint.
  96
  97
  98 Configuring in local(docker-compose) deployment:
  99 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 100
 101 Static:
 102 """""""
 103
 104 1. Edit *cmpServers.json* file in certservice/compose-resources
 105 2. Start containers::
 106
 107     make start-backend
 108
 109 Dynamic:
 110 """"""""
 111
 112 1. Find CertService docker container name.
 113 2. Enter container::
 114
 115     docker exec -it <certservice-container-name> bash
 116
 117 3. Edit *cmpServers.json* file::
 118
 119     vim /etc/onap/aaf/certservice/cmpServers.json
 120
 121 4. Save
 122 5. Reload configuration::
 123
 124     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
 125
 126
 127 Configuring in OOM deployment:
 128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 129
 130 Static:
 131 """""""
 132
 133 *Note! This must be executed before calling make all or needs remaking aaf Charts*
 134
 135 1. Edit *cmpServers.json* file
 136
 137    - if it's test deployment - edit *kubernetes/aaf/charts/aaf-cert-service/resources/test/cmpServers.json*
 138    - if it's normal deployment - edit *kubernetes/aaf/charts/aaf-cert-service/resources/default/cmpServers.json*
 139
 140 2. Build and start OOM deployment
 141
 142 Dynamic:
 143 """"""""
 144
 145 1. Encode your configuration to base64 (You can use for example online encoders or command line tool *base64*)
 146 2. Edit secret::
 147
 148     kubectl edit secret <cmp-servers-secret-name> # aaf-cert-service-secret by default
 149
 150 3. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
 151
 152   .. code-block:: yaml
 153
 154         apiVersion: v1
 155         data:
 156           cmpServers.json: <HERE_PLACE_YOUR_BASE64_ENCODED_CONFIG>
 157         kind: Secret
 158         metadata:
 159           creationTimestamp: "2020-04-21T16:30:29Z"
 160           name: aaf-cert-service-secret
 161           namespace: default
 162           resourceVersion: "33892990"
 163           selfLink: /api/v1/namespaces/default/secrets/aaf-cert-service-secret
 164           uid: 6a037526-83ed-11ea-b731-fa163e2144f6
 165         type: Opaque
 166
 167 4. Save and exit
 168 5. New configuration will be automatically mounted to CertService pod, but reload is needed.
 169 6. Enter CertService pod::
 170
 171     kubectl exec -it <cert-service-pod-name> bash
 172
 173 7. Reload configuration::
 174
 175     curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
 176
 177
 178 Generating certificates for CertService and CertService Client
 179 --------------------------------------------------------------
 180 CertService and CertService client use mutual TLS for communication. Certificates are generated using Makefile.
 181
 182 Local:
 183 ^^^^^^
 184
 185 Certificates are mounted to containers by docker volumes:
 186
 187     - CertService volumes are defined in certservice/docker-compose.yaml
 188     - CertClient volumes are defined in certservice/Makefile
 189
 190 All certificates are stored in *certservice/certs* directory. To recreate certificates go to *certservice/certs* directory and execute::
 191
 192     make clear all
 193
 194 This will clear existing certs and generate new ones.
 195
 196 OOM:
 197 ^^^^
 198
 199 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*.
 200 Secrets take certificates from *kubernetes/aaf/charts/aaf-cert-service/resources* directory. Certificates are generated automatically during building(using Make) OOM repository.
 201
 202 *kubernetes/aaf/charts/aaf-cert-service/Makefile* is similar to the one stored in certservice repository. It actually generates certificates.
 203 This Makefile is executed by *kubernetes/aaf/Makefile*, which is automatically executed during OOM build.
 204
 205
 206 Configuring EJBCA server for testing
 207 ------------------------------------
 208
 209 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.
 210
 211 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.
 212
 213 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.
 214
 215 Currently the recommended mode is single-layer RA mode.
 216
 217
 218 Default Values:
 219
 220 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 221 |  Name               | Value                                                                                                                           |
 222 +=====================+=================================================================================================================================+
 223 | Request URL         | http://aaf-ejbca:8080/ejbca/publicweb/cmp/cmpRA                                                                                 |
 224 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 225 | Response Type       | PKI Response                                                                                                                    |
 226 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 227 | caMode              | RA                                                                                                                              |
 228 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 229 | alias               | cmpRA                                                                                                                           |
 230 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 231
 232
 233 If you wish to configure the EJBCA server, you can find Documentation for EJBCA here: https://doc.primekey.com/ejbca/
 234
 235 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
 236
 237 Init Container for K8s
 238 ----------------------
 239
 240 Example deployment:
 241
 242 .. code-block:: yaml
 243
 244     ...
 245   kind: Deployment
 246   metadata:
 247     ...
 248   spec:
 249   ...
 250     template:
 251     ...
 252       spec:
 253         containers:
 254           - image: sample.image
 255             name: sample.name
 256             ...
 257             volumeMounts
 258               - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
 259                 name: certs
 260             ...
 261         initContainers:
 262           - name: cert-service-client
 263             image: nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
 264             imagePullPolicy: Always
 265             env:
 266               - name: REQUEST_URL
 267                 value: http://aaf-cert-service:8080/v1/certificate/
 268               - name: REQUEST_TIMEOUT
 269                 value: "1000"
 270               - name: OUTPUT_PATH
 271                 value: /var/certs
 272               - name: CA_NAME
 273                 value: RA
 274               - name: COMMON_NAME
 275                 value: onap.org
 276               - name: ORGANIZATION
 277                 value: Linux-Foundation
 278               - name: ORGANIZATION_UNIT
 279                 value: ONAP
 280               - name: LOCATION
 281                 value: San-Francisco
 282               - name: STATE
 283                 value: California
 284               - name: COUNTRY
 285                 value: US
 286               - name: SANS
 287                 value: test.onap.org:onap.com
 288             volumeMounts:
 289               - mountPath: /var/certs
 290                 name: certs
 291           ...
 292         volumes:
 293           -emptyDir: {}
 294            name: certs
 295         ...
 296
 297