OOM Certification Service

Introduction

Overview

In Frankfurt release AAF was enhanced by Certificate Management Protocol ver. 2 (CMPv2) support. Such support is handled by new AAF’s microservice called CertService. CertService provides certificates signed by external CMPv2 server - further on such certificates are called operators certificates. Operators certificates are meant to secure external ONAP traffic - traffic between network functions (xNFs) and ONAP.

In Guilin release CertService was moved from AAF repository to OOM repository.

Context View

CMPV2 Context View

It is planned that Network Functions (aka xNFs) will get certificates from the same CMPv2 server and the same CA hierarchy, but will use own means to get such certificates. Cause xNFs and ONAP will get certificates signed by the same root CA and will trust such root CA, both parties will automatically trust each other and can communicate with each other.

Functionality

In Frankfurt release only Initialization Request with ImplicitConfirm is supported.

Istanbul release includes also support for Key Update Request and Certification Request

Initialization Request and Certification Request sent to CMPv2 server are authenticated by secret value (initial authentication key) and reference value (used to identify the secret value) as described in RFC-4210. Key Update Request uses signature protection so old certificate and private key are needed to authenticate the request.

Security considerations

CertService’s REST API is protected by mutual HTTPS, meaning server requests client’s certificate and authenticate only requests with trusted certificate. After ONAP default installation only certificate from CertService’s client is trusted. Authorization isn’t supported in Frankfurt release.

Architecture

Interaction between components

Interaction between components

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.

CMPv2 external provider is 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 Certificate CR to get it.

CMPv2 external provider communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.

To proof that CertService works Open Source CMPv2 server (EJBCA) is deployed and used in E2E tests.

Simplified certificate enrollment flow

Simplified certificate enrollment flow

Build

Environment

  • Java 11

  • Apache Maven 3.6.0

  • Linux

  • Docker 18.09.5

  • Python 2.7.x

How to build images?

  1. Checkout the project from https://gerrit.onap.org/r/#/admin/projects/oom/platform/cert-service

  2. Read information stored in README.md file

  3. Use a Makefile to build images:

    make build

How to start service locally?

  1. Start Cert Service with configured EJBCA:

    make start-backend

  2. Run Cert Service Client:

    make run-client

  3. Remove client container:

    make stop-client

  4. Stop Cert Service and EJBCA:

    make stop-backend

Offered APIs

OOM Cert Service Api

# ============LICENSE_START=======================================================
# oom-certservice
# ================================================================================
# Copyright (C) 2020-2021 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=========================================================
openapi: 3.0.1
info:
  title: CertService Documentation
  description: Certification service API documentation
  version: 1.0.1
servers:
  - url: https://localhost:8443
    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-update/{caName}:
    get:
      tags:
        - CertificationService
      summary: Update certificate
      description: Web endpoint for updating certificate. Used by system
        components to update certificate signed by CA.
      operationId: updateCertificate
      parameters:
        - name: caName
          in: path
          description: Name of certification authority that will update certificate.
          required: true
          schema:
            type: string
            example: "RA_TEST"
        - 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
            example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJREZqQ0NBZjRDQVFBd2R6RUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQWdNQ2tOaGJHbG1iM0p1YVdFeApGakFVQmdOVkJBY01EVk5oYmkxR2NtRnVZMmx6WTI4eERUQUxCZ05WQkFzTUJFOU9RVkF4R1RBWEJnTlZCQW9NCkVFeHBiblY0TFVadmRXNWtZWFJwYjI0eEVUQVBCZ05WQkFNTUNHOXVZWEF1YjNKbk1JSUJJakFOQmdrcWhraUcKOXcwQkFRRUZBQU9DQVE4QU1JSUJDZ0tDQVFFQXlVbWVvY0o2V09jRHBOR0x2SzRGMURkK3JVTDVBNjlQTVpwSApDSUlQZ2xrakNxcGlLL28yeFJlTTZ5VTlPVkpRcUJJUzRPeUFvWGxlKzJ4OURDanA2U1JpV2RJZEV2NFAzNk1nClRBV3lUdndta1dMYXFodmlwKzZQM0xUOGt0aktDL0JKVXo3dXlOWjAvTEdMWThpbWw1U1hnckQ0WlBvY2VrYzMKMStQZ0NrLzBTZWd6M0JaQkJVOVYwWXFtWFhlZDNkcHY3M1VFTXVESTVIY2NjSlFybkdUSkxDVTlJaWFJa1lQRgozQkhTVWpmbkVrS0hINWVwcTMwVEdyUytscFhxbHJ0cFFEWmIveHZpU3YyRjZWSVhGbURWdkl2RkNPaTZaMVlsClZvenVmNHhQRHQ5cmJxY1RUaGhjeVVqYWdDbnlwTmJzYms5U2QrWXFyNk1JbkZaNUZRSURBUUFCb0Zvd1dBWUoKS29aSWh2Y05BUWtPTVVzd1NUQkhCZ05WSFJFRVFEQStnZzEwWlhOMExtOXVZWEF1YjNKbmdnaHZibUZ3TG05eQpaNGNFZndBQUFZWU9ablJ3T2k4dmRHVnpkQzV2Y21lQkRYUmxjM1JBYjI1aGNDNXZjbWN3RFFZSktvWklodmNOCkFRRUxCUUFEZ2dFQkFJRTU0NFJ0RW5YRE5oQndKWDFGZ0Y4YzN5ck05SHcwNEw4VktNdnRaTlBjQU1SNC9lV0IKYTFDcE5uZVBQZktScWxiakxhOHplTW9iWWxGYlJVbGFvbnkzQXE4TlpiMFMxZ0RUWnFQWUQzRjNkMnhRUGJxOQpPbTR2Ly8zaGRIZlIvdFFCa3NPRkl0QkwvMW9jV004RTZqRm8rdU41ZGlCb3EyMUFvT0NXK1BMYWVnUG9jaGdYClJhZGcxc0JneW1tR3BDV0tNMy9UNnJTZEFvVmFoTzJ6VDd4NGhlRjNEazdsUUN5ZmdySUZDOHd2TmhBWWx1K1IKTmdoTVdNNEcvZzJPMHJvNVYzdWc4LzZ5UnovbDlhWXVJclRDNnVDaGJ3UXJFcEd4ZXR5WEd5bWE1Q2IxcTZyagpNdHNpQ0FneTBkR2dIZ2tOOVJrK3hHRC9BOGhzNURDSmdQUT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUgUkVRVUVTVC0tLS0tCg=="
        - name: PK
          in: header
          description: Private key in form of PEM object encoded in Base64 (with header and footer).
          required: true
          schema:
            type: string
            example: "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2d0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktrd2dnU2xBZ0VBQW9JQkFRREpTWjZod25wWTV3T2sKMFl1OHJnWFVOMzZ0UXZrRHIwOHhta2NJZ2crQ1dTTUtxbUlyK2piRkY0enJKVDA1VWxDb0VoTGc3SUNoZVY3NwpiSDBNS09ucEpHSlowaDBTL2cvZm95Qk1CYkpPL0NhUll0cXFHK0tuN28vY3RQeVMyTW9MOEVsVFB1N0kxblQ4CnNZdGp5S2FYbEplQ3NQaGsraHg2UnpmWDQrQUtUL1JKNkRQY0ZrRUZUMVhSaXFaZGQ1M2QybS92ZFFReTRNamsKZHh4d2xDdWNaTWtzSlQwaUpvaVJnOFhjRWRKU04rY1NRb2NmbDZtcmZSTWF0TDZXbGVxV3UybEFObHYvRytKSwovWVhwVWhjV1lOVzhpOFVJNkxwblZpVldqTzUvakU4TzMydHVweE5PR0Z6SlNOcUFLZktrMXV4dVQxSjM1aXF2Cm93aWNWbmtWQWdNQkFBRUNnZ0VCQUxEYnBhejlncUNBZ2x3YjNjcXZvT0dBelNZUk5WaCtmWGZZMVZidGFCRWcKbnNCdFNvclhjNjRpN2lkaDlmUmFsaEhHcDUzSFQ1SVJZVnBLVFdrVXZjbWl0V08wVU9WeUk2SmM0ekRJeEkzUAowVmRtNHpnWi9rR05SQXdwWGM3cytrSVpJMlFvWkloRW5rKzA5QU45dHBweTdkamdBN0E5Ymk0bVN6Tyt2Z2h2Ci9KMnErZlNzTm5hbWE2MGFDMC90QzBEYmlVZ2xFN0taaGVQTjlqaGZCa1pLUW1MUVpUMHJQWE1sU2gvdU41SWUKSGpBYkVQVHJCdGxTZ2pRT2o5ZnJhSk9xRm1tL3hGQ2YvKzRuNU0xeGNpQVBoeUZydDdSU1NuZ2tOcW50VkVXUQpxSytMSWlDSHpLMFpBUWhVMGVSVXZqRjVWK210QjhPaEpNSkxMQkVvS0NFQ2dZRUEvWU05YlB4bVVzS2VCclZiClVtRlg5TXRKWmZwd1lLbkQveVh0MjZWcHM4OEZhbEhsSDd6R3MvQitZYjZXMGgxcnBzUWoreTJtejMvS092eEgKMFA2Um01R0ZJNjhsdXc1UUlHV1FMT2FtaThUZW9yU21vQXp3TkVOL1lpdFY3UURPdVZTQUZiVTJBTkRRMWZaawpFY29HeHdLbC9pOEtWTDF1Z2pseEE1ZWp6dzBDZ1lFQXkwTTBGTTRVendzRHRJbW5hMkRwYmlobGFxQ0dZVWxQCmQ2N2NidDlWejZ6NE1MMm00TlZZOUdhdU9OQUF0R2VVSTlNYnlqNVlmaVJaSXFtc0RjaU16eGtMeDJOTzlUaTEKaHJJZzJxeUNubFhJVWtmQkxxUG94Z3FYeHBpS1hnblYwNU9VWEdHVW5Ya2JNNjZsNlVEMUw0YnVpMzVVRDI3Uwp3ajdCMGdodmtDa0NnWUVBdit3dWdhYm5sRG9RUnNYZnVCTkg4bVJBVWZyeVBzdm5QTytyRGtGQkw4Wkh0RUVCCnREQkhRZ3lNc1ZVSGUxU1luaTBaakZ2NFVGalBjaTV4OUMvMWJoQVIrbnpybEp4MlhzQmxFUWtoQnVscEgwYWkKYXNMQXl1QmF2S2hRS2RnVnFNcm5HUWdTTlRYaEZFcXZZYVJQMHpRWEZNTHFFRk5GS1VOeFlxWFhkclVDZ1lCegpleUR4MlF1MWZicURMZG55aGNMWmxSWFplSTRnWTdoRWRSSkQ0NXNyUEVoZDJNSWc1dFY5TllFeVFlckVsRHgwCkJoSzUycVlJTkxwM21SSnBXbEcxcjdNamV1WjNKOXJxUmZXb2gyNUdhdEkrL1FsaWFEbHRtc01VVDhIOUgzVmUKbVhBbTlFR3RIZ3M0VjdkblNFS0UyQkpiS2xDejIvRGQ3eTNMR0lQWjBRS0JnUUNLRTRMMEhxSkkwV2ZFKzlMYQpONCtjems2dnBoOUdlbHNib1NIM1FBN3V0cDFQdWo0ZU5kZ0tNZUJiczgvQk5JMWFLdFI0c3JFT2VKbkpxSStoCkdRRHc5V1cxSHAyNGlFUXp6QXJLQTNlY2JMYTNwQkhyR3RhMk14VHFBb1NtMWkwU3BybWIvRkNNd0Q1ZDNDV1YKYnp0R29yemhiOVJYdUhnYlZ3OWZZdU1XQlE9PQotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0tCg=="
        - name: OLD_CERT
          in: header
          description: Old certificate in form of PEM object encoded in Base64 (with header and footer).
          required: true
          schema:
            type: string
            example: "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2d0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktrd2dnU2xBZ0VBQW9JQkFRQ3owYnhqaytOSXNzVzMKTDBUazhZS2Rvd1UxZ0VUWUVoeWQ5d0c1M1E4VkcwOFV6cW9QVml4N0lSSXB1cDdDbG9GelErQmxwUUNoZEp1bQpoVmE1dXRjdFhXYVRId0FjRUxjc0hzdEZiZlFLcnMxempGOE1tdW1XcWo1NXdyOTVBcmJCdm1kOW9QL2hKMkRECkd1OUNmM3VzUTl2Qk1GYjJ4eXRKb2tBY1c0ME50UmgyOEhYaTRLZUFBcTIwQVF0dnVLQzd3L0Uvbkt5bmlPM08Kb3lOcEh5KzlZYW1aSDJCRi9CK0xiM2RibkZPNFVCc3JoSk5tTFhkMFBtTmNhRC9NMjJxMzlHdWRnRGNheHZFZwpTaVFRVURNTG1rb3llQUNkRzNaVnVSSlRNZGZscHI3djlocVJETVcxUlJKMEYzWWdjNmN3b0lodGdraEZHZWFtClQ5RHpaSkJyQWdNQkFBRUNnZ0VCQUpwY3lvN2t6akNESHMweEs4QXBQb29aL29lOTg5dFVPUEsxcnVxaHhLZkcKeUsxQTk2V3d3UUIyRkVSMEtvTTZkaWUvdGVzcnFRM3dyd2xVMzIwUzRsTFVJaERiaE5tUzA5dHhGK2dqQ21MOQpTZXNPTGk0QThkTGZsRUFzR1BoRmh5TnNVeVQ2UjQ0OW9vZjZJRGdDZmVVVVg1cEk1KzV5YlV1SmwrV0FCZWNrCkF4aWo1U21TNlpHUnN3L0FIMnUzYWsyTEw0a3lCbTVZd0E4cE5yR3UyTjM2TGJ0djI2aWlQUXdhSlBEeWlPaE0KcW5nUHBKd2s2MHVRb3IrK0xRdUYvN3B3Qm1XOGo3VmRhM3YwZkR6L3hiTXljVE1BRHA2b1pxcFhWRGs4Q0tSYgpiNndCa0ZxbHpwVDc0cTFyYlhrRUJFUjZaTnV5bHhmeWFoQjBGdXZDdnhFQ2dZRUE3N3BCaVcrUEJOeGg1SlBLCjNnM1JGckErYzR3WG0zU1VOTXRIL1JBenVEM01nRGlaRGZXV3FMQVQySlF6VUUwNm03NUZyNzdHa3MwWXQ3WkMKWmxCdko3a3RVSU9oS0ZxMTJqVjYrbWVJV29ka05hdGd1MmZVUGxlaDVwWGhLV1RUUHRUaTkyYWFKUG5PSWQ3UApDQ21PUjBxV1ZmcUk1LzNpaVhZOXNVRm5mVmtDZ1lFQXdBWjBRdENKcGw1SWw0QjVZWS82VXJpOUdLbXQ1MjNzCmJPNWRLRHg1RHYyU3preGZkeU5YN2FnZXBSZ3VrSGpKZ0x2anNTWnlPeEVwaThiQ3d1bTJ1MngyR0p6ektNQmgKVVdrakdTVE5JVkJKUTBhOCs3NVV3bHBJQXhqMFE1RkVMNXVEUm41NFNHN2NnRlpqRmhBTE1qT09vVUFpbk5QagptSkQ2eDFVQjcyTUNnWUVBeFIvQk9FUVZ0SWVMcjZ1Znk0eE0vSDBjUFdOYkhpZDBueHp4S3pTaGNzVE9YamtzCkVnQjZUR2ZOU2ZCRGFhcTNvTTJLL0FMQndvRUg3RGpnek1ValFlVFJVRDJNeldRWjJUN1V5d2RMWmpXaXYwY1gKR2NNOUVhNTVvT1JwNitIT213SHZTRVNFU0JkcDJ3d2Q3YlpPR20xSXhaWm44V3doVmF0MiswU3UxckVDZ1lBeApNZlliSC80RDUyZkZtSjZBUmppbGRMck5WTHMrN1VTQzY5Wmw5b2cxTlBXbGNKK01rRHQ0b1hlb2FEZVZ2N3d3CkJQTGljYTBXUU9GWjlBUDFsNWEvRVp4MzFjM2VCTnRwMWZ1dDkyV3VRVGxqeVAybHFTOWgwMnRiajhzVWZHVHgKcFcvT1laeERRbE92ZFhKUk5xOEhuM25OQ2ZkVUlsek91MlhrSjMwbGJRS0JnUUROZlV1THB5V1B2cGh0SHhTMwpaek9tbHRwM2pkNHVSQkJ6b25KZWNKSFF5N3lpY3VleFlib0RUTjRmaG5aTExoL0dCT05iOXBXK2ZLTVVkeDIxCjh0anJiZUdHengyOHNBMFBHWTMxZlA0aC9xNmY2QXdCVllUa1pkeHNJTmE4WS9EcUxYNmt5Z0VLSXliMGZLQnIKS09ldUlZYTN2cUdGUndSWXU1NTNsMmtqRHc9PQotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0tCg=="
        - name: OLD_PK
          in: header
          description: Old private key (corresponding with old certificate) in form of PEM object
            encoded in Base64 (with header and footer).
          required: true
          schema:
            type: string
            example: "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2d0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktrd2dnU2xBZ0VBQW9JQkFRQ3owYnhqaytOSXNzVzMKTDBUazhZS2Rvd1UxZ0VUWUVoeWQ5d0c1M1E4VkcwOFV6cW9QVml4N0lSSXB1cDdDbG9GelErQmxwUUNoZEp1bQpoVmE1dXRjdFhXYVRId0FjRUxjc0hzdEZiZlFLcnMxempGOE1tdW1XcWo1NXdyOTVBcmJCdm1kOW9QL2hKMkRECkd1OUNmM3VzUTl2Qk1GYjJ4eXRKb2tBY1c0ME50UmgyOEhYaTRLZUFBcTIwQVF0dnVLQzd3L0Uvbkt5bmlPM08Kb3lOcEh5KzlZYW1aSDJCRi9CK0xiM2RibkZPNFVCc3JoSk5tTFhkMFBtTmNhRC9NMjJxMzlHdWRnRGNheHZFZwpTaVFRVURNTG1rb3llQUNkRzNaVnVSSlRNZGZscHI3djlocVJETVcxUlJKMEYzWWdjNmN3b0lodGdraEZHZWFtClQ5RHpaSkJyQWdNQkFBRUNnZ0VCQUpwY3lvN2t6akNESHMweEs4QXBQb29aL29lOTg5dFVPUEsxcnVxaHhLZkcKeUsxQTk2V3d3UUIyRkVSMEtvTTZkaWUvdGVzcnFRM3dyd2xVMzIwUzRsTFVJaERiaE5tUzA5dHhGK2dqQ21MOQpTZXNPTGk0QThkTGZsRUFzR1BoRmh5TnNVeVQ2UjQ0OW9vZjZJRGdDZmVVVVg1cEk1KzV5YlV1SmwrV0FCZWNrCkF4aWo1U21TNlpHUnN3L0FIMnUzYWsyTEw0a3lCbTVZd0E4cE5yR3UyTjM2TGJ0djI2aWlQUXdhSlBEeWlPaE0KcW5nUHBKd2s2MHVRb3IrK0xRdUYvN3B3Qm1XOGo3VmRhM3YwZkR6L3hiTXljVE1BRHA2b1pxcFhWRGs4Q0tSYgpiNndCa0ZxbHpwVDc0cTFyYlhrRUJFUjZaTnV5bHhmeWFoQjBGdXZDdnhFQ2dZRUE3N3BCaVcrUEJOeGg1SlBLCjNnM1JGckErYzR3WG0zU1VOTXRIL1JBenVEM01nRGlaRGZXV3FMQVQySlF6VUUwNm03NUZyNzdHa3MwWXQ3WkMKWmxCdko3a3RVSU9oS0ZxMTJqVjYrbWVJV29ka05hdGd1MmZVUGxlaDVwWGhLV1RUUHRUaTkyYWFKUG5PSWQ3UApDQ21PUjBxV1ZmcUk1LzNpaVhZOXNVRm5mVmtDZ1lFQXdBWjBRdENKcGw1SWw0QjVZWS82VXJpOUdLbXQ1MjNzCmJPNWRLRHg1RHYyU3preGZkeU5YN2FnZXBSZ3VrSGpKZ0x2anNTWnlPeEVwaThiQ3d1bTJ1MngyR0p6ektNQmgKVVdrakdTVE5JVkJKUTBhOCs3NVV3bHBJQXhqMFE1RkVMNXVEUm41NFNHN2NnRlpqRmhBTE1qT09vVUFpbk5QagptSkQ2eDFVQjcyTUNnWUVBeFIvQk9FUVZ0SWVMcjZ1Znk0eE0vSDBjUFdOYkhpZDBueHp4S3pTaGNzVE9YamtzCkVnQjZUR2ZOU2ZCRGFhcTNvTTJLL0FMQndvRUg3RGpnek1ValFlVFJVRDJNeldRWjJUN1V5d2RMWmpXaXYwY1gKR2NNOUVhNTVvT1JwNitIT213SHZTRVNFU0JkcDJ3d2Q3YlpPR20xSXhaWm44V3doVmF0MiswU3UxckVDZ1lBeApNZlliSC80RDUyZkZtSjZBUmppbGRMck5WTHMrN1VTQzY5Wmw5b2cxTlBXbGNKK01rRHQ0b1hlb2FEZVZ2N3d3CkJQTGljYTBXUU9GWjlBUDFsNWEvRVp4MzFjM2VCTnRwMWZ1dDkyV3VRVGxqeVAybHFTOWgwMnRiajhzVWZHVHgKcFcvT1laeERRbE92ZFhKUk5xOEhuM25OQ2ZkVUlsek91MlhrSjMwbGJRS0JnUUROZlV1THB5V1B2cGh0SHhTMwpaek9tbHRwM2pkNHVSQkJ6b25KZWNKSFF5N3lpY3VleFlib0RUTjRmaG5aTExoL0dCT05iOXBXK2ZLTVVkeDIxCjh0anJiZUdHengyOHNBMFBHWTMxZlA0aC9xNmY2QXdCVllUa1pkeHNJTmE4WS9EcUxYNmt5Z0VLSXliMGZLQnIKS09ldUlZYTN2cUdGUndSWXU1NTNsMmtqRHc9PQotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0tCg=="
      responses:
        "200":
          description: Certificate successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationResponseModel'
        "400":
          description: 'Given CSR, PK, old certificate or/and old PK is incorrect'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
        "404":
          description: CA not found for given name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
        "500":
          description: Something went wrong during connection to CMPv2 server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
  '/v1/certificate/{caName}':
    get:
      tags:
        - CertificationService
      summary: Initialize certificate
      description: Web endpoint for requesting certificate initialization. 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
            example: "RA_TEST"
        - name: CSR
          in: header
          description: Certificate initialization request in form of PEM object encoded in
            Base64 (with header and footer).
          required: true
          schema:
            type: string
            example: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJREZqQ0NBZjRDQVFBd2R6RUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQWdNQ2tOaGJHbG1iM0p1YVdFeApGakFVQmdOVkJBY01EVk5oYmkxR2NtRnVZMmx6WTI4eERUQUxCZ05WQkFzTUJFOU9RVkF4R1RBWEJnTlZCQW9NCkVFeHBiblY0TFVadmRXNWtZWFJwYjI0eEVUQVBCZ05WQkFNTUNHOXVZWEF1YjNKbk1JSUJJakFOQmdrcWhraUcKOXcwQkFRRUZBQU9DQVE4QU1JSUJDZ0tDQVFFQXM5RzhZNVBqU0xMRnR5OUU1UEdDbmFNRk5ZQkUyQkljbmZjQgp1ZDBQRlJ0UEZNNnFEMVlzZXlFU0ticWV3cGFCYzBQZ1phVUFvWFNicG9WV3ViclhMVjFta3g4QUhCQzNMQjdMClJXMzBDcTdOYzR4ZkRKcnBscW8rZWNLL2VRSzJ3YjVuZmFELzRTZGd3eHJ2UW45N3JFUGJ3VEJXOXNjclNhSkEKSEZ1TkRiVVlkdkIxNHVDbmdBS3R0QUVMYjdpZ3U4UHhQNXlzcDRqdHpxTWphUjh2dldHcG1SOWdSZndmaTI5MwpXNXhUdUZBYks0U1RaaTEzZEQ1alhHZy96TnRxdC9Scm5ZQTNHc2J4SUVva0VGQXpDNXBLTW5nQW5SdDJWYmtTClV6SFg1YWErNy9ZYWtRekZ0VVVTZEJkMklIT25NS0NJYllKSVJSbm1way9RODJTUWF3SURBUUFCb0Zvd1dBWUoKS29aSWh2Y05BUWtPTVVzd1NUQkhCZ05WSFJFRVFEQStnZzEwWlhOMExtOXVZWEF1YjNKbmdnaHZibUZ3TG05eQpaNGNFZndBQUFZWU9ablJ3T2k4dmRHVnpkQzV2Y21lQkRYUmxjM1JBYjI1aGNDNXZjbWN3RFFZSktvWklodmNOCkFRRUxCUUFEZ2dFQkFFb3JtOWJ2NTlVVk5ESHhLSlgzREFIT0w2cXVvVnBrRUNhS0xWaVVwaG9CS0c4MU1CN0kKY0k0S211bm5pbzRIa002LytZQmlpYnJXV1c1WFFFWFpKYTRkMnE1SnlRNFNMaXFnT1o4OWRlRm1iTEdTbGFaSQpwLzFmaTFlRVY0aU5wK1FhKzJBbHhTTEZVWmpFamtCRUNJVWs4ZEJERE5ZUXA2MEduazRLSjJkbDVxYTc1dzNsCkFhT2VlcFgvSHdJK2pRc2FIZHFZUW9aUFhuWXF4V2FaVWtNOG9PSXEzTUxzZDNGcGdzcnlUWXVqZDJxeTlTa2oKZjYyNElhU2tmeXVQZEJwdTZENWw5SjZOUmxtY25iWVJydHFaRGtmZXBYV1NPMHEyLzFBR0VSa0ppdTRYR1lLbwo3b0I0MWFvKzNva1V6RmUyOUlseXVmWUhHU0xmaFRtdkp1TT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUgUkVRVUVTVC0tLS0tCg=="
        - name: PK
          in: header
          description: Private key in form of PEM object encoded in Base64 (with header
            and footer).
          required: true
          schema:
            type: string
            example: "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2d0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktrd2dnU2xBZ0VBQW9JQkFRQ3owYnhqaytOSXNzVzMKTDBUazhZS2Rvd1UxZ0VUWUVoeWQ5d0c1M1E4VkcwOFV6cW9QVml4N0lSSXB1cDdDbG9GelErQmxwUUNoZEp1bQpoVmE1dXRjdFhXYVRId0FjRUxjc0hzdEZiZlFLcnMxempGOE1tdW1XcWo1NXdyOTVBcmJCdm1kOW9QL2hKMkRECkd1OUNmM3VzUTl2Qk1GYjJ4eXRKb2tBY1c0ME50UmgyOEhYaTRLZUFBcTIwQVF0dnVLQzd3L0Uvbkt5bmlPM08Kb3lOcEh5KzlZYW1aSDJCRi9CK0xiM2RibkZPNFVCc3JoSk5tTFhkMFBtTmNhRC9NMjJxMzlHdWRnRGNheHZFZwpTaVFRVURNTG1rb3llQUNkRzNaVnVSSlRNZGZscHI3djlocVJETVcxUlJKMEYzWWdjNmN3b0lodGdraEZHZWFtClQ5RHpaSkJyQWdNQkFBRUNnZ0VCQUpwY3lvN2t6akNESHMweEs4QXBQb29aL29lOTg5dFVPUEsxcnVxaHhLZkcKeUsxQTk2V3d3UUIyRkVSMEtvTTZkaWUvdGVzcnFRM3dyd2xVMzIwUzRsTFVJaERiaE5tUzA5dHhGK2dqQ21MOQpTZXNPTGk0QThkTGZsRUFzR1BoRmh5TnNVeVQ2UjQ0OW9vZjZJRGdDZmVVVVg1cEk1KzV5YlV1SmwrV0FCZWNrCkF4aWo1U21TNlpHUnN3L0FIMnUzYWsyTEw0a3lCbTVZd0E4cE5yR3UyTjM2TGJ0djI2aWlQUXdhSlBEeWlPaE0KcW5nUHBKd2s2MHVRb3IrK0xRdUYvN3B3Qm1XOGo3VmRhM3YwZkR6L3hiTXljVE1BRHA2b1pxcFhWRGs4Q0tSYgpiNndCa0ZxbHpwVDc0cTFyYlhrRUJFUjZaTnV5bHhmeWFoQjBGdXZDdnhFQ2dZRUE3N3BCaVcrUEJOeGg1SlBLCjNnM1JGckErYzR3WG0zU1VOTXRIL1JBenVEM01nRGlaRGZXV3FMQVQySlF6VUUwNm03NUZyNzdHa3MwWXQ3WkMKWmxCdko3a3RVSU9oS0ZxMTJqVjYrbWVJV29ka05hdGd1MmZVUGxlaDVwWGhLV1RUUHRUaTkyYWFKUG5PSWQ3UApDQ21PUjBxV1ZmcUk1LzNpaVhZOXNVRm5mVmtDZ1lFQXdBWjBRdENKcGw1SWw0QjVZWS82VXJpOUdLbXQ1MjNzCmJPNWRLRHg1RHYyU3preGZkeU5YN2FnZXBSZ3VrSGpKZ0x2anNTWnlPeEVwaThiQ3d1bTJ1MngyR0p6ektNQmgKVVdrakdTVE5JVkJKUTBhOCs3NVV3bHBJQXhqMFE1RkVMNXVEUm41NFNHN2NnRlpqRmhBTE1qT09vVUFpbk5QagptSkQ2eDFVQjcyTUNnWUVBeFIvQk9FUVZ0SWVMcjZ1Znk0eE0vSDBjUFdOYkhpZDBueHp4S3pTaGNzVE9YamtzCkVnQjZUR2ZOU2ZCRGFhcTNvTTJLL0FMQndvRUg3RGpnek1ValFlVFJVRDJNeldRWjJUN1V5d2RMWmpXaXYwY1gKR2NNOUVhNTVvT1JwNitIT213SHZTRVNFU0JkcDJ3d2Q3YlpPR20xSXhaWm44V3doVmF0MiswU3UxckVDZ1lBeApNZlliSC80RDUyZkZtSjZBUmppbGRMck5WTHMrN1VTQzY5Wmw5b2cxTlBXbGNKK01rRHQ0b1hlb2FEZVZ2N3d3CkJQTGljYTBXUU9GWjlBUDFsNWEvRVp4MzFjM2VCTnRwMWZ1dDkyV3VRVGxqeVAybHFTOWgwMnRiajhzVWZHVHgKcFcvT1laeERRbE92ZFhKUk5xOEhuM25OQ2ZkVUlsek91MlhrSjMwbGJRS0JnUUROZlV1THB5V1B2cGh0SHhTMwpaek9tbHRwM2pkNHVSQkJ6b25KZWNKSFF5N3lpY3VleFlib0RUTjRmaG5aTExoL0dCT05iOXBXK2ZLTVVkeDIxCjh0anJiZUdHengyOHNBMFBHWTMxZlA0aC9xNmY2QXdCVllUa1pkeHNJTmE4WS9EcUxYNmt5Z0VLSXliMGZLQnIKS09ldUlZYTN2cUdGUndSWXU1NTNsMmtqRHc9PQotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0tCg=="
      responses:
        "200":
          description: Certificate successfully signed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationResponseModel'
        "400":
          description: Given CSR or/and PK is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
        "404":
          description: CA not found for given name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
        "500":
          description: Something went wrong during connection to CMPv2 server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
  /ready:
    get:
      tags:
        - CertificationService
      summary: Check if CertService application 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: {}
        "503":
          description: Configuration loading failed and service is unavailable
          content: {}
  /reload:
    get:
      tags:
        - CertificationService
      summary: Reload CMPv2 servers configuration from configuration file
      description: Web endpoint for performing configuration reload. Used to reload
        configuration from file.
      operationId: reloadConfiguration
      responses:
        "200":
          description: Configuration has been successfully reloaded
          content: {}
        "500":
          description: Something went wrong during configuration loading
          content:
            string:
              schema:
                type: string
                example: "can't parse JSON.  Raw result: Exception occurred during CMP Servers configuration loading"
  /actuator/health:
    get:
      tags:
        - Actuator
      summary: Actuator web endpoint 'health'
      operationId: healthCheck
      responses:
        "200":
          description: Service is healthy
          content:
            string:
              schema:
                $ref: '#/components/schemas/StatusResponseModel'
components:
  schemas:
    StatusResponseModel:
      type: object
      properties:
        status:
          type: string
          example: "UP"
    ErrorResponseModel:
      type: object
      properties:
        errorMessage:
          type: string
          example: "Internal server error"
    CertificationResponseModel:
      type: object
      properties:
        certificateChain:
          type: array
          items:
            type: string
            example: "-----BEGIN CERTIFICATE-----\nMIIErDCCAxSgAwIBAgIUfYvpzoT6WTxiu2KtxDwdvB56iVUwDQYJKoZIhvcNAQEL\nBQAwYTEjMCEGCgmSJomT8ixkAQEME2MtMGI1YzFhYTBkNzA4NjVjNGUxFTATBgNV\nBAMMDE1hbmFnZW1lbnRDQTEjMCEGA1UECgwaRUpCQ0EgQ29udGFpbmVyIFF1aWNr\nc3RhcnQwHhcNMjAwNDAxMTAyNzAwWhcNMjIwNDAxMTAyNDEyWjCBlzEeMBwGCSqG\nSIb3DQEJARYPdGVzdGVyQG9uYXAub3JnMREwDwYDVQQDDAhvbmFwLm9yZzENMAsG\nA1UECwwET05BUDEZMBcGA1UECgwQTGludXgtRm91bmRhdGlvbjEWMBQGA1UEBwwN\nU2FuLUZyYW5jaXNjbzETMBEGA1UECAwKQ2FsaWZvcm5pYTELMAkGA1UEBhMCVVMw\nggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDNDMk82GQQNr+uBGEhGMpP\nW8P/xk6WqntF2drXaaodJqMIcbF235E58z8kfo4yzown2nm0hM1RB4I8P2k3xkmz\nT42J38Mwyg/DWjHq+vhb0XHH6wXuGD42BvXiWh5WGhrSP0nBd6yL4jwyU82V0sTI\nVu+eXzbv20Hzq92IaHudBzM76e/3M+N9hSoeGJD5mbQVyZqqdQjyfGJs/povX+dd\nPuHKlwSzz6LOxhUqO5aknx52y05IBr11jL4RprU41n0NMILT59zwokDhtxhDg6Q5\nqp+vGpwsv28j89D1+ZrxJCl+q5Kd3+fc2Tf5KFu4Gtn5Ww8SGVmkiiJa7+Wv2S/P\nAgMBAAGjgaQwgaEwDAYDVR0TAQH/BAIwADAfBgNVHSMEGDAWgBQ4TWsw5NCfgMjt\nc6sLNV008AniSjAiBgNVHREEGzAZgghvbmFwLm9yZ4INdGVzdC5vbmFwLm9yZzAd\nBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwQwHQYDVR0OBBYEFAMyW8sAIjOG\n4qiMVEWuBfliFNeyMA4GA1UdDwEB/wQEAwIF4DANBgkqhkiG9w0BAQsFAAOCAYEA\nCviGRpVZgd4Vr3R3pslegH9GRa1TmCVP8wTD6CUA84VqMzVatcdWbaDFNoCVv54v\nUCYPsN8REx/I53R1jbQ5tralj8JMublrdDaKDQY7OdfjL53nGS4OGl76ZLMt50cF\nnXreoSixCdv3OkPO7+P5szzfnwcCQEa235GfHOxAKv2DIhI8+aFMdi1vTJMYmROs\nYA/6DuJAFjfjPM6T4hzKdW8FPyyUw4kWSNRtt+cxN1JxGDYRt1bnjj7u7nMA5Mge\noWn5oeHLO8rkWgMy0BPxL+YVJhqhdD1fiSek99vmWNUKqmui/4TOXf06SjuMgPgL\nOdp/e2+unwOw+TfdQ/Vu1736IRuWKgLxXOXoOHq2RCZpMgfol2wOFdWSeHWnOag2\nstKD9mmxUaq3wactkVQEkljo3vOgw3D829jC5BOVASxoYoiNzRQlpXrP+kj9QPt0\nZN6haQCgjejHOVpKeuUNoZTUyH+2MwpANLiaJjQcZrwt8N9bAN7WilY+f7CHwMK+\n-----END CERTIFICATE-----\n"
        trustedCertificates:
          type: array
          items:
            type: string
            example: "-----BEGIN CERTIFICATE-----\nMIIEszCCAxugAwIBAgIUK3BbY7jXBtQfSMhob3Ls9BoorbYwDQYJKoZIhvcNAQEL\nBQAwYTEjMCEGCgmSJomT8ixkAQEME2MtMGI1YzFhYTBkNzA4NjVjNGUxFTATBgNV\nBAMMDE1hbmFnZW1lbnRDQTEjMCEGA1UECgwaRUpCQ0EgQ29udGFpbmVyIFF1aWNr\nc3RhcnQwHhcNMjAwNDAxMTAyNzAwWhcNMzAwNDAxMTAyNzAwWjBhMSMwIQYKCZIm\niZPyLGQBAQwTYy0wYjVjMWFhMGQ3MDg2NWM0ZTEVMBMGA1UEAwwMTWFuYWdlbWVu\ndENBMSMwIQYDVQQKDBpFSkJDQSBDb250YWluZXIgUXVpY2tzdGFydDCCAaIwDQYJ\nKoZIhvcNAQEBBQADggGPADCCAYoCggGBAJ5UAlOGkFyyjyDfFBADJrVzce5/wvNC\nDzL8OoB5CRa22NxHZqPL6fNpqexH1alE7ko/g+vvu1BLHnjKzglVMVV880jjG/tq\ngUf9syfmRdRcgPUrF71dOTNw52ZGB23e8es7VQNYca5QH0mfjaw2AxKf4pNzScTi\nbYXw/KxuoeBHP2ybKhSCxau1k6eePUEkpzHlu33XjtTKGRklCo4lDslLtMOV0gWm\nJj2pd9v+/qY9AMio1XkqczGmnGrSRDD7fp+3WpBI2Q4ZaDZZHnzg/9TXmpBGWhwi\n5Ca5e9Cmb9WGjE8W4uICyvaBSmvsGqB2nBjLC0rBUyJxkMxaxZYxoWbegCqlnwgo\naG2OMbGq1qO/U5ArW9WppovA9y540j49CuYWgvf2pH21GzQX2uCtiHDge01exko/\np7c8/20B0rNjyvBFM9s2NOQ4wCIrLVKPClX3mpzuIGliRpnXnC6FQMrC4yNvyO7s\nB2PwzesXaBdD07AfXpYtSaHeqLZafMtqRwIDAQABo2MwYTAPBgNVHRMBAf8EBTAD\nAQH/MB8GA1UdIwQYMBaAFDhNazDk0J+AyO1zqws1XTTwCeJKMB0GA1UdDgQWBBQ4\nTWsw5NCfgMjtc6sLNV008AniSjAOBgNVHQ8BAf8EBAMCAYYwDQYJKoZIhvcNAQEL\nBQADggGBAImYiKkQfR52L2NzjuHI6y8darhBNpZSNf5Hhzv5MOs6yKJSFxh6mQFg\nRfF860AbxgxAfE8bvK2IX+W6b193ecFXAOrRc+UcEyqTg2efqp2zuCdQpnA4nopf\n+474iRkAHdlwdeI0FTE931AOCMfKaQAiEn40Xo3xB09xvMhK7ce2xkxFp90uqbyZ\nwXPRORUj5rKhCiL10jkgXmTfGGlzgQfpHxQxnwQzuAPcv31l+0YVZpDpkSP8A2ts\nmS/yGFfBylyPnGa/+mChZoI7AAKUZ0QWSTDVQLFW6RIs0ByX9zPZqQx0ncGzXH++\nmLu/33YpyjfcjFzvhFVRJCNpELTa0aCElDcD+LIiz80fFP3bxbI42ifYXbt+k/8w\nAB8Ffh1GOneWnaOl42mghNs6ve9e+PjOphYS1sQI74b0liXQdI4tmobAyPoACpgR\ncJ9DAfYtkpMQjxkV/FUM92m76WQpFnIRNQl6C5XLzWHCAVvS+MxEydtINsl4FCvw\nPDdu3P8UkA==\n-----END CERTIFICATE-----\n"

How to use functionality

Common information how to use CMPv2 certificate provider described below

General information

CMPv2 certificate provider is a part of certificate distribution infrastructure in ONAP. The main functionality of the provider is to forward Certificate Signing Requests (CSRs) created by cert-mananger (https://cert-manager.io) to CertServiceAPI.

Additional information can be found on a dedicated page: https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration.

By default CMPv2 provider is enabled.

CMPv2 Issuer

In order to be able to request a certificate via CMPv2 provider a CMPv2Issuer CRD (Customer Resource Definition) instance has to be created.

It is important to note that the attribute kind has to be set to CMPv2Issuer, all other attributes can be set as needed.

NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment.

Here is a definition of a CMPv2Issuer provided with ONAP installation:

apiVersion: certmanager.onap.org/v1
kind: CMPv2Issuer
metadata:
  name: cmpv2-issuer-onap
  namespace: onap
spec:
  url: https://oom-cert-service:8443
  healthEndpoint: actuator/health
  certEndpoint: v1/certificate
  updateEndpoint: v1/certificate-update
  caName: RA
  certSecretRef:
    name: cmpv2-issuer-secret
    certRef: cmpv2Issuer-cert.pem
    keyRef: cmpv2Issuer-key.pem
    cacertRef: cacert.pem

Certificate enrolling

In order to request a certificate a K8s Certificate CRD (Custom Resource Definition) has to be created.

It is important that in the section issuerRef following attributes have those values:

  • group: certmanager.onap.org

  • kind: CMPv2Issuer

After Certificate CRD has been placed cert manager will send a CSR (Certificate Sign Request) to CA (Certificate Authority) via CMPv2 provider. Signed certificate as well as trust anchor (CA root certificate) will be stored in the K8s secret specified in Certificate CRD (see secretName attribute).

By default certificates will be stored in PEM format. It is possible to get certificates also in JKS and P12 format - see example below - more information can be found on official cert manager page.

The following SANs types are supported: DNS names, IPs, URIs, emails.

Here is an example of a Certificate:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: certificate_name
  namespace: onap
spec:
  # The secret name to store the signed certificate
  secretName: secret_name
  # Common Name
  commonName: certissuer.onap.org
  subject:
    organizations:
      - Linux-Foundation
    countries:
      - US
    localities:
      - San-Francisco
    provinces:
      - California
    organizationalUnits:
      - ONAP
  # SANs
  dnsNames:
    - localhost
    - certissuer.onap.org
  ipAddresses:
    - "127.0.0.1"
  uris:
    - onap://cluster.local/
  emailAddresses:
    - onap@onap.org
  # The reference to the CMPv2 issuer
  issuerRef:
    group: certmanager.onap.org
    kind: CMPv2Issuer
    name: cmpv2-issuer-onap
  # Section keystores is optional and defines in which format certificates will be stored
  # If this section is omitted than only PEM format will be present in the secret
  keystores:
      jks:
        create: true
        passwordSecretRef: # Password used to encrypt the keystore
          name: certservice-key
          key: key
      pkcs12:
        create: true
        passwordSecretRef: # Password used to encrypt the keystore
          name: certservice-key
          key: key

Here is an example of generated secret containing certificates:

Name:         secret_name
Namespace:    onap
Labels:       <none>
Annotations:  cert-manager.io/alt-names: localhost,certissuer.onap.org
              cert-manager.io/certificate-name: certificate_name
              cert-manager.io/common-name: certissuer.onap.org
              cert-manager.io/ip-sans:
              cert-manager.io/issuer-group: certmanager.onap.org
              cert-manager.io/issuer-kind: CMPv2Issuer
              cert-manager.io/issuer-name: cmpv2-issuer-onap
              cert-manager.io/uri-sans:

Type:  kubernetes.io/tls

Data
====
tls.crt:         1675 bytes  <-- Certificate (PEM)
tls.key:         1679 bytes  <-- Private Key (PEM)
truststore.jks:  1265 bytes  <-- Trusted anchors (JKS)
ca.crt:          1692 bytes  <-- Trusted anchors (PEM)
keystore.jks:    3786 bytes  <-- Certificate and Private Key (JKS)
keystore.p12:    4047 bytes  <-- Certificate and Private Key (P12)

Certificate update

When the certificate already exists, but its date is close to expire or certificate data should be changed, then the certificate update scenario can be executed. It is performed automatically by cert-manager close to the expiration date or can be triggered manually. This use case requires the update endpoint configured for CMPv2Issuer CRD:

...
certEndpoint: v1/certificate
updateEndpoint: v1/certificate-update
caName: RA
...

If updateEndpoint field is not present or empty, then certEndpoint will be used (regular initial request instead of update) to get the certificate and this event will be logged. This behavior comes from releases prior to 2.4.0, when the certificate update feature was not implemented. To be able to perform the certificate update scenario, make sure the updateEndpoint is present in CMPv2Issuer CRD.

There are two possible types of requests when a certificate needs to be updated: Key Update Request (KUR) and Certification Request (CR). Certification Service internally compares the old and new certificates fields. When they are equal, KUR request is sent. If there is a difference, the type of request is CR.

There is a difference between CR and KUR in terms of the request authentication. Certificate Request uses IAK/RV mechanism, while KUR uses signature protection. The old certificate and the old private key are required to be sent in the headers of the update request.

Logging

CertService API

To see CertService console logs use:

  • Docker:

docker logs <cert-service-container-name>

e.g.
docker logs oomcert-service

  • Kubernetes:

kubectl -n onap logs <cert-service-pod-name>

e.g.
kubectl -n onap logs $(kubectl -n onap get pods | grep cert-service | awk '{print $1}')

Console logs contains logs for logging levels from DEBUG to ERROR.

CertService logs for different logging levels are available in the container:

  • Docker:

docker exec -it <cert-service-container-name> bash

e.g.
docker exec -it oomcert-service bash

  • Kubernetes:

kubectl -n onap exec -it <cert-service-pod-name> bash

e.g.
kubectl -n onap exec -it $(kubectl -n onap get pods | grep cert-service | awk '{print $1}') bash

Path to logs:

/var/log/onap/oom/certservice

Available log files:

  • audit.log - contains logs for INFO logging level

  • debug.log - contains logs for logging levels from DEBUG to ERROR

  • error.log - contains logs for ERROR logging level

User cannot change logging levels.

CMPv2 certificate provider

To see CMPv2 certificate provider console logs use :

kubectl -n onap logs <cmpv2-certificate-provider-pod-name> provider

e.g.
kubectl -n onap logs $(kubectl -n onap get pods | grep cmpv2-cert-provider | awk '{print $1}') provider

Installation

When enabling CMPv2, kubernetes/onap/resources/overrides/oom-cert-service-environment.yaml file with override values need to be used during OOM installation. CertService can be easily installed with OOM installation, simply by setting proper flag. It’s possible to also install EJBCA server for testing purposes. It also can be done by setting proper flag.

Enabling CertService

In order to install CertService during OOM deployment, global flag global.cmpv2Enabled in kubernetes/onap/resources/overrides/oom-cert-service-environment.yaml file must be set to true.

Enabling EJBCA - testing CMPV2 server

In order to install EJBCA server, global flag global.addTestingComponents in kubernetes/onap/values.yaml file or other file with override values must be set to true.

Setting this flag, will also cause CertService to load test configuration from kubernetes/platform/components/oom-cert-service/resources/test/cmpServers.json

Configuration

Configuring Cert Service

Cert Service keeps configuration of CMP Servers in file cmpServers.json.

Example cmpServers.json file:

{
  "cmpv2Servers": [
    {
      "caName": "Client",
      "url": "http://oomcert-ejbca:8080/ejbca/publicweb/cmp/cmp",
      "issuerDN": "CN=ManagementCA",
      "authentication": {
        "iak": "mypassword",
        "rv": "mypassword"
      }
    },
    {
      "caName": "RA",
      "url": "http://oomcert-ejbca:8080/ejbca/publicweb/cmp/cmpRA",
      "issuerDN": "CN=ManagementCA",
      "authentication": {
        "iak": "mypassword",
        "rv": "mypassword"
      }
    }
  ]
}

This contains list of CMP Servers, where each server has following properties:

  • caName - name of the external CA server. It’s used to match CA_NAME sent by CertService client in order to match proper configuration.

  • url - URL to CMPv2 server

  • issuerDN - Distinguished Name of the CA that will sign the certificate

  • authentication

    • iak - Initial authentication key, used to 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 HTTPS endpoint.

Next sections explain how to configure Cert Service in local (docker-compose) and OOM Deployments.

Configuring in local (docker-compose) deployment:

Before application start:

  1. Edit cmpServers.json file in certservice/compose-resources

  2. Start containers:

    make start-backend
When application is running:

  1. Find CertService docker container name.

  2. Enter container:

    docker exec -it <certservice-container-name> bash

e.g.
docker exec -it oomcert-service bash

  3. Edit cmpServers.json file:

    vim /etc/onap/oom/certservice/cmpServers.json

  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/oom/certservice/certs/root.crt --cert-type p12 --cert /etc/onap/oom/certservice/certs/certServiceServer-keystore.p12 --pass $KEYSTORE_PASSWORD

  6. Exit container:

    exit

Configuring in OOM deployment:

Before OOM installation:

Note! This must be executed before calling make all (from OOM Installation) or needs remaking OOM charts.

  1. Edit cmpServers.json file. If OOM global.addTestingComponents flag is set to:

    • true - edit kubernetes/platform/components/oom-cert-service/resources/test/cmpServers.json

    • false - edit *kubernetes/platform/components/oom-cert-service/resources/default/cmpServers.json

  2. Build and start OOM deployment

When CertService is deployed:

  1. Create file with configuration

  2. Encode your configuration to base64:

    cat <configuration_file> | base64

  3. Edit secret:

    kubectl -n onap edit secret <cmp-servers-secret-name>

e.g.
kubectl -n onap edit secret oom-cert-service-secret

  4. Replace value for cmpServers.json with your base64 encoded configuration. For example:

apiVersion: v1
data:
  cmpServers.json: <HERE_PLACE_YOUR_BASE64_ENCODED_CONFIG>
kind: Secret
metadata:
  creationTimestamp: "2020-04-21T16:30:29Z"
  name: oom-cert-service-secret
  namespace: default
  resourceVersion: "33892990"
  selfLink: /api/v1/namespaces/default/secrets/oom-cert-service-secret
  uid: 6a037526-83ed-11ea-b731-fa163e2144f6
type: Opaque

  1. Save and exit

  2. New configuration will be automatically mounted to CertService pod, but application configuration reload is needed.

  3. To reload configuration enter CertService pod:

    kubectl -n onap exec -it <cert-service-pod-name> bash

e.g.
kubectl -n onap exec -it $(kubectl -n onap get pods | grep cert-service | awk '{print $1}') bash

  4. Reload configuration:

    curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD

  5. Exit container:

    exit

Generating certificates for CertService and CMPv2 certificate provider

CertService and CMPv2 certificate provider use mutual TLS for communication. Certificates are generated during CertService installation.

Docker mode:

Certificates are mounted to containers by docker volumes:

  • CertService volumes are defined in certservice/docker-compose.yaml

All certificates are stored in certservice/certs directory. To recreate certificates go to certservice/certs directory and execute:

make clear all

This will clear existing certs and generate new ones.

ONAP OOM installation:

Certificates are stored in secrets, which are mounted to pods as volumes. For CMPv2 certificate provider, certificates are delivered in CMPv2Issuer as secrets name with corresponding keys.

Both secrets definitions are stored in kubernetes/platform/components/oom-cert-service/values.yaml as secrets: key.

During platform component deployment, certificates in secrets are generated automatically using Certificate resources from cert-manager. Their definitions are stored in kubernetes/platform/components/oom-cert-service/values.yaml as certificates: key.

Using external certificates for CertService and CMPv2 certificate provider

This section describes how to use custom, external certificates for CertService and CMPv2 certificate provider communication in OOM installation.

  1. Remove certificates: section from kubernetes/platform/components/oom-cert-service/values.yaml

  2. Prepare secret for CertService. It must be provided before OOM installation. It must contain four files:

    • keystore.jks - keystore in JKS format. Signed by some Root CA

    • keystore.p12 - same keystore in PKCS#12 format

    • truststore.jks - truststore in JKS format, containing certificates of the Root CA that signed CertService Client certificate

    • ca.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/platform/components/oom-cert-service/values.yaml file

  4. Prepare secret for CMPv2 certificate provider. It must be provided before OOM installation. It must contain three files:

    • tls.crt - certificate in CRT format. Signed by some Root CA

    • tls.key - private key in KEY format

    • ca.crt - certificate of the RootCA that signed CertService certificate in CRT format

  5. Name the secret properly - the name should match global.oom.certService.client.secret.name value from kubernetes/onap/values.yaml file

  6. Provide keystore and truststore passwords (the same for both) for CertService. It can be done in two ways:

    • by inlining them into kubernetes/platform/components/oom-cert-service/values.yaml:

      • override credentials.tls.certificatesPassword value with keystore and truststore password

    • or by providing them as secrets:

      • uncomment credentials.tls.certificatesPasswordExternalSecret value and provide keystore and truststore password

Configuring EJBCA server for testing

To instantiate an EJBCA server for testing purposes with an OOM deployment, cmpv2Enabled and cmpv2Testing have to be changed to true in oom/kubernetes/platform/values.yaml.

cmpv2Enabled has to be true to enable oom-cert-service to be instantiated and used with an external Certificate Authority to get certificates for secure communication.

If cmpv2Testing is enabled then an EJBCA test server will be instantiated in the OOM deployment as well, and will come pre-configured with a test CA to request a certificate from.

Currently the recommended mode is single-layer RA mode.

Default Values:

Name

Value

Request URL

http://ejbca:8080/ejbca/publicweb/cmp/cmpRA

Response Type

PKI Response

caMode

RA

alias

cmpRA

If you wish to configure the EJBCA server, you can find Documentation for EJBCA here: https://doc.primekey.com/ejbca/

If you want to understand how CMP works on EJBCA in more detail, you can find Details here: https://download.primekey.com/docs/EJBCA-Enterprise/6_14_0/CMP.html

Change Log

Istanbul

Version: 2.4.1

Release Date

2022-01-12

New Features

N/A

Bug Fixes

N/A

Known Issues

N/A

Security Notes

N/A

Fixed Security Issues

Vulnerability [CVE-2021-44228] Top up Apache log4j2 to 2.17.1

Known Security Issues

N/A

Known Vulnerabilities in Used Modules

N/A

Upgrade Notes

N/A

Deprecation Notes

N/A

Other

Version: 2.4.0

Release Date

2021-07-22

New Features

Add certificate update use case (support for CMPv2 messages: Key Update Request and Certification Request).

Bug Fixes

N/A

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

caMode is removed from cmpServers.json configuration file.

Deprecation Notes

CertService client is not supported since Istanbul release.

Other

Honolulu

Version: 2.3.3

Release Date

2021-01-27

New Features

N/A

Bug Fixes

Enhance CertServiceAPI response (include CMP server error messages). Fix KeyUsage extension sent to CMPv2 server

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: 2.3.2

Release Date

2020-12-28

New Features

N/A

Bug Fixes

Align Cert Service Api to RFC4210. Fix Cert Service Client CA_NAME validation. Fix Cert Service External Provider logging.

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: 2.3.1

Release Date

2020-12-02

New Features

N/A

Bug Fixes

Fix NullPointerException in CertService Client when SANs environment variable is not defined.

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: 2.3.0

Release Date

2020-12-01

New Features

  • Extended CertService by support for new SANs types - IPs, E-mails, URIs

Bug Fixes

N/A

Known Issues

CertService Client exits unsuccessfully with code 99 when SANs environment variable is not defined, because of NullPointerException

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: 2.2.0

Release Date

New Features

  • Added module oom-certservice-k8s-external-provider with following functionality:

    An external provider is a part of PKI infrastructure. It consumes CertificateRequest CRD from Cert-Manager and calls CertService API to enroll certificate from CMPv2 server.

    More information can be found on dedicated wiki page

Bug Fixes

N/A

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

Guilin

Version: 2.1.0

Release Date

New Features

  • Added module oom-certservice-post-processor with following functionality:

    • appending CMPv2 certificates to CertMan truststore

    • replacing CertMan keystore with CMPv2 keystore

Bug Fixes

N/A

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: 2.0.0

Release Date

New Features

  • The same functionality as in aaf-certservice 1.2.0

Bug Fixes

N/A

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.2.0

Release Date

New Features

  • Client creates subdirectories in given OUTPUT_PATH and place certificate into it.

Bug Fixes

N/A

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.1.0

Release Date

2020-06-29

New Features

  • Added property to CertService Client to allow selection of output certificates type (One of: PEM, JKS, P12).

Bug Fixes

  • Resolved issue where created PKCS12 certificates had jks extension.

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

Frankfurt

Version: 1.0.1

Release Date

2020-05-22

New Features

The Frankfurt Release is the first release of the Certification Service.

Bug Fixes

  • AAF-1132 - CertService Client returns exit status 5 when TLS configuration fails

Known Issues

  • PKCS12 certificates have jks extension

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

Release Date

2020-04-16

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

  • AAF-1132 - CertService Client returns exit status 5 when TLS configuration fails

  • PKCS12 certificates have jks extension

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 Change Log

OOM Certification Service Release Notes

Version: 2.4.0

Abstract

This document provides the release notes for the Istanbul release.

Summary

Certificate update use case is now available. For details go to: How to use instructions

Release Data

Project

OOM

Docker images

  • onap/org.onap.oom.platform.cert-service.oom-certservice-api:2.4.0

  • onap/org.onap.oom.platform.cert-service.oom-certservice-post-processor:2.4.0

  • onap/org.onap.oom.platform.cert-service.oom-certservice-k8s-external-provider:2.4.0

Release designation

Istanbul

New features

  • OOM-2754 Implement certificate update in CMPv2 external issuer

  • OOM-2753 Implement certificate update in CMPv2 CertService

  • OOM-2744 Remove CertService Client mechanism from ONAP

  • OOM-2649 Update contrib/ejbca to 7.x

Bug fixes

  • OOM-2771 Fix CertificateRequest resource was not found issue in CMPv2 external issuer

  • OOM-2764 Fix sonar issues in CertService

Known Issues

If Cert-Manager was down for some time and did not trigger certificate update on time, then updating an outdated certificate may require manual actions. The required actions are described in Troubleshooting section

Deliverables

Software Deliverables

Docker images mentioned in Release Date section.

Documentation Deliverables

Known Limitations, Issues and Workarounds

System Limitations

Any known system limitations.

Known Vulnerabilities

Any known vulnerabilities.

Workarounds

Any known workarounds.

Security Notes

Fixed Security Issues

None

Known Security Issues

None

Test Results

Not applicable

References

For more information on the ONAP Istanbul release, please see:

  1. ONAP Home Page

  2. ONAP Documentation

  3. ONAP Release Downloads

  4. ONAP Wiki Page

Version: 2.3.3

Abstract

This document provides the release notes for the Honolulu release.

Summary

Certification Service provides certificates signed by external CMPv2 server - such certificates are further called operators certificates. Operators certificates are meant to secure external ONAP traffic - traffic between network functions (xNFs) and ONAP.

This project was moved from Application Authorization Framework (AAF), to check previous release notes see, AAF CertService release notes .

Release Data

Project

OOM

Docker images

  • onap/org.onap.oom.platform.cert-service.oom-certservice-api:2.3.3

  • onap/org.onap.oom.platform.cert-service.oom-certservice-client:2.3.3

  • onap/org.onap.oom.platform.cert-service.oom-certservice-post-processor:2.3.3

  • onap/org.onap.oom.platform.cert-service.oom-certservice-k8s-external-provider:2.3.3

Release designation

Honolulu

New features

  • OOM-2560 Integrated CMPv2 certificate provider with Cert-Manager

    An CMPv2 certificate provider is a part of PKI infrastructure. It consumes CertificateRequest custom resource from Cert-Manager and calls CertService API to enroll certificate from CMPv2 server. During ONAP deployment, the CMPv2 certificate provider is enabled when flags cmpv2Enabled, CMPv2CertManagerIntegration and platform.enabled equals true.

    More information can be found on dedicated wiki page

  • OOM-2632 Extended CertService API and clients to correctly support SANs parameters such as: e-mails, URIs and IP addresses.

Bug fixes

  • OOM-2656 Adjusted CertService API to RFC4210 - changed MAC protection algorithm and number of iteration for such algorithm.

  • OOM-2657 Enhanced CertServiceAPI response in order to include CMP server error messages.

  • OOM-2658 Fixed KeyUsage extension sent to CMPv2 server

Known Issues

None

Deliverables

Software Deliverables

Docker images mentioned in Release Date section.

Documentation Deliverables

Known Limitations, Issues and Workarounds

System Limitations

Any known system limitations.

Known Vulnerabilities

Any known vulnerabilities.

Workarounds

Any known workarounds.

Security Notes

Fixed Security Issues

None

Known Security Issues

None

Test Results

Not applicable

References

For more information on the ONAP Honolulu release, please see:

  1. ONAP Home Page

  2. ONAP Documentation

  3. ONAP Release Downloads

  4. ONAP Wiki Page

Troubleshooting

Update an outdated certificate after Cert-Manager was down

When a certificate expires because Cert-Manager was not able to trigger the update on time, for some CMPv2 servers, e.g. EJBCA, there are manual actions required to perform the update.

Given the expired certificate status is READY=False:

  1. Edit the cert resource. It can be e.g. a small change in SANs.

  2. Use the cert-manager plugin renew command to trigger the update manually.

  3. Edit the cert again to revert the changes.

  4. Trigger the update manually.

The certificate should now be alive and updated correctly.

Indices and tables