Merge "Refactor CmpResponseHelper to support intermediate certificate"

diff --git a/certService/README.md b/certService/README.md
index 8e7fccc..61506e7 100644 (file)
--- a/certService/README.md
+++ b/certService/README.md
@@ -88,11 +88,11 @@ path:
 cd /var/log/onap/aaf/certservice
 ```
 You should see:    
-audit.log  error.log  trace.log
+audit.log  error.log  debug.log
 
 ### RestAPI
 API is described by Swagger ( OpenAPI 3.0 ) on endpoint /docs 
 ( endpoint is defined in properties as springdoc.swagger-ui.path )
 ```
 http://localchost:8080/docs
-```
\ No newline at end of file
+```

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644 (file)
index 0000000..65513dc
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+       @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+clean:
+       @echo "##### Clean build directory #####"
+       rm -rf $(BUILDDIR)
+       @echo "##### Done #####"
+
+.PHONY: help clean Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+       @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

diff --git a/docs/README.md b/docs/README.md
new file mode 100644 (file)
index 0000000..15deade
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,21 @@
+## AAF Certification Service documentation
+###Requirements
+    Python 3.x
+
+To generate a documentation locally follow below steps.
+
+1. Open **docs** folder in terminal
+2. Install all required dependencies
+
+    ```
+    python install -r requirements-docs.txt
+   ```
+3. Generate local documentation
+    ```
+    make html
+    ```
+    After command execution the documentation will be available in **_build/html** folder.
+4. Before you commit documentation changes please execute
+    ```
+    make clean
+   ```

diff --git a/docs/conf.py b/docs/conf.py
index 8f40e8b..b37b90c 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -7,6 +7,9 @@ linkcheck_ignore = [
     'http://localhost',
 ]
 
+extensions = [
+    'sphinxcontrib.openapi',
+]
 intersphinx_mapping = {}
 
 html_last_updated_fmt = '%d-%b-%y %H:%M'

diff --git a/docs/index.rst b/docs/index.rst
index 87b6152..e84df93 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,7 +2,22 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright 2020 NOKIA
 
-AAF Cert Service
-------------------------------------------------
+AAF Certification Service
+=========================================
+
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
+   :caption: Contents:
+
+   sections/architecture.rst
+   sections/build.rst
+   sections/offeredapis.rst
+   sections/logging.rst
+   sections/installation.rst
+   sections/configuration.rst
+   sections/release-notes.rst
+
+Indices and tables
+==================
+
+* :ref:`search`

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index b3188dd..98fc25c 100644 (file)
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -10,6 +10,7 @@ sphinxcontrib-needs>=0.2.3
 sphinxcontrib-nwdiag
 sphinxcontrib-seqdiag
 sphinxcontrib-swaggerdoc
+sphinxcontrib-openapi
 sphinxcontrib-plantuml
 sphinx_bootstrap_theme
 lfdocs-conf

diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
new file mode 100644 (file)
index 0000000..9b1b481
--- /dev/null
+++ b/docs/sections/architecture.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Architecture
+============
+
+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 will be 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.
+CertService's client communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.
+
+.. image:: resources/certservice_high_level.jpg
+   :width: 855px
+   :height: 178px
+   :alt: Interaction between components

diff --git a/docs/sections/build.rst b/docs/sections/build.rst
new file mode 100644 (file)
index 0000000..d533e33
--- /dev/null
+++ b/docs/sections/build.rst
@@ -0,0 +1,61 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Build
+=====
+
+Jenkins
+-------
+#. JJB Master
+
+    https://jenkins.onap.org/view/aaf/job/aaf-certservice-master-merge-java/
+
+#. JJB Stage
+
+    https://jenkins.onap.org/view/aaf/job/aaf-certservice-maven-docker-stage-master/
+
+#. JJB Release
+
+    https://jenkins.onap.org/view/aaf/job/aaf-certservice-maven-stage-master/
+    https://jenkins.onap.org/view/aaf/job/aaf-certservice-release-merge/
+
+#. JJB CSIT
+
+    https://jenkins.onap.org/view/CSIT/job/aaf-master-csit-certservice/
+
+Environment
+-----------
+
+* Java 11
+* Apache Maven 3.6.0
+* Linux
+* Docker 18.09.5
+* Python 2.7.x
+
+How to build images?
+--------------------
+
+#. Checkout the project from https://gerrit.onap.org/r/#/admin/projects/aaf/certservice
+#. Read information's stored in README.md file
+#. Use a Makefile to build images::
+
+    make build
+
+How to start service locally?
+-----------------------------------------------
+#. Start Cert Service with configured EJBCA::
+
+    make start-backend
+
+#. Run Cert Service Client::
+
+    make run-client
+
+#. Remove client container::
+
+    make stop-client
+
+#. Stop Cert Service and EJBCA::
+
+    make stop-backend

diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
new file mode 100644 (file)
index 0000000..d49c86b
--- /dev/null
+++ b/docs/sections/configuration.rst
@@ -0,0 +1,110 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Configuration
+=============
+
+Standalone docker container
+---------------------------
+
+Certification Service Client image:
+
+.. code-block:: 
+
+  nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest 
+
+
+1. Create file with environments as in example below.
+
+.. code-block:: 
+
+  #Client envs
+  REQUEST_URL=http://aaf-cert-service-service:8080/v1/certificate/
+  REQUEST_TIMEOUT=1000
+  OUTPUT_PATH=/var/certs
+  CA_NAME=RA
+  #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
+
+
+2. Run docker container with environments file and docker network (API and client must be running in same network).
+
+.. code-block:: bash
+
+  AAFCERT_CLIENT_IMAGE=nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
+  DOCKER_ENV_FILE= <path to environment file>
+  NETWORK_CERT_SERVICE= <docker network of cert service>
+  DOCKER_VOLUME="<absolute path to local dir>:<output path>"
+
+  docker run --env-file $DOCKER_ENV_FILE --network $NETWORK_CERT_SERVICE --volume $DOCKER_VOLUME $AAFCERT_CLIENT_IMAGE
+
+
+
+Init Container for K8s
+----------------------
+
+Example deployment:
+
+.. 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.aaf.certservice.aaf-certservice-client:latest
+            imagePullPolicy: Always
+            env:
+              - name: REQUEST_URL
+                value: http://aaf-cert-service-service:8080/v1/certificate/
+              - name: REQUEST_TIMEOUT
+                value: "1000"
+              - name: OUTPUT_PATH
+                value: /var/certs
+              - name: CA_NAME
+                value: RA
+              - 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
+            volumeMounts:
+              - mountPath: /var/certs
+                name: certs
+          ...
+        volumes: 
+          -emptyDir: {}
+           name: certs
+        ...
+
+ 
\ No newline at end of file

diff --git a/docs/sections/installation.rst b/docs/sections/installation.rst
new file mode 100644 (file)
index 0000000..8ef137f
--- /dev/null
+++ b/docs/sections/installation.rst
@@ -0,0 +1,21 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Installation
+============
+
+.. note::
+   * This section is used to describe how a software component is acquired and installed.
+   
+   * This section is typically: provided for a platform-component and application; and
+     referenced in user guides.
+
+   * This note must be removed after content has been added.
+
+Environment
+-----------
+
+
+Steps
+-----

diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst
new file mode 100644 (file)
index 0000000..422b70a
--- /dev/null
+++ b/docs/sections/logging.rst
@@ -0,0 +1,70 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Logging
+=======
+
+Certification Service API 
+--------------------------
+
+
+Certification Service logs are available in the Docker container
+
+    docker exec -it aaf-certservice-api bash
+
+Path to logs:
+
+    /var/log/onap/aaf/certservice
+
+Available log files:
+    * audit.log
+    * debug.log
+    * error.log
+
+
+Certification Service Client
+----------------------------
+To see logs use :
+
+- Docker: 
+
+.. code-block:: bash
+   
+   docker logs cert-service-client
+
+- Kubernetes: 
+  
+.. code-block:: bash
+   
+   kubectl logs <pod-name> cert-service-client
+
+
+Logs are stored inside container log path:
+
+  /var/logs
+
+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 PKCS12 conversion                      |
++-------+------------------------------------------------+
+| 8     | Fail in Private Key to PEM Encoding            |
++-------+------------------------------------------------+

diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
new file mode 100644 (file)
index 0000000..31e53bc
--- /dev/null
+++ b/docs/sections/offeredapis.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+Offered APIs
+============
+
+AAF Cert Service Api
+--------------------
+
+.. openapi:: resources/OpenAPI.yaml

diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
new file mode 100644 (file)
index 0000000..bd00ac7
--- /dev/null
+++ b/docs/sections/release-notes.rst
@@ -0,0 +1,50 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020 NOKIA
+
+
+Release Notes
+=============
+
+Version: 1.0.0
+--------------
+
+:Release Date: 2020-03-25
+
+**New Features**
+
+The Frankfurt Release is the first release of the Certification Service.
+
+**Bug Fixes**
+
+        - No new fixes were implemented for this release
+
+**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**
+
+===========
+
+End of Release Notes

diff --git a/docs/sections/resources/OpenAPI.yaml b/docs/sections/resources/OpenAPI.yaml
new file mode 100644 (file)
index 0000000..cee5a40
--- /dev/null
+++ b/docs/sections/resources/OpenAPI.yaml
@@ -0,0 +1,158 @@
+openapi: 3.0.1
+info:
+  title: CertService Documentation
+  description: Certification service API documentation
+  version: 1.0.0
+servers:
+  - url: http://localhost:8080
+    description: Generated server url
+tags:
+  - name: Actuator
+    description: Monitor and interact
+    externalDocs:
+      description: Spring Boot Actuator Web API Documentation
+      url: https://docs.spring.io/spring-boot/docs/current/actuator-api/html/
+paths:
+  /v1/certificate/{caName}:
+    get:
+      tags:
+        - CertificationService
+      summary: sign certificate
+      description: Web endpoint for requesting certificate signing. Used by system
+        components to gain certificate signed by CA.
+      operationId: signCertificate
+      parameters:
+        - name: caName
+          in: path
+          description: Name of certification authority that will sign CSR.
+          required: true
+          schema:
+            type: string
+        - name: CSR
+          in: header
+          description: Certificate signing request in form of PEM object encoded in
+            Base64 (with header and footer).
+          required: true
+          schema:
+            type: string
+        - name: PK
+          in: header
+          description: Private key in form of PEM object encoded in Base64 (with header
+            and footer).
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: certificate successfully signed
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/CertificationModel'
+        "500":
+          description: something went wrong during connecting to cmp client
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/ErrorResponseModel'
+        "404":
+          description: CA not found for given name
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/ErrorResponseModel'
+        "400":
+          description: given CSR or/and PK is incorrect
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/ErrorResponseModel'
+  /ready:
+    get:
+      tags:
+        - CertificationService
+      summary: check is container is ready
+      description: Web endpoint for checking if service is ready to be used.
+      operationId: checkReady
+      responses:
+        "200":
+          description: configuration is loaded and service is ready to use
+          content:
+            application/json; charset=utf-8:
+              schema:
+                type: string
+        "503":
+          description: configuration loading failed and service is unavailable
+          content:
+            application/json; charset=utf-8:
+              schema:
+                type: string
+  /reload:
+    get:
+      tags:
+        - CertificationService
+      summary: reload service configuration from file
+      description: Web endpoint for performing configuration reload. Used to reload
+        configuration file from file.
+      operationId: reloadConfiguration
+      responses:
+        "200":
+          description: configuration has been successfully reloaded
+          content:
+            application/json; charset=utf-8:
+              schema:
+                type: string
+        "500":
+          description: something went wrong during configuration loading
+          content:
+            application/json; charset=utf-8:
+              schema:
+                $ref: '#/components/schemas/ErrorResponseModel'
+  /actuator/health:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator web endpoint 'health'
+      operationId: handle_0
+      responses:
+        "200":
+          description: default response
+          content: {}
+  /actuator/health/**:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator web endpoint 'health-path'
+      operationId: handle_1
+      responses:
+        "200":
+          description: default response
+          content: {}
+  /actuator:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator root web endpoint
+      operationId: links_2
+      responses:
+        "200":
+          description: default response
+          content: {}
+components:
+  schemas:
+    ErrorResponseModel:
+      type: object
+      properties:
+        errorMessage:
+          type: string
+    CertificationModel:
+      type: object
+      properties:
+        certificateChain:
+          type: array
+          items:
+            type: string
+        trustedCertificates:
+          type: array
+          items:
+            type: string

diff --git a/docs/sections/resources/certservice_high_level.jpg b/docs/sections/resources/certservice_high_level.jpg
new file mode 100644 (file)
index 0000000..1146698
Binary files /dev/null and b/docs/sections/resources/certservice_high_level.jpg differ