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
9 Configuring Cert Service
10 ------------------------
11 Cert Service keeps configuration of CMP Servers in file *cmpServers.json*.
13 Example cmpServers.json file:
21 "url": "http://oomcert-ejbca:8080/ejbca/publicweb/cmp/cmp",
22 "issuerDN": "CN=ManagementCA",
31 "url": "http://oomcert-ejbca:8080/ejbca/publicweb/cmp/cmpRA",
32 "issuerDN": "CN=ManagementCA",
42 This contains list of CMP Servers, where each server has following properties:
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*
50 - *iak* - Initial authentication key, used to authenticate request in CMPv2 server
51 - *rv* - Reference value, used to authenticate request in CMPv2 server
55 This configuration is read on the application start. It can also be reloaded in runtime, by calling HTTPS endpoint.
57 Next sections explain how to configure Cert Service in local (docker-compose) and OOM Deployments.
60 Configuring in local (docker-compose) deployment:
61 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
63 Before application start:
64 """""""""""""""""""""""""
66 1. Edit *cmpServers.json* file in certservice/compose-resources
71 When application is running:
72 """"""""""""""""""""""""""""
74 1. Find CertService docker container name.
77 docker exec -it <certservice-container-name> bash
80 docker exec -it oomcert-service bash
82 3. Edit *cmpServers.json* file::
84 vim /etc/onap/oom/certservice/cmpServers.json
86 4. Save the file. Note that this file is mounted as volume, so change will be persistent.
87 5. Reload configuration::
89 curl -I https://localhost:8443/reload --cacert /etc/onap/oom/certservice/certs/root.crt --cert-type p12 --cert /etc/onap/oom/certservice/certs/certServiceServer-keystore.p12 --pass $KEYSTORE_PASSWORD
96 Configuring in OOM deployment:
97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
99 Before OOM installation:
100 """"""""""""""""""""""""
102 Note! This must be executed before calling *make all* (from OOM Installation) or needs remaking OOM charts.
105 1. Edit *cmpServers.json* file. If OOM *global.addTestingComponents* flag is set to:
107 - *true* - edit *kubernetes/platform/components/oom-cert-service/resources/test/cmpServers.json*
108 - *false* - edit *kubernetes/platform/components/oom-cert-service/resources/default/cmpServers.json
110 2. Build and start OOM deployment
112 When CertService is deployed:
113 """""""""""""""""""""""""""""
115 1. Create file with configuration
117 2. Encode your configuration to base64::
119 cat <configuration_file> | base64
123 kubectl -n onap edit secret <cmp-servers-secret-name>
126 kubectl -n onap edit secret oom-cert-service-secret
128 4. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
134 cmpServers.json: <HERE_PLACE_YOUR_BASE64_ENCODED_CONFIG>
137 creationTimestamp: "2020-04-21T16:30:29Z"
138 name: oom-cert-service-secret
140 resourceVersion: "33892990"
141 selfLink: /api/v1/namespaces/default/secrets/oom-cert-service-secret
142 uid: 6a037526-83ed-11ea-b731-fa163e2144f6
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::
149 kubectl -n onap exec -it <cert-service-pod-name> bash
152 kubectl -n onap exec -it $(kubectl -n onap get pods | grep cert-service | awk '{print $1}') bash
154 8. Reload configuration::
156 curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
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.
170 Certificates are mounted to containers by docker volumes:
172 - CertService volumes are defined in certservice/docker-compose.yaml
173 - CertService Client volumes are defined in certservice/Makefile
175 All certificates are stored in *certservice/certs* directory. To recreate certificates go to *certservice/certs* directory and execute::
179 This will clear existing certs and generate new ones.
181 ONAP OOM installation:
182 ^^^^^^^^^^^^^^^^^^^^^^
184 Certificates are stored in secrets, which are mounted to pods as volumes. Both secrets are stored in *kubernetes/platform/components/oom-cert-service/templates/secret.yaml*.
185 Secrets take certificates from *kubernetes/platform/components/oom-cert-service/resources* directory. Certificates are generated automatically during building (using Make) OOM repository.
187 *kubernetes/platform/components/oom-cert-service/Makefile* is similar to the one stored in certservice repository. It actually generates certificates.
188 This Makefile is executed by *kubernetes/platform/Makefile*, which is automatically executed during OOM build.
191 Using external certificates for CertService and CertService Client
192 ------------------------------------------------------------------
194 This section describes how to use custom, external certificates for CertService and CertService Client communication in OOM installation.
195 *kubernetes/platform/components/oom-cert-service/values.yaml*
196 1. Set *tls.certificateExternalSecret* flag to true in *kubernetes/platform/components/oom-cert-service/values.yaml*
197 2. Prepare secret for CertService. It must be provided before OOM installation. It must contain four files:
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
204 3. Name the secret properly - the name should match *tls.server.secret.name* value from *kubernetes/platform/components/oom-cert-service/values.yaml* file
206 4. Prepare secret for CertService Client. It must be provided before OOM installation. It must contain two files:
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
211 5. Name the secret properly - the name should match *global.oom.certService.client.secret.name* value from *kubernetes/onap/values.yaml* file
213 6. Provide keystore and truststore passwords for CertService. It can be done in two ways:
215 - by inlining them into *kubernetes/platform/components/oom-cert-service/values.yaml*:
217 - override *credentials.tls.keystorePassword* value with keystore password
218 - override *credentials.tls.truststorePassword* value with truststore password
220 - or by providing them as secrets:
222 - uncomment *credentials.tls.keystorePasswordExternalSecret* value and provide keystore password
223 - uncomment *credentials.tls.truststorePasswordExternalSecret* value and provide truststore password
225 7. Override default keystore and truststore passwords for CertService Client in *kubernetes/onap/values.yaml* file:
227 - override *global.oom.certServiceClient.envVariables.keystorePassword* value with keystore password
228 - override *global.oom.certServiceClient.envVariables.truststorePassword* value with truststore password
231 Configuring EJBCA server for testing
232 ------------------------------------
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/platform/values.yaml.
236 cmpv2Enabled has to be true to enable oom-cert-service to be instantiated and used with an external Certificate Authority to get certificates for secure communication.
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.
240 Currently the recommended mode is single-layer RA mode.
245 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
247 +=====================+=================================================================================================================================+
248 | Request URL | http://ejbca:8080/ejbca/publicweb/cmp/cmpRA |
249 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
250 | Response Type | PKI Response |
251 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
253 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
255 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
258 If you wish to configure the EJBCA server, you can find Documentation for EJBCA here: https://doc.primekey.com/ejbca/
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