1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. Copyright 2020 NOKIA
How to use functionality
=========================
Common information to docker and Kubernetes modes described below
Basic information
-----------------
CertService client needs the following configuration parameters to work properly:
1. Parameters for generating certification artifacts and connecting to CertService API to obtain certificate and trust anchors
- REQUEST_URL *(default: https://oom-cert-service:8443/v1/certificate/)* - URL to CertService API
- REQUEST_TIMEOUT *(default: 30000[ms])* - Timeout in milliseconds for REST API calls
- OUTPUT_PATH *(required)* - Path where client will output generated certificate and trust anchor
- CA_NAME *(required)* - Name of CA which will enroll certificate. Must be same as configured on server side. Used in REST API calls
- OUTPUT_TYPE *(default: P12)* - Type of certificate which will be generated. Supported types:
- JKS - Java KeyStore (JKS)
- P12 - Public Key Cryptography Standard #12 (PKCS#12)
- PEM - Privacy-Enhanced Mail (PEM)
2. Parameters to generate Certificate Signing Request (CSR):
- COMMON_NAME *(required)* - Common name for which certificate from CMPv2 server should be issued
- ORGANIZATION *(required)* - Organization for which certificate from CMPv2 server should be issued
- ORGANIZATION_UNIT *(optional)* - Organization unit for which certificate from CMPv2 server should be issued
- LOCATION *(optional)* - Location for which certificate from CMPv2 server should be issued
- STATE *(required)* - State for which certificate from CMPv2 server should be issued
- COUNTRY *(required)* - Country for which certificate from CMPv2 server should be issued
- 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. The following SANs types are supported: DNS names, IPs, URIs, emails.
3. Parameters to establish secure communication to CertService:
- KEYSTORE_PATH *(required)*
- KEYSTORE_PASSWORD *(required)*
- TRUSTSTORE_PATH *(required)*
- TRUSTSTORE_PASSWORD *(required)*
CertService client image can be found on Nexus repository :
.. code-block:: bash
nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:$VERSION
As standalone docker container
------------------------------
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>`__
To run CertService client as standalone docker container execute following steps:
1. Create file '*$PWD/client.env*' with environment variables as in example below:
.. code-block:: bash
#Client envs
REQUEST_URL=<URL to CertService API>
REQUEST_TIMEOUT=10000
OUTPUT_PATH=/var/certs
CA_NAME=RA
OUTPUT_TYPE=P12
#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,onap@onap.org,127.0.0.1,onap://cluster.local/
#TLS config envs
KEYSTORE_PATH=/etc/onap/oom/certservice/certs/certServiceClient-keystore.jks
KEYSTORE_PASSWORD=<password to certServiceClient-keystore.jks>
TRUSTSTORE_PATH=/etc/onap/oom/certservice/certs/certServiceClient-truststore.jks
TRUSTSTORE_PASSWORD=<password to certServiceClient-truststore.jks>
2. Run docker container as in following example (API and client must be running in same network):
.. code-block:: bash
docker run \
--rm \
--name oomcert-client \
--env-file <$PWD/client.env (same as in step1)> \
--network <docker network of cert service> \
--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)> \
--volume <local path to keystore in JKS format>:<KEYSTORE_PATH> \
--volume <local path to truststore in JKS format>:<TRUSTSTORE_PATH> \
nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:$VERSION
After successful creation of certifications, container exits with exit code 0, expected log looks like:
.. code-block:: bash
INFO 1 [ main] o.o.o.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
INFO 1 [ main] o.o.o.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: [{SAN value: example.org, type: dNSName}, {SAN value: test.onap.org, type: dNSName}, {SAN value: onap@onap.org, type: rfc822Name}, {SAN value: 127.0.0.1, type: iPAddress}, {SAN value: onap://cluster.local/, type: uniformResourceIdentifier}]
INFO 1 [ main] o.o.o.c.c.c.KeyPairFactory : KeyPair generation started with algorithm: RSA and key size: 2048
INFO 1 [ main] o.o.o.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: [{SAN value: example.org, type: dNSName}, {SAN value: test.onap.org, type: dNSName}, {SAN value: onap@onap.org, type: rfc822Name}, {SAN value: 127.0.0.1, type: iPAddress}, {SAN value: onap://cluster.local/, type: uniformResourceIdentifier}]
INFO 1 [ main] o.o.o.c.c.c.CsrFactory : Creation of CSR has been completed successfully
INFO 1 [ main] o.o.o.c.c.c.CsrFactory : Conversion of CSR to PEM has been started
INFO 1 [ main] o.o.o.c.c.c.PrivateKeyToPemEncoder : Attempt to encode private key to PEM
INFO 1 [ main] o.o.o.c.c.h.HttpClient : Attempt to send request to API, on url: https://oom-cert-service:8443/v1/certificate/RA
INFO 1 [ main] o.o.o.c.c.h.HttpClient : Received response from API
DEBUG 1 [ main] o.o.o.c.c.c.c.ConvertedArtifactsCreator : Attempt to create keystore files and saving data. File names: keystore.p12, keystore.pass
INFO 1 [ main] o.o.o.c.c.c.c.PemConverter : Conversion of PEM certificates to PKCS12 keystore
DEBUG 1 [ main] o.o.o.c.c.c.w.CertFileWriter : Attempt to save file keystore.p12 in path /var/certs
DEBUG 1 [ main] o.o.o.c.c.c.w.CertFileWriter : Attempt to save file keystore.pass in path /var/certs
DEBUG 1 [ main] o.o.o.c.c.c.c.ConvertedArtifactsCreator : Attempt to create truststore files and saving data. File names: truststore.p12, truststore.pass
INFO 1 [ main] o.o.o.c.c.c.c.PemConverter : Conversion of PEM certificates to PKCS12 truststore
DEBUG 1 [ main] o.o.o.c.c.c.w.CertFileWriter : Attempt to save file truststore.p12 in path /var/certs
DEBUG 1 [ main] o.o.o.c.c.c.w.CertFileWriter : Attempt to save file truststore.pass in path /var/certs
INFO 1 [ main] o.o.o.c.c.AppExitHandler : Application exits with following exit code: 0 and message: Success
If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
As init container for Kubernetes
--------------------------------
In order to run CertService client as init container for ONAP component you need to:
- define an init container and use CerService Client image
- provide client configuration through ENV variables in the init container
- define two volumes:
- first for generated certificates - it will be mounted in the init container and in the component container
- second with secret containing keys and certificates for secure communication between CertService Client and CertService - it will be mounted only in the init container
- mount both volumes to the init container
- mount first volume to the component container
You can use the following deployment example as a reference:
.. 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.oom.platform.cert-service.oom-certservice-client:latest
imagePullPolicy: Always
env:
- name: REQUEST_URL
value: https://oom-cert-service:8443/v1/certificate/
- name: REQUEST_TIMEOUT
value: "1000"
- name: OUTPUT_PATH
value: /var/certs
- name: CA_NAME
value: RA
- name: OUTPUT_TYPE
value: P12
- 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,onap@onap.org,127.0.0.1,onap://cluster.local/
- name: KEYSTORE_PATH
value: /etc/onap/oom/certservice/certs/certServiceClient-keystore.jks
- name: KEYSTORE_PASSWORD
value: secret
- name: TRUSTSTORE_PATH
value: /etc/onap/oom/certservice/certs/truststore.jks
- name: TRUSTSTORE_PASSWORD
value: secret
volumeMounts:
- mountPath: /var/certs
name: certs
- mountPath: /etc/onap/oom/certservice/certs/
name: tls-volume
...
volumes:
- name: certs
emptyDir: {}
- name tls-volume
secret:
secretName: oom-cert-service-client-tls-secret # Value of global.oom.certService.client.secret.name
...
|
