Merge "Fix How to use functionality page."
diff --git a/Makefile b/Makefile
index f94ad9a..778b94d 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-all: build start-backend run-client stop-client stop-backend
+all: build start-backend run-client stop-backend
start-with-client: start-backend run-client
.PHONY: build
diff --git a/certServiceClient/src/main/java/org/onap/aaf/certservice/client/configuration/exception/TlsConfigurationException.java b/certServiceClient/src/main/java/org/onap/aaf/certservice/client/configuration/exception/TlsConfigurationException.java
index a10185b..91f164e 100644
--- a/certServiceClient/src/main/java/org/onap/aaf/certservice/client/configuration/exception/TlsConfigurationException.java
+++ b/certServiceClient/src/main/java/org/onap/aaf/certservice/client/configuration/exception/TlsConfigurationException.java
@@ -24,7 +24,7 @@
import org.onap.aaf.certservice.client.api.ExitableException;
public class TlsConfigurationException extends ExitableException {
- private static final ExitStatus EXIT_STATUS = ExitStatus.CERT_SERVICE_API_CONNECTION_EXCEPTION;
+ private static final ExitStatus EXIT_STATUS = ExitStatus.TLS_CONFIGURATION_EXCEPTION;
public TlsConfigurationException(String message) {
super(message);
diff --git a/certServiceClient/src/test/java/org/onap/aaf/certservice/client/configuration/exception/TlsConfigurationExceptionTest.java b/certServiceClient/src/test/java/org/onap/aaf/certservice/client/configuration/exception/TlsConfigurationExceptionTest.java
new file mode 100644
index 0000000..e1144a6
--- /dev/null
+++ b/certServiceClient/src/test/java/org/onap/aaf/certservice/client/configuration/exception/TlsConfigurationExceptionTest.java
@@ -0,0 +1,47 @@
+/*
+ * ============LICENSE_START=======================================================
+ * aaf-certservice-client
+ * ================================================================================
+ * Copyright (C) 2020 Nokia. All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.aaf.certservice.client.configuration.exception;
+
+import org.junit.jupiter.api.Test;
+import org.onap.aaf.certservice.client.api.ExitStatus;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+public class TlsConfigurationExceptionTest {
+
+ @Test
+ public void containsProperExitStatus() {
+ // Given
+ ExitStatus exitStatus = null;
+
+ // When
+ try {
+ throw new TlsConfigurationException("Test message");
+ } catch (TlsConfigurationException e) {
+ exitStatus = e.applicationExitStatus();
+ }
+
+ // Then
+ assertThat(exitStatus).isNotNull();
+ assertThat(exitStatus).isEqualTo(ExitStatus.TLS_CONFIGURATION_EXCEPTION);
+ }
+}
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
index f6078a4..fc75d11 100644
--- a/docs/sections/configuration.rst
+++ b/docs/sections/configuration.rst
@@ -41,33 +41,35 @@
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 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
+ - *caMode* - Issuer mode. Allowed values are *CLIENT* and *RA*
- *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 HTTP endpoint.
+This configuration is read on the application start. It can also be reloaded in runtime, by calling HTTPS endpoint.
+
+Next sections explain how to configure Cert Service in local (docker-compose) and OOM Deployments.
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::
@@ -78,31 +80,39 @@
vim /etc/onap/aaf/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
+6. Exit container::
+
+ exit
+
Configuring in OOM deployment:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Static:
-"""""""
+Before OOM installation:
+""""""""""""""""""""""""
-*Note! This must be executed before calling make all or needs remaking aaf Charts*
+Note! This must be executed before calling *make all* (from OOM Installation) or needs remaking aaf Charts.
-1. Edit *cmpServers.json* file
- - 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*
+1. Edit *cmpServers.json* file. If OOM *global.addTestingComponents* flag is set to:
+
+ - *true* - edit *kubernetes/aaf/charts/aaf-cert-service/resources/test/cmpServers.json*
+ - *false* - edit *kubernetes/aaf/charts/aaf-cert-service/resources/default/cmpServers.json*
2. Build and start OOM deployment
-Dynamic:
-""""""""
+When CertService is deployed:
+"""""""""""""""""""""""""""""
-1. Encode your configuration to base64 (You can use for example online encoders or command line tool *base64*)
+1. Encode your configuration to base64::
+
+ echo "CONFIGURATION_TO_ENCODE" | base64
+
2. Edit secret::
kubectl edit secret <cmp-servers-secret-name> # aaf-cert-service-secret by default
@@ -125,8 +135,8 @@
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. New configuration will be automatically mounted to CertService pod, but application configuration reload is needed.
+6. To reload configuration enter CertService pod::
kubectl exec -it <cert-service-pod-name> bash
@@ -134,18 +144,22 @@
curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
+8. Exit container::
+
+ exit
+
Generating certificates for CertService and CertService Client
--------------------------------------------------------------
-CertService and CertService client use mutual TLS for communication. Certificates are generated using Makefile.
+CertService and CertService client use mutual TLS for communication. Certificates are generated during CertService installation.
-Local:
+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
+ - 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::
@@ -153,16 +167,56 @@
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. 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.
+Secrets take certificates from *kubernetes/aaf/charts/aaf-cert-service/resources* directory. Certificates are generated automatically during building (using Make) OOM repository.
*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.
+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.
+
+1. Set *tls.certificateExternalSecret* flag to true in *kubernetes/aaf/charts/aaf-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 p12 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
+
+3. Name the secret properly - the name should match *tls.server.secret.name* value from *kubernetes/aaf/charts/aaf-cert-service/values.yaml* file
+
+4. Prepare secret for CertService Client. It must be provided before OOM installation. It must contain two 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
+
+5. Name the secret properly - the name should match *global.aaf.certService.client.secret.name*
+
+6. Provide keystore and truststore passwords for CertService. It can be done in two ways:
+
+ - by inlining them into *kubernetes/aaf/charts/aaf-cert-service/values.yaml*:
+
+ - override *credentials.tls.keystorePassword* value with keystore password
+ - override *credentials.tls.truststorePassword* value with 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.aaf.certServiceClient.envVariables.keystorePassword* value with keystore password
+ - override *global.aaf.certServiceClient.envVariables.truststorePassword* value with truststore password
+
+
Configuring EJBCA server for testing
------------------------------------
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
index 599225a..00b9e08 100644
--- a/docs/sections/release-notes.rst
+++ b/docs/sections/release-notes.rst
@@ -6,6 +6,47 @@
Release Notes
=============
+Version: 1.0.1
+--------------
+
+:Release Date: 2020-xx-xx
+
+**New Features**
+
+The Frankfurt Release is the first release of the Certification Service.
+
+**Bug Fixes**
+
+ - `AAF-1132 <https://jira.onap.org/browse/AAF-1132>`_ - CertService Client returns exit status 5 when TLS configuration fails
+
+**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**
+
+**Other**
+
+===========
+
Version: 1.0.0
--------------
@@ -21,7 +62,7 @@
**Known Issues**
- N/A
+ - `AAF-1132 <https://jira.onap.org/browse/AAF-1132>`_ - CertService Client returns exit status 5 when TLS configuration fails
**Security Notes**