diff options
5 files changed, 172 insertions, 30 deletions
@@ -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 a10185b2..91f164e3 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.ExitStatus; 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 00000000..e1144a6b --- /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 f6078a41..fc75d11b 100644 --- a/docs/sections/configuration.rst +++ b/docs/sections/configuration.rst @@ -41,33 +41,35 @@ Example cmpServers.json file: 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 @@ Dynamic: 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:: + + echo "CONFIGURATION_TO_ENCODE" | base64 -1. Encode your configuration to base64 (You can use for example online encoders or command line tool *base64*) 2. Edit secret:: kubectl edit secret <cmp-servers-secret-name> # aaf-cert-service-secret by default @@ -125,8 +135,8 @@ Dynamic: 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 @@ Dynamic: 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 @@ All certificates are stored in *certservice/certs* directory. To recreate certif 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 599225a9..00b9e085 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 @@ The Frankfurt Release is the first release of the Certification Service. **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** |