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 Configuring EJBCA server for testing
 179 ------------------------------------
 180
 181 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.
 182
 183 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.
 184
 185 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.
 186
 187 Currently the recommended mode is single-layer RA mode.
 188
 189
 190 Default Values:
 191
 192 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 193 |  Name               | Value                                                                                                                           |
 194 +=====================+=================================================================================================================================+
 195 | Request URL         | http://aaf-ejbca:8080/ejbca/publicweb/cmp/cmpRA                                                                                 |
 196 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 197 | Response Type       | PKI Response                                                                                                                    |
 198 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 199 | caMode              | RA                                                                                                                              |
 200 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 201 | alias               | cmpRA                                                                                                                           |
 202 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
 203
 204
 205 If you wish to configure the EJBCA server, you can find Documentation for EJBCA here: https://doc.primekey.com/ejbca/
 206
 207 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
 208
 209 Init Container for K8s
 210 ----------------------
 211
 212 Example deployment:
 213
 214 .. code-block:: yaml
 215
 216     ...
 217   kind: Deployment
 218   metadata:
 219     ...
 220   spec:
 221   ...
 222     template:
 223     ...
 224       spec:
 225         containers:
 226           - image: sample.image
 227             name: sample.name
 228             ...
 229             volumeMounts
 230               - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
 231                 name: certs
 232             ...
 233         initContainers:
 234           - name: cert-service-client
 235             image: nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
 236             imagePullPolicy: Always
 237             env:
 238               - name: REQUEST_URL
 239                 value: http://aaf-cert-service:8080/v1/certificate/
 240               - name: REQUEST_TIMEOUT
 241                 value: "1000"
 242               - name: OUTPUT_PATH
 243                 value: /var/certs
 244               - name: CA_NAME
 245                 value: RA
 246               - name: COMMON_NAME
 247                 value: onap.org
 248               - name: ORGANIZATION
 249                 value: Linux-Foundation
 250               - name: ORGANIZATION_UNIT
 251                 value: ONAP
 252               - name: LOCATION
 253                 value: San-Francisco
 254               - name: STATE
 255                 value: California
 256               - name: COUNTRY
 257                 value: US
 258               - name: SANS
 259                 value: test.onap.org:onap.com
 260             volumeMounts:
 261               - mountPath: /var/certs
 262                 name: certs
 263           ...
 264         volumes:
 265           -emptyDir: {}
 266            name: certs
 267         ...
 268
 269