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
5 How to use functionality
6 =========================
7 Common information to docker and Kubernetes modes described below
11 CertService client needs the following configuration parameters to work properly:
13 1. Parameters for generating certification artifacts and connecting to CertService API to obtain certificate and trust anchors
15 - REQUEST_URL *(default: https://oom-cert-service:8443/v1/certificate/)* - URL to CertService API
16 - REQUEST_TIMEOUT *(default: 30000[ms])* - Timeout in milliseconds for REST API calls
17 - OUTPUT_PATH *(required)* - Path where client will output generated certificate and trust anchor
18 - CA_NAME *(required)* - Name of CA which will enroll certificate. Must be same as configured on server side. Used in REST API calls
19 - OUTPUT_TYPE *(default: P12)* - Type of certificate which will be generated. Supported types:
21 - JKS - Java KeyStore (JKS)
22 - P12 - Public Key Cryptography Standard #12 (PKCS#12)
23 - PEM - Privacy-Enhanced Mail (PEM)
26 2. Parameters to generate Certificate Signing Request (CSR):
28 - COMMON_NAME *(required)* - Common name for which certificate from CMPv2 server should be issued
29 - ORGANIZATION *(required)* - Organization for which certificate from CMPv2 server should be issued
30 - ORGANIZATION_UNIT *(optional)* - Organization unit for which certificate from CMPv2 server should be issued
31 - LOCATION *(optional)* - Location for which certificate from CMPv2 server should be issued
32 - STATE *(required)* - State for which certificate from CMPv2 server should be issued
33 - COUNTRY *(required)* - Country for which certificate from CMPv2 server should be issued
34 - SANS *(optional)(SANS's should be separated by a comma e.g. test.onap.org,onap.com)* - Subject Alternative Names (SANs) for which certificate from CMPv2 server should be issued.
36 3. Parameters to establish secure communication to CertService:
38 - KEYSTORE_PATH *(required)*
39 - KEYSTORE_PASSWORD *(required)*
40 - TRUSTSTORE_PATH *(required)*
41 - TRUSTSTORE_PASSWORD *(required)*
43 CertService client image can be found on Nexus repository :
47 nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:$VERSION
50 As standalone docker container
51 ------------------------------
52 You need certificate and trust anchors to connect to CertService API via HTTPS. Information how to generate truststore and keystore files you can find in project repository README `Gerrit GitWeb <https://gerrit.onap.org/r/gitweb?p=oom%2Fplatform%2Fcert-service.git;a=summary>`__
54 To run CertService client as standalone docker container execute following steps:
56 1. Create file '*$PWD/client.env*' with environment variables as in example below:
61 REQUEST_URL=<URL to CertService API>
63 OUTPUT_PATH=/var/certs
69 ORGANIZATION=Linux-Foundation
70 ORGANIZATION_UNIT=ONAP
71 LOCATION=San-Francisco
74 SANS=test.onap.org,onap.com
77 KEYSTORE_PATH=/etc/onap/oom/certservice/certs/certServiceClient-keystore.jks
78 KEYSTORE_PASSWORD=<password to certServiceClient-keystore.jks>
79 TRUSTSTORE_PATH=/etc/onap/oom/certservice/certs/certServiceClient-truststore.jks
80 TRUSTSTORE_PASSWORD=<password to certServiceClient-truststore.jks>
82 2. Run docker container as in following example (API and client must be running in same network):
88 --name oomcert-client \
89 --env-file <$PWD/client.env (same as in step1)> \
90 --network <docker network of cert service> \
91 --mount type=bind,src=<path to local host directory where certificate and trust anchor will be created>,dst=<OUTPUT_PATH (same as in step 1)> \
92 --volume <local path to keystore in JKS format>:<KEYSTORE_PATH> \
93 --volume <local path to truststore in JKS format>:<TRUSTSTORE_PATH> \
94 nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:$VERSION
98 After successful creation of certifications, container exits with exit code 0, expected log looks like:
102 INFO 1 [ main] o.o.a.c.c.c.f.ClientConfigurationFactory : Successful validation of Client configuration. Configuration data: REQUEST_URL: https://oom-cert-service:8443/v1/certificate/, REQUEST_TIMEOUT: 10000, OUTPUT_PATH: /var/certs, CA_NAME: RA, OUTPUT_TYPE: P12
103 INFO 1 [ main] o.o.a.c.c.c.f.CsrConfigurationFactory : Successful validation of CSR configuration. Configuration data: COMMON_NAME: onap.org, COUNTRY: US, STATE: California, ORGANIZATION: Linux-Foundation, ORGANIZATION_UNIT: ONAP, LOCATION: San-Francisco, SANS: test.onap.org:onap.org
104 INFO 1 [ main] o.o.a.c.c.c.KeyPairFactory : KeyPair generation started with algorithm: RSA and key size: 2048
105 INFO 1 [ main] o.o.a.c.c.c.CsrFactory : Creation of CSR has been started with following parameters: COMMON_NAME: onap.org, COUNTRY: US, STATE: California, ORGANIZATION: Linux-Foundation, ORGANIZATION_UNIT: ONAP, LOCATION: San-Francisco, SANS: test.onap.org:onap.org
106 INFO 1 [ main] o.o.a.c.c.c.CsrFactory : Creation of CSR has been completed successfully
107 INFO 1 [ main] o.o.a.c.c.c.CsrFactory : Conversion of CSR to PEM has been started
108 INFO 1 [ main] o.o.a.c.c.c.PrivateKeyToPemEncoder : Attempt to encode private key to PEM
109 INFO 1 [ main] o.o.a.c.c.h.HttpClient : Attempt to send request to API, on url: https://oom-cert-service:8443/v1/certificate/RA
110 INFO 1 [ main] o.o.a.c.c.h.HttpClient : Received response from API
111 DEBUG 1 [ main] o.o.a.c.c.c.c.ConvertedArtifactsCreator : Attempt to create keystore files and saving data. File names: keystore.p12, keystore.pass
112 INFO 1 [ main] o.o.a.c.c.c.c.PemConverter : Conversion of PEM certificates to PKCS12 keystore
113 DEBUG 1 [ main] o.o.a.c.c.c.w.CertFileWriter : Attempt to save file keystore.p12 in path /var/certs
114 DEBUG 1 [ main] o.o.a.c.c.c.w.CertFileWriter : Attempt to save file keystore.pass in path /var/certs
115 DEBUG 1 [ main] o.o.a.c.c.c.c.ConvertedArtifactsCreator : Attempt to create truststore files and saving data. File names: truststore.p12, truststore.pass
116 INFO 1 [ main] o.o.a.c.c.c.c.PemConverter : Conversion of PEM certificates to PKCS12 truststore
117 DEBUG 1 [ main] o.o.a.c.c.c.w.CertFileWriter : Attempt to save file truststore.p12 in path /var/certs
118 DEBUG 1 [ main] o.o.a.c.c.c.w.CertFileWriter : Attempt to save file truststore.pass in path /var/certs
119 INFO 1 [ main] o.o.a.c.c.AppExitHandler : Application exits with following exit code: 0 and message: Success
124 If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
126 As init container for Kubernetes
127 --------------------------------
129 In order to run CertService client as init container for ONAP component you need to:
131 - define an init container and use CerService Client image
132 - provide client configuration through ENV variables in the init container
133 - define two volumes:
135 - first for generated certificates - it will be mounted in the init container and in the component container
136 - second with secret containing keys and certificates for secure communication between CertService Client and CertService - it will be mounted only in the init container
137 - mount both volumes to the init container
138 - mount first volume to the component container
140 You can use the following deployment example as a reference:
154 - image: sample.image
158 - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
162 - name: cert-service-client
163 image: nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:latest
164 imagePullPolicy: Always
167 value: https://oom-cert-service:8443/v1/certificate/
168 - name: REQUEST_TIMEOUT
179 value: Linux-Foundation
180 - name: ORGANIZATION_UNIT
189 value: test.onap.org:onap.com
190 - name: KEYSTORE_PATH
191 value: /etc/onap/oom/certservice/certs/certServiceClient-keystore.jks
192 - name: KEYSTORE_PASSWORD
194 - name: TRUSTSTORE_PATH
195 value: /etc/onap/oom/certservice/certs/truststore.jks
196 - name: TRUSTSTORE_PASSWORD
199 - mountPath: /var/certs
201 - mountPath: /etc/onap/oom/certservice/certs/
209 secretName: oom-cert-service-client-tls-secret # Value of global.oom.certService.client.secret.name