Merge "[OOM-CERT-SERVICE] Deprecate certServiceClient - update docs"
[oom/platform/cert-service.git] / 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-2021 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://oomcert-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://oomcert-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 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*
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     e.g.
80     docker exec -it oomcert-service bash
81
82 3. Edit *cmpServers.json* file::
83
84     vim /etc/onap/oom/certservice/cmpServers.json
85
86 4. Save the file. Note that this file is mounted as volume, so change will be persistent.
87 5. Reload configuration::
88
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
90
91 6. Exit container::
92
93     exit
94
95
96 Configuring in OOM deployment:
97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98
99 Before OOM installation:
100 """"""""""""""""""""""""
101
102 Note! This must be executed before calling *make all* (from OOM Installation) or needs remaking OOM charts.
103
104
105 1. Edit *cmpServers.json* file. If OOM *global.addTestingComponents* flag is set to:
106
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
109
110 2. Build and start OOM deployment
111
112 When CertService is deployed:
113 """""""""""""""""""""""""""""
114
115 1. Create file with configuration
116
117 2. Encode your configuration to base64::
118
119     cat <configuration_file> | base64
120
121 3. Edit secret::
122
123     kubectl -n onap edit secret <cmp-servers-secret-name>
124
125     e.g.
126     kubectl -n onap edit secret oom-cert-service-secret
127
128 4. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
129
130   .. code-block:: yaml
131
132         apiVersion: v1
133         data:
134           cmpServers.json: <HERE_PLACE_YOUR_BASE64_ENCODED_CONFIG>
135         kind: Secret
136         metadata:
137           creationTimestamp: "2020-04-21T16:30:29Z"
138           name: oom-cert-service-secret
139           namespace: default
140           resourceVersion: "33892990"
141           selfLink: /api/v1/namespaces/default/secrets/oom-cert-service-secret
142           uid: 6a037526-83ed-11ea-b731-fa163e2144f6
143         type: Opaque
144
145 5. Save and exit
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::
148
149     kubectl -n onap exec -it <cert-service-pod-name> bash
150
151     e.g.
152     kubectl -n onap exec -it $(kubectl -n onap get pods | grep cert-service | awk '{print $1}') bash
153
154 8. Reload configuration::
155
156     curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
157
158 9. Exit container::
159
160     exit
161
162
163 Generating certificates for CertService and CMPv2 certificate provider
164 ----------------------------------------------------------------------
165 CertService and CMPv2 certificate provider use mutual TLS for communication. Certificates are generated during CertService installation.
166
167 Docker mode:
168 ^^^^^^^^^^^^
169
170 Certificates are mounted to containers by docker volumes:
171
172     - CertService volumes are defined in certservice/docker-compose.yaml
173
174 All certificates are stored in *certservice/certs* directory. To recreate certificates go to *certservice/certs* directory and execute::
175
176     make clear all
177
178 This will clear existing certs and generate new ones.
179
180 ONAP OOM installation:
181 ^^^^^^^^^^^^^^^^^^^^^^
182
183 Certificates are stored in secrets, which are mounted to pods as volumes. For CMPv2 certificate provider, certificates are delivered in CMPv2Issuer as secrets name with corresponding keys.
184
185 Both secrets definitions are stored in *kubernetes/platform/components/oom-cert-service/values.yaml* as *secrets:* key.
186
187 During platform component deployment, certificates in secrets are generated automatically using *Certificate* resources from cert-manager.
188 Their definitions are stored in *kubernetes/platform/components/oom-cert-service/values.yaml* as *certificates:* key.
189
190
191 Using external certificates for CertService and CMPv2 certificate provider
192 --------------------------------------------------------------------------
193
194 This section describes how to use custom, external certificates for CertService and CMPv2 certificate provider communication in OOM installation.
195
196 1. Remove *certificates:* section from *kubernetes/platform/components/oom-cert-service/values.yaml*
197
198 2. Prepare secret for CertService. It must be provided before OOM installation. It must contain four files:
199
200     - *keystore.jks*  - keystore in JKS format. Signed by some Root CA
201     - *keystore.p12* - same keystore in PKCS#12 format
202     - *truststore.jks* - truststore in JKS format, containing certificates of the Root CA that signed CertService Client certificate
203     - *ca.crt* - certificate of the RootCA that signed Client certificate in CRT format
204
205 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
207 4. Prepare secret for CMPv2 certificate provider. It must be provided before OOM installation. It must contain three files:
208
209     - *tls.crt* - certificate in CRT format. Signed by some Root CA
210     - *tls.key* - private key in KEY format
211     - *ca.crt* - certificate of the RootCA that signed CertService certificate in CRT format
212
213 5. Name the secret properly - the name should match *global.oom.certService.client.secret.name* value from *kubernetes/onap/values.yaml* file
214
215 6. Provide keystore and truststore passwords (the same for both) for CertService. It can be done in two ways:
216
217     - by inlining them into *kubernetes/platform/components/oom-cert-service/values.yaml*:
218
219         - override *credentials.tls.certificatesPassword* value with keystore and truststore password
220
221     - or by providing them as secrets:
222
223         - uncomment *credentials.tls.certificatesPasswordExternalSecret* value and provide keystore and truststore password
224
225
226 Configuring EJBCA server for testing
227 ------------------------------------
228
229 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.
230
231 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.
232
233 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.
234
235 Currently the recommended mode is single-layer RA mode.
236
237
238 Default Values:
239
240 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
241 |  Name               | Value                                                                                                                           |
242 +=====================+=================================================================================================================================+
243 | Request URL         | http://ejbca:8080/ejbca/publicweb/cmp/cmpRA                                                                                 |
244 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
245 | Response Type       | PKI Response                                                                                                                    |
246 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
247 | caMode              | RA                                                                                                                              |
248 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
249 | alias               | cmpRA                                                                                                                           |
250 +---------------------+---------------------------------------------------------------------------------------------------------------------------------+
251
252
253 If you wish to configure the EJBCA server, you can find Documentation for EJBCA here: https://doc.primekey.com/ejbca/
254
255 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
256