aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPawel Baniewski <pawel.baniewski@nokia.com>2021-06-18 10:22:42 +0000
committerGerrit Code Review <gerrit@onap.org>2021-06-18 10:22:42 +0000
commit649be36042dd5d58022c28e628399e350dc43282 (patch)
treeed17526166f970f23c1e8092c6545048414330f1
parent6698688e354cab9858ef72fc67c1187b87afea43 (diff)
parent6258cddd13af599acfa56246034bd2712dddb6f7 (diff)
Merge "[OOM-CERT-SERVICE] Deprecate certServiceClient - update docs"
-rw-r--r--certService/pom.xml4
-rw-r--r--certService/version.properties4
-rw-r--r--certServiceClient/README.md42
-rw-r--r--certServiceK8sExternalProvider/pom.xml2
-rw-r--r--certServicePostProcessor/pom.xml4
-rw-r--r--docs/index.rst3
-rw-r--r--docs/sections/architecture.rst8
-rw-r--r--docs/sections/change-log.rst49
-rw-r--r--docs/sections/cmpv2-cert-provider.rst151
-rw-r--r--docs/sections/configuration.rst55
-rw-r--r--docs/sections/logging.rst64
-rw-r--r--docs/sections/resources/certService_cert_enrollment_flow.pngbin143610 -> 131031 bytes
-rw-r--r--docs/sections/resources/certservice_high_level.pngbin20276 -> 25697 bytes
-rw-r--r--docs/sections/usage.rst297
-rw-r--r--pom.xml2
15 files changed, 249 insertions, 436 deletions
diff --git a/certService/pom.xml b/certService/pom.xml
index 3c9efcaa..4ad5b4ac 100644
--- a/certService/pom.xml
+++ b/certService/pom.xml
@@ -18,10 +18,10 @@
<parent>
<groupId>org.onap.oom.platform.cert-service</groupId>
<artifactId>oom-certservice</artifactId>
- <version>2.3.3-SNAPSHOT</version>
+ <version>2.4.0-SNAPSHOT</version>
</parent>
<artifactId>oom-certservice-api</artifactId>
- <version>2.3.3-SNAPSHOT</version>
+ <version>2.4.0-SNAPSHOT</version>
<name>oom-certservice-api</name>
<description>OOM Certification Service Api</description>
<packaging>jar</packaging>
diff --git a/certService/version.properties b/certService/version.properties
index 29a89d0c..c0f75b6a 100644
--- a/certService/version.properties
+++ b/certService/version.properties
@@ -1,6 +1,6 @@
major=2
-minor=3
-patch=2
+minor=4
+patch=0
base_version=${major}.${minor}.${patch}
release_version=${base_version}
snapshot_version=${base_version}-SNAPSHOT
diff --git a/certServiceClient/README.md b/certServiceClient/README.md
index 98dcfb9b..15f63f4e 100644
--- a/certServiceClient/README.md
+++ b/certServiceClient/README.md
@@ -22,7 +22,7 @@ mvn clean install -P docker
### Nexus container image
```
-nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:latest
+nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:2.3.3
```
### Running local client application as standalone docker container
@@ -30,8 +30,45 @@ CertService API and client must be running in same network.
You need certificate and trust anchors (in JKS format) to connect to CertService API via HTTPS. Information how to generate truststore and keystore files you can find in CertService main README.
-Information how to run you can find in CertService main README and official documentation, see [Read The Docs](https://docs.onap.org/projects/onap-oom-platform-cert-service/en/latest/sections/usage.html)
+To run CertService client as standalone docker container execute following steps:
+1. Create file ‘$PWD/client.env’ with environment variables as in example below:
+```
+#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):
+```
+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:2.3.3
+```
+After successful creation of certifications, container exits with exit code 0.
### Logs locally
@@ -56,3 +93,4 @@ docker logs oom-certservice-client
8 Fail in Private Key to PEM Encoding
9 Wrong TLS configuration
10 File could not be created
+99 Application exited abnormally
diff --git a/certServiceK8sExternalProvider/pom.xml b/certServiceK8sExternalProvider/pom.xml
index 4e7f6898..a64b9a6b 100644
--- a/certServiceK8sExternalProvider/pom.xml
+++ b/certServiceK8sExternalProvider/pom.xml
@@ -5,7 +5,7 @@
<parent>
<artifactId>oom-certservice</artifactId>
<groupId>org.onap.oom.platform.cert-service</groupId>
- <version>2.3.3-SNAPSHOT</version>
+ <version>2.4.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
diff --git a/certServicePostProcessor/pom.xml b/certServicePostProcessor/pom.xml
index 6fa10de6..0584043d 100644
--- a/certServicePostProcessor/pom.xml
+++ b/certServicePostProcessor/pom.xml
@@ -5,12 +5,12 @@
<parent>
<artifactId>oom-certservice</artifactId>
<groupId>org.onap.oom.platform.cert-service</groupId>
- <version>2.3.3-SNAPSHOT</version>
+ <version>2.4.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>oom-certservice-post-processor</artifactId>
- <version>2.3.3-SNAPSHOT</version>
+ <version>2.4.0-SNAPSHOT</version>
<name>oom-certservice-post-processor</name>
<description>An application which conducts certificate post-processing like: merging truststores, copying keystores.</description>
<packaging>jar</packaging>
diff --git a/docs/index.rst b/docs/index.rst
index d14bbfbe..2b9e6887 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,6 +1,6 @@
.. 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
.. _master_index:
OOM Certification Service
@@ -12,7 +12,6 @@ OOM Certification Service
sections/introduction.rst
sections/architecture.rst
- sections/cmpv2-cert-provider.rst
sections/build.rst
sections/offeredapis.rst
sections/usage.rst
diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
index 9166aa39..9cd86d55 100644
--- a/docs/sections/architecture.rst
+++ b/docs/sections/architecture.rst
@@ -10,15 +10,15 @@ Interaction between components
------------------------------
.. image:: resources/certservice_high_level.png
- :width: 855px
- :height: 223px
+ :width: 978px
+ :height: 202px
:alt: Interaction between components
The micro-service called CertService is designed for requesting certificates signed by external Certificate Authority (CA) using CMP over HTTP protocol. It uses CMPv2 client to send and receive CMPv2 messages.
-CertService's client is also provided so other ONAP components (aka end components) can easily get certificate from CertService. End component is an ONAP component (e.g. DCAE collector or controller) which requires certificate from CMPv2 server to protect external traffic and uses CertService's client to get it.
+CMPv2 external provider is also provided so other ONAP components (aka end components) can easily get certificate from CertService. End component is an ONAP component (e.g. DCAE collector or controller) which requires certificate from CMPv2 server to protect external traffic and uses Certificate CR to get it.
-CertService's client communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.
+CMPv2 external provider communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.
To proof that CertService works Open Source CMPv2 server (EJBCA) is deployed and used in E2E tests.
diff --git a/docs/sections/change-log.rst b/docs/sections/change-log.rst
index 71c5e118..41b23fad 100644
--- a/docs/sections/change-log.rst
+++ b/docs/sections/change-log.rst
@@ -1,11 +1,58 @@
.. 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
Change Log
==============
+--------
+Istanbul
+--------
+
+==============
+
+Version: 2.4.0
+--------------
+
+:Release Date:
+
+**New Features**
+
+ N/A
+
+**Bug Fixes**
+
+ N/A
+
+**Known Issues**
+
+ N/A
+
+**Security Notes**
+
+ N/A
+
+*Fixed Security Issues*
+
+ N/A
+
+*Known Security Issues*
+
+ N/A
+
+*Known Vulnerabilities in Used Modules*
+
+ N/A
+
+**Upgrade Notes**
+
+**Deprecation Notes**
+
+ CertService client is not supported since Istanbul release.
+
+**Other**
+
==============
--------
diff --git a/docs/sections/cmpv2-cert-provider.rst b/docs/sections/cmpv2-cert-provider.rst
deleted file mode 100644
index f4493cd1..00000000
--- a/docs/sections/cmpv2-cert-provider.rst
+++ /dev/null
@@ -1,151 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. Copyright 2020 NOKIA
-
-CMPv2 certificate provider
-==============================
-
-General information
-------------------------------
-
-CMPv2 certificate provider is a part of certificate distribution infrastructure in ONAP.
-The main functionality of the provider is to forward Certificate Signing Requests (CSRs) created by cert-mananger (https://cert-manager.io) to CertServiceAPI.
-
-Additional information can be found on a dedicated page: https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration.
-
-By default CMPv2 provider is **disabled**. To enable it set following global helm value:
-
-- CMPv2CertManagerIntegration = true
-
-CMPv2 Issuer
-------------------------------
-
-In order to be able to request a certificate via CMPv2 provider a *CMPv2Issuer* CRD (Customer Resource Definition) instance has to be created.
-
-It is important to note that the attribute *kind* has to be set to **CMPv2Issuer**, all other attributes can be set as needed.
-
-**NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment.**
-
-Here is a definition of a *CMPv2Issuer* provided with ONAP installation:
-
-.. code-block:: yaml
-
- apiVersion: certmanager.onap.org/v1
- kind: CMPv2Issuer
- metadata:
- name: cmpv2-issuer-onap
- namespace: onap
- spec:
- url: https://oom-cert-service:8443
- healthEndpoint: actuator/health
- certEndpoint: v1/certificate
- caName: RA
- certSecretRef:
- name: cmpv2-issuer-secret
- certRef: cmpv2Issuer-cert.pem
- keyRef: cmpv2Issuer-key.pem
- cacertRef: cacert.pem
-
-
-Certificate enrolling
-------------------------------
-
-In order to request a certificate a K8s *Certificate* CRD (Custom Resource Definition) has to be created.
-
-It is important that in the section issuerRef following attributes have those values:
-
-- group: certmanager.onap.org
-
-- kind: CMPv2Issuer
-
-After *Certificate* CRD has been placed cert manager will send a *CSR* (Certificate Sign Request) to CA (Certificate Authority) via CMPv2 provider.
-Signed certificate as well as trust anchor (CA root certificate) will be stored in the K8s *secret* specified in *Certificate* CRD (see secretName attribute).
-
-By default certificates will be stored in PEM format. It is possible to get certificates also in JKS and P12 format - see example below - more information can be found on official cert manager page.
-
-The following SANs types are supported: DNS names, IPs, URIs, emails.
-
-Here is an example of a *Certificate*:
-
-.. code-block:: yaml
-
- apiVersion: cert-manager.io/v1
- kind: Certificate
- metadata:
- name: certificate_name
- namespace: onap
- spec:
- # The secret name to store the signed certificate
- secretName: secret_name
- # Common Name
- commonName: certissuer.onap.org
- subject:
- organizations:
- - Linux-Foundation
- countries:
- - US
- localities:
- - San-Francisco
- provinces:
- - California
- organizationalUnits:
- - ONAP
- # SANs
- dnsNames:
- - localhost
- - certissuer.onap.org
- ipAddresses:
- - "127.0.0.1"
- uris:
- - onap://cluster.local/
- emailAddresses:
- - onap@onap.org
- # The reference to the CMPv2 issuer
- issuerRef:
- group: certmanager.onap.org
- kind: CMPv2Issuer
- name: cmpv2-issuer-onap
- # Section keystores is optional and defines in which format certificates will be stored
- # If this section is omitted than only PEM format will be present in the secret
- keystores:
- jks:
- create: true
- passwordSecretRef: # Password used to encrypt the keystore
- name: certservice-key
- key: key
- pkcs12:
- create: true
- passwordSecretRef: # Password used to encrypt the keystore
- name: certservice-key
- key: key
-
-
-Here is an example of generated *secret* containing certificates:
-
-.. code-block:: yaml
-
- Name: secret_name
- Namespace: onap
- Labels: <none>
- Annotations: cert-manager.io/alt-names: localhost,certissuer.onap.org
- cert-manager.io/certificate-name: certificate_name
- cert-manager.io/common-name: certissuer.onap.org
- cert-manager.io/ip-sans:
- cert-manager.io/issuer-group: certmanager.onap.org
- cert-manager.io/issuer-kind: CMPv2Issuer
- cert-manager.io/issuer-name: cmpv2-issuer-onap
- cert-manager.io/uri-sans:
-
- Type: kubernetes.io/tls
-
- Data
- ====
- tls.crt: 1675 bytes <-- Certificate (PEM)
- tls.key: 1679 bytes <-- Private Key (PEM)
- truststore.jks: 1265 bytes <-- Trusted anchors (JKS)
- ca.crt: 1692 bytes <-- Trusted anchors (PEM)
- keystore.jks: 3786 bytes <-- Certificate and Private Key (JKS)
- keystore.p12: 4047 bytes <-- Certificate and Private Key (P12)
-
-
-
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
index c165fa3b..6ba7c1b4 100644
--- a/docs/sections/configuration.rst
+++ b/docs/sections/configuration.rst
@@ -1,6 +1,6 @@
.. 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
==============
@@ -160,9 +160,9 @@ When CertService is deployed:
exit
-Generating certificates for CertService and CertService Client
---------------------------------------------------------------
-CertService and CertService client use mutual TLS for communication. Certificates are generated during CertService installation.
+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:
^^^^^^^^^^^^
@@ -170,7 +170,6 @@ Docker mode:
Certificates are mounted to containers by docker volumes:
- CertService volumes are defined in certservice/docker-compose.yaml
- - CertService Client volumes are defined in certservice/Makefile
All certificates are stored in *certservice/certs* directory. To recreate certificates go to *certservice/certs* directory and execute::
@@ -181,51 +180,47 @@ This will clear existing certs and generate new ones.
ONAP OOM installation:
^^^^^^^^^^^^^^^^^^^^^^
-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*.
-Secrets take certificates from *kubernetes/platform/components/oom-cert-service/resources* directory. Certificates are generated automatically during building (using Make) OOM repository.
+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.
-*kubernetes/platform/components/oom-cert-service/Makefile* is similar to the one stored in certservice repository. It actually generates certificates.
-This Makefile is executed by *kubernetes/platform/Makefile*, which is automatically executed during OOM build.
+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 CertService Client
-------------------------------------------------------------------
-This section describes how to use custom, external certificates for CertService and CertService Client communication in OOM installation.
-*kubernetes/platform/components/oom-cert-service/values.yaml*
-1. Set *tls.certificateExternalSecret* flag to true in *kubernetes/platform/components/oom-cert-service/values.yaml*
+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:
- - *certServiceServer-keystore.jks* - keystore in JKS format. Signed by some Root CA
- - *certServiceServer-keystore.p12* - same keystore in PKCS#12 format
+ - *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
- - *root.crt* - certificate of the RootCA that signed Client certificate in CRT format
+ - *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 CertService Client. It must be provided before OOM installation. It must contain two files:
+4. Prepare secret for CMPv2 certificate provider. It must be provided before OOM installation. It must contain three files:
- - *certServiceClient-keystore.jks* - keystore in JKS format. Signed by some Root CA
- - *truststore.jks* - truststore in JKS format, containing certificates of the RootCA that signed CertService certificate
+ - *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 for CertService. It can be done in two ways:
+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.keystorePassword* value with keystore password
- - override *credentials.tls.truststorePassword* value with truststore password
+ - override *credentials.tls.certificatesPassword* value with keystore and truststore password
- or by providing them as secrets:
- - uncomment *credentials.tls.keystorePasswordExternalSecret* value and provide keystore password
- - uncomment *credentials.tls.truststorePasswordExternalSecret* value and provide truststore password
-
-7. Override default keystore and truststore passwords for CertService Client in *kubernetes/onap/values.yaml* file:
-
- - override *global.oom.certServiceClient.envVariables.keystorePassword* value with keystore password
- - override *global.oom.certServiceClient.envVariables.truststorePassword* value with truststore password
+ - uncomment *credentials.tls.certificatesPasswordExternalSecret* value and provide keystore and truststore password
Configuring EJBCA server for testing
diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst
index 0e3511cf..c56ecea6 100644
--- a/docs/sections/logging.rst
+++ b/docs/sections/logging.rst
@@ -1,6 +1,6 @@
.. 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
Logging
@@ -62,65 +62,13 @@ Available log files:
User cannot change logging levels.
-.. _cert_logs:
-
-CertService client
-------------------
-To see CertService client console logs use :
-
-- Docker:
-
-.. code-block:: bash
-
- docker logs <cert-service-client-container-name>
-
- e.g.
- docker logs oomcert-client
-
-- Kubernetes:
- CertService client is used as init container in other components. In the following example:
- - *<some-component-pod-name>* refers to the component that uses CertService client as init container
- - *<cert-service-client-init-container-name>* refers to name of init container used by the mentioned component. It can be found by executing *'kubectl -n onap descrine pod <some-component-pod-name>'* and looking into 'Init Containers section'
+CMPv2 certificate provider
+--------------------------
+To see CMPv2 certificate provider console logs use :
.. code-block:: bash
- kubectl -n onap logs <some-component-pod-name> -c <cert-service-client-init-container-name>
+ kubectl -n onap logs <cmpv2-certificate-provider-pod-name> provider
e.g.
- kubectl -n onap logs <some-component-pod-name> -c cert-service-client
-
-
-
-| Container stops after execution, so all available logs are printed on console.
-| User cannot change logging levels.
-
-Client application exits with following exit codes:
-
-
-+-------+------------------------------------------------+
-| Code | Information |
-+=======+================================================+
-| 0 | Success |
-+-------+------------------------------------------------+
-| 1 | Invalid client configuration |
-+-------+------------------------------------------------+
-| 2 | Invalid CSR configuration |
-+-------+------------------------------------------------+
-| 3 | Fail in key pair generation |
-+-------+------------------------------------------------+
-| 4 | Fail in CSR generation |
-+-------+------------------------------------------------+
-| 5 | CertService HTTP unsuccessful response |
-+-------+------------------------------------------------+
-| 6 | Internal HTTP Client connection problem |
-+-------+------------------------------------------------+
-| 7 | Fail in PEM conversion |
-+-------+------------------------------------------------+
-| 8 | Fail in Private Key to PEM Encoding |
-+-------+------------------------------------------------+
-| 9 | Wrong TLS configuration |
-+-------+------------------------------------------------+
-| 10 | File could not be created |
-+-------+------------------------------------------------+
-| 99 | Application exited abnormally |
-+-------+------------------------------------------------+
+ kubectl -n onap logs $(kubectl -n onap get pods | grep cmpv2-cert-provider | awk '{print $1}') provider
diff --git a/docs/sections/resources/certService_cert_enrollment_flow.png b/docs/sections/resources/certService_cert_enrollment_flow.png
index 87d15adc..7b786947 100644
--- a/docs/sections/resources/certService_cert_enrollment_flow.png
+++ b/docs/sections/resources/certService_cert_enrollment_flow.png
Binary files differ
diff --git a/docs/sections/resources/certservice_high_level.png b/docs/sections/resources/certservice_high_level.png
index 7cab5e88..369e538e 100644
--- a/docs/sections/resources/certservice_high_level.png
+++ b/docs/sections/resources/certservice_high_level.png
Binary files differ
diff --git a/docs/sections/usage.rst b/docs/sections/usage.rst
index 0bbf348e..3031f364 100644
--- a/docs/sections/usage.rst
+++ b/docs/sections/usage.rst
@@ -1,211 +1,148 @@
.. 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
How to use functionality
=========================
-Common information to docker and Kubernetes modes described below
+Common information how to use CMPv2 certificate provider 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
+General information
------------------------------
-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
+CMPv2 certificate provider is a part of certificate distribution infrastructure in ONAP.
+The main functionality of the provider is to forward Certificate Signing Requests (CSRs) created by cert-mananger (https://cert-manager.io) to CertServiceAPI.
- #Client envs
- REQUEST_URL=<URL to CertService API>
- REQUEST_TIMEOUT=10000
- OUTPUT_PATH=/var/certs
- CA_NAME=RA
- OUTPUT_TYPE=P12
+Additional information can be found on a dedicated page: https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration.
- #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/
+By default CMPv2 provider is enabled.
- #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
+CMPv2 Issuer
+------------------------------
+In order to be able to request a certificate via CMPv2 provider a *CMPv2Issuer* CRD (Customer Resource Definition) instance has to be created.
+It is important to note that the attribute *kind* has to be set to **CMPv2Issuer**, all other attributes can be set as needed.
-After successful creation of certifications, container exits with exit code 0, expected log looks like:
+**NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment.**
-.. code-block:: bash
+Here is a definition of a *CMPv2Issuer* provided with ONAP installation:
- 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
+.. code-block:: yaml
+ apiVersion: certmanager.onap.org/v1
+ kind: CMPv2Issuer
+ metadata:
+ name: cmpv2-issuer-onap
+ namespace: onap
+ spec:
+ url: https://oom-cert-service:8443
+ healthEndpoint: actuator/health
+ certEndpoint: v1/certificate
+ caName: RA
+ certSecretRef:
+ name: cmpv2-issuer-secret
+ certRef: cmpv2Issuer-cert.pem
+ keyRef: cmpv2Issuer-key.pem
+ cacertRef: cacert.pem
+
+
+Certificate enrolling
+------------------------------
+In order to request a certificate a K8s *Certificate* CRD (Custom Resource Definition) has to be created.
+It is important that in the section issuerRef following attributes have those values:
-If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
+- group: certmanager.onap.org
-As init container for Kubernetes
---------------------------------
+- kind: CMPv2Issuer
-In order to run CertService client as init container for ONAP component you need to:
+After *Certificate* CRD has been placed cert manager will send a *CSR* (Certificate Sign Request) to CA (Certificate Authority) via CMPv2 provider.
+Signed certificate as well as trust anchor (CA root certificate) will be stored in the K8s *secret* specified in *Certificate* CRD (see secretName attribute).
- - define an init container and use CerService Client image
- - provide client configuration through ENV variables in the init container
- - define two volumes:
+By default certificates will be stored in PEM format. It is possible to get certificates also in JKS and P12 format - see example below - more information can be found on official cert manager page.
- - 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
+The following SANs types are supported: DNS names, IPs, URIs, emails.
-You can use the following deployment example as a reference:
+Here is an example of a *Certificate*:
.. code-block:: yaml
- ...
- kind: Deployment
+ apiVersion: cert-manager.io/v1
+ kind: Certificate
metadata:
- ...
+ name: certificate_name
+ namespace: onap
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
- ...
+ # The secret name to store the signed certificate
+ secretName: secret_name
+ # Common Name
+ commonName: certissuer.onap.org
+ subject:
+ organizations:
+ - Linux-Foundation
+ countries:
+ - US
+ localities:
+ - San-Francisco
+ provinces:
+ - California
+ organizationalUnits:
+ - ONAP
+ # SANs
+ dnsNames:
+ - localhost
+ - certissuer.onap.org
+ ipAddresses:
+ - "127.0.0.1"
+ uris:
+ - onap://cluster.local/
+ emailAddresses:
+ - onap@onap.org
+ # The reference to the CMPv2 issuer
+ issuerRef:
+ group: certmanager.onap.org
+ kind: CMPv2Issuer
+ name: cmpv2-issuer-onap
+ # Section keystores is optional and defines in which format certificates will be stored
+ # If this section is omitted than only PEM format will be present in the secret
+ keystores:
+ jks:
+ create: true
+ passwordSecretRef: # Password used to encrypt the keystore
+ name: certservice-key
+ key: key
+ pkcs12:
+ create: true
+ passwordSecretRef: # Password used to encrypt the keystore
+ name: certservice-key
+ key: key
+
+
+Here is an example of generated *secret* containing certificates:
+
+.. code-block:: yaml
+
+ Name: secret_name
+ Namespace: onap
+ Labels: <none>
+ Annotations: cert-manager.io/alt-names: localhost,certissuer.onap.org
+ cert-manager.io/certificate-name: certificate_name
+ cert-manager.io/common-name: certissuer.onap.org
+ cert-manager.io/ip-sans:
+ cert-manager.io/issuer-group: certmanager.onap.org
+ cert-manager.io/issuer-kind: CMPv2Issuer
+ cert-manager.io/issuer-name: cmpv2-issuer-onap
+ cert-manager.io/uri-sans:
+
+ Type: kubernetes.io/tls
+
+ Data
+ ====
+ tls.crt: 1675 bytes <-- Certificate (PEM)
+ tls.key: 1679 bytes <-- Private Key (PEM)
+ truststore.jks: 1265 bytes <-- Trusted anchors (JKS)
+ ca.crt: 1692 bytes <-- Trusted anchors (PEM)
+ keystore.jks: 3786 bytes <-- Certificate and Private Key (JKS)
+ keystore.p12: 4047 bytes <-- Certificate and Private Key (P12)
diff --git a/pom.xml b/pom.xml
index e3d1f5af..76a7c6a8 100644
--- a/pom.xml
+++ b/pom.xml
@@ -23,7 +23,7 @@
</parent>
<groupId>org.onap.oom.platform.cert-service</groupId>
<artifactId>oom-certservice</artifactId>
- <version>2.3.3-SNAPSHOT</version>
+ <version>2.4.0-SNAPSHOT</version>
<name>oom-certservice</name>
<description>OOM Certification Service</description>
<packaging>pom</packaging>