.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. Copyright 2020 NOKIA
+.. Copyright 2020-2021 NOKIA
Configuration
-=============
-
-Standalone docker container
----------------------------
-
-Certification Service Client image:
-
-.. code-block::
-
- nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
-
-
-1. Create file with environments as in example below.
-
-.. code-block::
-
- #Client envs
- REQUEST_URL=http://aaf-cert-service:8080/v1/certificate/
- REQUEST_TIMEOUT=1000
- OUTPUT_PATH=/var/certs
- CA_NAME=RA
- #Csr config envs
- COMMON_NAME=onap.org
- ORGANIZATION=Linux-Foundation
- ORGANIZATION_UNIT=ONAP
- LOCATION=San-Francisco
- STATE=California
- COUNTRY=US
- SANS=test.onap.org:onap.com
-
-
-2. Run docker container with environments file and docker network (API and client must be running in same network).
-
-.. code-block:: bash
-
- AAFCERT_CLIENT_IMAGE=nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
- DOCKER_ENV_FILE= <path to environment file>
- NETWORK_CERT_SERVICE= <docker network of cert service>
- DOCKER_VOLUME="<absolute path to local dir>:<output path>"
-
- docker run --env-file $DOCKER_ENV_FILE --network $NETWORK_CERT_SERVICE --volume $DOCKER_VOLUME $AAFCERT_CLIENT_IMAGE
+==============
Configuring Cert Service
"cmpv2Servers": [
{
"caName": "Client",
- "url": "http://aafcert-ejbca:8080/ejbca/publicweb/cmp/cmp",
+ "url": "http://oomcert-ejbca:8080/ejbca/publicweb/cmp/cmp",
"issuerDN": "CN=ManagementCA",
- "caMode": "CLIENT",
"authentication": {
"iak": "mypassword",
"rv": "mypassword"
},
{
"caName": "RA",
- "url": "http://aafcert-ejbca:8080/ejbca/publicweb/cmp/cmpRA",
+ "url": "http://oomcert-ejbca:8080/ejbca/publicweb/cmp/cmpRA",
"issuerDN": "CN=ManagementCA",
- "caMode": "RA",
"authentication": {
"iak": "mypassword",
"rv": "mypassword"
This contains list of CMP Servers, where each server has following properties:
- - *caName* - name of the external CA server
- - *url* - Url to CMPv2 server
+ - *caName* - name of the external CA server. It's used to match *CA_NAME* sent by CertService client in order to match proper configuration.
+ - *url* - URL to CMPv2 server
- *issuerDN* - Distinguished Name of the CA that will sign the certificate
- - *caMode* - Issuer mode
- *authentication*
- *iak* - Initial authentication key, used to authenticate request in CMPv2 server
- - *rv* - Reference values, used ti authenticate request in CMPv2 server
+ - *rv* - Reference value, used to authenticate request in CMPv2 server
+
+This configuration is read on the application start. It can also be reloaded in runtime, by calling HTTPS endpoint.
-This configuration is read on the application start. It can also be reloaded in runtime, by calling HTTP endpoint.
+Next sections explain how to configure Cert Service in local (docker-compose) and OOM Deployments.
-Configuring in local(docker-compose) deployment:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuring in local (docker-compose) deployment:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Static:
-"""""""
+Before application start:
+"""""""""""""""""""""""""
1. Edit *cmpServers.json* file in certservice/compose-resources
2. Start containers::
make start-backend
-Dynamic:
-""""""""
+When application is running:
+""""""""""""""""""""""""""""
1. Find CertService docker container name.
2. Enter container::
docker exec -it <certservice-container-name> bash
+ e.g.
+ docker exec -it oomcert-service bash
+
3. Edit *cmpServers.json* file::
- vim /etc/onap/aaf/certservice/cmpServers.json
+ vim /etc/onap/oom/certservice/cmpServers.json
-4. Save
+4. Save the file. Note that this file is mounted as volume, so change will be persistent.
5. Reload configuration::
- 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
+ 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
+
+6. Exit container::
+
+ exit
Configuring in OOM deployment:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before OOM installation:
+""""""""""""""""""""""""
-Static:
-"""""""
+Note! This must be executed before calling *make all* (from OOM Installation) or needs remaking OOM charts.
-*Note! This must be executed before calling make all or needs remaking aaf Charts*
-1. Edit *cmpServers.json* file
+1. Edit *cmpServers.json* file. If OOM *global.addTestingComponents* flag is set to:
- - if it's test deployment - edit *kubernetes/aaf/charts/aaf-cert-service/resources/test/cmpServers.json*
- - if it's normal deployment - edit *kubernetes/aaf/charts/aaf-cert-service/resources/default/cmpServers.json*
+ - *true* - edit *kubernetes/platform/components/oom-cert-service/resources/test/cmpServers.json*
+ - *false* - edit *kubernetes/platform/components/oom-cert-service/resources/default/cmpServers.json*
2. Build and start OOM deployment
-Dynamic:
-""""""""
+When CertService is deployed:
+"""""""""""""""""""""""""""""
+
+1. Create file with configuration
+
+2. Encode your configuration to base64::
+
+ cat <configuration_file> | base64
-1. Encode your configuration to base64 (You can use for example online encoders or command line tool *base64*)
-2. Edit secret::
+3. Edit secret::
- kubectl edit secret <cmp-servers-secret-name> # aaf-cert-service-secret by default
+ kubectl -n onap edit secret <cmp-servers-secret-name>
-3. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
+ e.g.
+ kubectl -n onap edit secret oom-cert-service-secret
+
+4. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
.. code-block:: yaml
kind: Secret
metadata:
creationTimestamp: "2020-04-21T16:30:29Z"
- name: aaf-cert-service-secret
+ name: oom-cert-service-secret
namespace: default
resourceVersion: "33892990"
- selfLink: /api/v1/namespaces/default/secrets/aaf-cert-service-secret
+ selfLink: /api/v1/namespaces/default/secrets/oom-cert-service-secret
uid: 6a037526-83ed-11ea-b731-fa163e2144f6
type: Opaque
-4. Save and exit
-5. New configuration will be automatically mounted to CertService pod, but reload is needed.
-6. Enter CertService pod::
+5. Save and exit
+6. New configuration will be automatically mounted to CertService pod, but application configuration reload is needed.
+7. To reload configuration enter CertService pod::
+
+ kubectl -n onap exec -it <cert-service-pod-name> bash
- kubectl exec -it <cert-service-pod-name> bash
+ e.g.
+ kubectl -n onap exec -it $(kubectl -n onap get pods | grep cert-service | awk '{print $1}') bash
-7. Reload configuration::
+8. Reload configuration::
curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
+9. Exit container::
+
+ exit
-Generating certificates for CertService and CertService Client
---------------------------------------------------------------
-CertService and CertService client use mutual TLS for communication. Certificates are generated using Makefile.
-Local:
-^^^^^^
+Generating certificates for CertService and CMPv2 certificate provider
+----------------------------------------------------------------------
+CertService and CMPv2 certificate provider use mutual TLS for communication. Certificates are generated during CertService installation.
+
+Docker mode:
+^^^^^^^^^^^^
Certificates are mounted to containers by docker volumes:
- CertService volumes are defined in certservice/docker-compose.yaml
- - CertClient volumes are defined in certservice/Makefile
All certificates are stored in *certservice/certs* directory. To recreate certificates go to *certservice/certs* directory and execute::
This will clear existing certs and generate new ones.
-OOM:
-^^^^
+ONAP OOM installation:
+^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+Both secrets definitions are stored in *kubernetes/platform/components/oom-cert-service/values.yaml* as *secrets:* key.
+
+During platform component deployment, certificates in secrets are generated automatically using *Certificate* resources from cert-manager.
+Their definitions are stored in *kubernetes/platform/components/oom-cert-service/values.yaml* as *certificates:* key.
+
+
+Using external certificates for CertService and CMPv2 certificate provider
+--------------------------------------------------------------------------
+
+This section describes how to use custom, external certificates for CertService and CMPv2 certificate provider communication in OOM installation.
+
+1. Remove *certificates:* section from *kubernetes/platform/components/oom-cert-service/values.yaml*
+
+2. Prepare secret for CertService. It must be provided before OOM installation. It must contain four files:
+
+ - *keystore.jks* - keystore in JKS format. Signed by some Root CA
+ - *keystore.p12* - same keystore in PKCS#12 format
+ - *truststore.jks* - truststore in JKS format, containing certificates of the Root CA that signed CertService Client certificate
+ - *ca.crt* - certificate of the RootCA that signed Client certificate in CRT format
+
+3. Name the secret properly - the name should match *tls.server.secret.name* value from *kubernetes/platform/components/oom-cert-service/values.yaml* file
+
+4. Prepare secret for CMPv2 certificate provider. It must be provided before OOM installation. It must contain three files:
+
+ - *tls.crt* - certificate in CRT format. Signed by some Root CA
+ - *tls.key* - private key in KEY format
+ - *ca.crt* - certificate of the RootCA that signed CertService certificate in CRT format
+
+5. Name the secret properly - the name should match *global.oom.certService.client.secret.name* value from *kubernetes/onap/values.yaml* file
+
+6. Provide keystore and truststore passwords (the same for both) for CertService. It can be done in two ways:
+
+ - by inlining them into *kubernetes/platform/components/oom-cert-service/values.yaml*:
+
+ - override *credentials.tls.certificatesPassword* value with keystore and truststore password
-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*.
-Secrets take certificates from *kubernetes/aaf/charts/aaf-cert-service/resources* directory. Certificates are generated automatically during building(using Make) OOM repository.
+ - or by providing them as secrets:
-*kubernetes/aaf/charts/aaf-cert-service/Makefile* is similar to the one stored in certservice repository. It actually generates certificates.
-This Makefile is executed by *kubernetes/aaf/Makefile*, which is automatically executed during OOM build.
+ - uncomment *credentials.tls.certificatesPasswordExternalSecret* value and provide keystore and truststore password
Configuring EJBCA server for testing
------------------------------------
-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.
+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.
-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.
+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.
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.
+---------------------+---------------------------------------------------------------------------------------------------------------------------------+
| Name | Value |
+=====================+=================================================================================================================================+
-| Request URL | http://aaf-ejbca:8080/ejbca/publicweb/cmp/cmpRA |
+| Request URL | http://ejbca:8080/ejbca/publicweb/cmp/cmpRA |
+---------------------+---------------------------------------------------------------------------------------------------------------------------------+
| Response Type | PKI Response |
+---------------------+---------------------------------------------------------------------------------------------------------------------------------+
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
-Init Container for K8s
-----------------------
-
-Example deployment:
-
-.. code-block:: yaml
-
- ...
- kind: Deployment
- metadata:
- ...
- spec:
- ...
- template:
- ...
- spec:
- containers:
- - image: sample.image
- name: sample.name
- ...
- volumeMounts
- - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
- name: certs
- ...
- initContainers:
- - name: cert-service-client
- image: nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
- imagePullPolicy: Always
- env:
- - name: REQUEST_URL
- value: http://aaf-cert-service:8080/v1/certificate/
- - name: REQUEST_TIMEOUT
- value: "1000"
- - name: OUTPUT_PATH
- value: /var/certs
- - name: CA_NAME
- value: RA
- - name: COMMON_NAME
- value: onap.org
- - name: ORGANIZATION
- value: Linux-Foundation
- - name: ORGANIZATION_UNIT
- value: ONAP
- - name: LOCATION
- value: San-Francisco
- - name: STATE
- value: California
- - name: COUNTRY
- value: US
- - name: SANS
- value: test.onap.org:onap.com
- volumeMounts:
- - mountPath: /var/certs
- name: certs
- ...
- volumes:
- -emptyDir: {}
- name: certs
- ...
-
-
\ No newline at end of file
Code Review / oom / platform / cert-service.git / blobdiff