diff options
Diffstat (limited to 'docs/sections')
| -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 |
9 files changed, 499 insertions, 0 deletions
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 |
