diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 23 | ||||
| -rw-r--r-- | docs/README.md | 21 | ||||
| -rw-r--r-- | docs/conf.py | 3 | ||||
| -rw-r--r-- | docs/index.rst | 21 | ||||
| -rw-r--r-- | docs/requirements-docs.txt | 1 | ||||
| -rw-r--r-- | docs/sections/architecture.rst | 18 | ||||
| -rw-r--r-- | docs/sections/build.rst | 61 | ||||
| -rw-r--r-- | docs/sections/configuration.rst | 110 | ||||
| -rw-r--r-- | docs/sections/installation.rst | 21 | ||||
| -rw-r--r-- | docs/sections/logging.rst | 70 | ||||
| -rw-r--r-- | docs/sections/offeredapis.rst | 11 | ||||
| -rw-r--r-- | docs/sections/release-notes.rst | 50 | ||||
| -rw-r--r-- | docs/sections/resources/OpenAPI.yaml | 158 | ||||
| -rw-r--r-- | docs/sections/resources/certservice_high_level.jpg | bin | 0 -> 24640 bytes |
14 files changed, 565 insertions, 3 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..65513dc3 --- /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 index 00000000..15deadea --- /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 8f40e8b8..b37b90cf 100644 --- 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 87b61527..e84df935 100644 --- 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 b3188ddd..98fc25ce 100644 --- 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 index 00000000..9b1b481e --- /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 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..d49c86bd --- /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 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..422b70a0 --- /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 index 00000000..31e53bc5 --- /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 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 diff --git a/docs/sections/resources/OpenAPI.yaml b/docs/sections/resources/OpenAPI.yaml new file mode 100644 index 00000000..cee5a402 --- /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 Binary files differnew file mode 100644 index 00000000..11466983 --- /dev/null +++ b/docs/sections/resources/certservice_high_level.jpg |
