From 483ccbf2d8f0c71ebb15a4a47246a68a42e68f3e Mon Sep 17 00:00:00 2001 From: Bogumil Zebek Date: Wed, 25 Mar 2020 11:54:11 +0100 Subject: Documentation Issue-ID: AAF-1091 Signed-off-by: Zebek Bogumil Change-Id: I59df0545c4dd5adfde32c83988f89cd2d0c4676b --- docs/sections/architecture.rst | 18 +++ docs/sections/build.rst | 61 +++++++++++ docs/sections/configuration.rst | 28 +++++ docs/sections/img/certservice_high_level.jpg | Bin 0 -> 24640 bytes docs/sections/installation.rst | 21 ++++ docs/sections/logging.rst | 25 +++++ docs/sections/offeredapis.rst | 11 ++ docs/sections/openapi.yaml | 158 +++++++++++++++++++++++++++ docs/sections/release-notes.rst | 50 +++++++++ 9 files changed, 372 insertions(+) create mode 100644 docs/sections/architecture.rst create mode 100644 docs/sections/build.rst create mode 100644 docs/sections/configuration.rst create mode 100644 docs/sections/img/certservice_high_level.jpg create mode 100644 docs/sections/installation.rst create mode 100644 docs/sections/logging.rst create mode 100644 docs/sections/offeredapis.rst create mode 100644 docs/sections/openapi.yaml create mode 100644 docs/sections/release-notes.rst (limited to 'docs/sections') diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst new file mode 100644 index 00000000..654208d1 --- /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:: img/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 index 00000000..d533e330 --- /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 index 00000000..47f2dd87 --- /dev/null +++ b/docs/sections/configuration.rst @@ -0,0 +1,28 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2020 NOKIA + +Configuration +============= + +.. note:: + * This section is used to describe the options a software component offers for configuration. + + * Configuration is typically: provided for platform-component and sdk projects; + and referenced in developer and user guides. + + * This note must be removed after content has been added. + + + +Example ... + +You can provide the following in ``basic.conf`` + +``host=ADDRESS`` + The address of the host + +``port=PORT`` + The port used for signaling + + Optional. Default: ``8080`` diff --git a/docs/sections/img/certservice_high_level.jpg b/docs/sections/img/certservice_high_level.jpg new file mode 100644 index 00000000..11466983 Binary files /dev/null and b/docs/sections/img/certservice_high_level.jpg differ diff --git a/docs/sections/installation.rst b/docs/sections/installation.rst new file mode 100644 index 00000000..8ef137fc --- /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 index 00000000..159b5132 --- /dev/null +++ b/docs/sections/logging.rst @@ -0,0 +1,25 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2020 NOKIA + +Logging +======= + +Where to Access Information +--------------------------- + +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 + + diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst new file mode 100644 index 00000000..fe5807a8 --- /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:: ../../certService/OpenAPI.yaml diff --git a/docs/sections/openapi.yaml b/docs/sections/openapi.yaml new file mode 100644 index 00000000..cee5a402 --- /dev/null +++ b/docs/sections/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/release-notes.rst b/docs/sections/release-notes.rst new file mode 100644 index 00000000..bd00ac74 --- /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 -- cgit 1.2.3-korg