...

The goal of this requirement is to implement new micro-service called CertService which will request certificates signed by external Certificate Authority (CA) using CMP over HTTP protocol. 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.

...

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.

Context view

Architecture sketch

Simplified certificate enrollment flow

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.

...

Method	Endpoint	Parameter				Returned values
		Name	Is required?	Transfer method	Description	Name	Always returned?	Transfer method	Description
GET	/v1/certificate/{caName}	CA name	Yes	Path parameter	Name of Certificate Authority which should sign sent CSR. Must match CertService's CMPv2 servers configuration.	Error message	No, only if error occurred on server side	Body (JSON)	Verbose information what wrong happened on server side.
		Base64 encoded CSR (Certificate Signing Request) in PEM format	Yes	Header	Certificate Signing Request for given component	Certificate chain	No, only in success case.	Body (JSON)	Base64 encoded signed certificate with whole certificate chain (intermediate CA certificates) in PEM format. Signed certificate should be returned first and then all intermediate certificates in following order: singer of previous certificate till certificate which is signed by root CA. All certificates are in PEM format.
		Base64 encoded private key in PEM format	Yes	Header	Private key. Needed to create proof of possession (PoP)	Trusted certificates	No, only in success case.	Body (JSON)	Base64 encoded list of trusted certificates in PEM format. In other words list of root CAs which should be treated as trust anchors. Must contain root CA which was used to sign certificate and may contain other root CAs. Order doesn't matter. All certificates are in PEM format.

...

OpenAPI

Swagger will be added here

CMPv2 server properties

...

CMPv2 server properties

CertService contains configuration of CMPv2 servers. To enroll certificate at least one CMPv2 server has to be configured. CMPv2 servers configuration is read during CertService startup and to take runtime changes into account CertService's refresh configuration endpoint has to be called.

...

Example

#{
WARNING - work in progress so still can change
{
   "cmpv2Servers":[
      {
         "caName":"TEST",
         "url":"http://127.0.0.1/ejbca/publicweb/cmp/cmp",
         "issuerDN":"CN=ManagementCA",
         "caMode":"CLIENT",
         "authentication":{
            "iak":"xxx",
            "rv":"yyy"
         }
      },
      {
         "caName":"TEST2",
         "url":"http://127.0.0.1/ejbca/publicweb/cmp/cmpRA",
         "issuerDN":"CN=ManagementCA2",
         "caMode":"RA",
         "authentication":{
            "iak":"xxx",
            "rv":"yyy"
         }
      }
   ]
}

...

Relevant values in Initialization Request (IR) message sent to CMPv2 server:

Return values from CMPv2 client

Following table represents return values from CMPv2 client.

Test code for running cmpv2 client against EJBCA server through unit test

...

For Kubernetes helm chart is provided. Just overwrite needed values and deploy helm chart using following command: TBA  

helm install --name $NAME --namespace onap $PATH_TO_HELM_CHART --values $PATH_TO_OVERRIDDEN_VALUES

...

Results

...

...

Run CertService's client as docker via following command: TBA

TEST

Kuberenetes

Cause ONAP is deployed in K8s, CertService's client will be delivered as independent container and should run as init container for end component. Both init container and end component must mount the same volume (persistent or ephemeral) to transfer generated artifacts.

Example

Volume to transfer generated artifacts should be mounted to application container (lines 46-49). Within K8s workload, CertService's client as init container should be added (lines 10-13). All needed ENV variables should be passed to CertService's client (lines 14-36). CertService's client should mount the same volume as application container (lines 37-39). Volume to transfer generated artifacts can be an emptyDir type (lines 51-53).

...

...

AAFCERT_CLIENT_IMAGE=onap/org.onap.aaf.certservice.aaf-certservice-client
DOCKER_ENV_FILE= <path to envfile>
NETWORK_CERT_SERVICE= <docker network of cert service>
 
docker run --name aaf-certservice-client --env-file $DOCKER_ENV_FILE --network $NETWORK_CERT_SERVICE $AAFCERT_CLIENT_IMAGE

Kuberenetes

Cause ONAP is deployed in K8s, CertService's client will be delivered as independent container and should run as init container for end component. Both init container and end component must mount the same volume (persistent or ephemeral) to transfer generated artifacts.

Example

Volume to transfer generated artifacts should be mounted to application container (lines 57-61). Within K8s workload, CertService's client as init container should be added conditionally (lines 10-14 and 49). All needed ENV variables should be passed to CertService's client (lines 15-45). CertService's client should mount the same volume as application container (lines 46-48). Volume to transfer generated artifacts can be an emptyDir type (lines 64-67).

...                                 # WARNING - work in progress so still can change
kind: Deployment
metadata:
  ...
spec:
...
  template:
  ...
    spec:
      {{- if .Values.global.cmpv2Enabled }}
      initContainers:
        - name: cert-service-client
          image: {{ .Values.global.repository }}/{{ .Values.global.aaf.certServiceClient.image }}
          imagePullPolicy: {{ .Values.global.pullPolicy | default .Values.pullPolicy }}
          env:
            - name: REQUEST_URL
              value: {{ .Values.global.aaf.certServiceClient.envVariables.requestURL }}
            - name: REQUEST_TIMEOUT
              value: {{ .Values.global.aaf.certServiceClient.envVariables.requestTimeout}}
            - name: OUTPUT_PATH
              value: {{ .Values.certificate.outputPath }}
            - name: CA_NAME
              value: {{ .Values.global.aaf.certServiceClient.envVariables.caName }}
            - name: COMMON_NAME
              value: {{ .Values.certificate.commonName }}
            - name: ORGANIZATION
  # WARNING - work in progress so still can change kind: Deployment metadatavalue: {{  .Values.global.
spec:
aaf.certServiceClient.envVariables.cmpv2Organization }}
   template:     ...    - specname: ORGANIZATION_UNIT
     initContainers:         value: {{ .Values.global.aaf.certServiceClient.envVariables.cmpv2OrganizationalUnit }}
- name: cert-service-client          - imagename: {{ .Values.global.csClientRepository }}/{{ .Values.global.csClientImage }}LOCATION
              imagePullPolicyvalue: {{ .Values.global.pullPolicy | default .Values.pullPolicy.aaf.certServiceClient.envVariables.cmpv2Location }}
      
   env:             - name: REQUEST_URLSTATE
              value: {{ .Values.certService.urlglobal.aaf.certServiceClient.envVariables.cmpv2State }}
            - name: REQUEST_TIMEOUTCOUNTRY
              value: {{ .Values.certService.timeoutglobal.aaf.certServiceClient.envVariables.cmpv2Country }}
            - name: OUTPUT_PATHSANS
              value: {{ .Values.certServicecertificate.outputPathsans }}
            - name: CAKEYSTORE_NAMEPATH
              value: {{ .Values.global.aaf.certServicecertServiceClient.envVariables.caNamekeystorePath }}
            - name: COMMONKEYSTORE_NAMEPASSWORD
              value: {{ .Values.certService.commonName.global.aaf.certServiceClient.envVariables.keystorePassword }}
            - name: ORGANIZATIONTRUSTSTORE_PATH
              value: {{ .Values.global.aaf.certServicecertServiceClient.envVariables.organizationtruststorePath }}
            - name: ORGANIZATIONTRUSTSTORE_UNITPASSWORD
              value: {{ .Values.global.certService.organizationUnitaaf.certServiceClient.envVariables.truststorePassword }}
            - namevolumeMounts:
LOCATION            -   valuemountPath: {{ .Values.global.certService.locationoutputPath }}
             - name: STATE{{ include "common.fullname"   . }}-cmpv2-certs
         value: {{ .Values.global.certService.state end -}}
      containers:
        - name: COUNTRY {{ include "common.name" . }}
          image: "{{ include  value: "common.repository" . }}/{{ .Values.global.certService.countryimage }}"
          imagePullPolicy:  - name: SANS
 {{ .Values.global.pullPolicy | default .Values.pullPolicy }}
            value: {{ .Values.certService.sans }}
resources:
          volumeMounts:  {{ include "common.resources" . | indent 12 }}
   - mountPath: {{ .Values.certService.outputPath }}   volumeMounts:
           name: {{- includeif "common.fullname" ..Values.global.cmpv2Enabled }}-cmpv2-certs
      containers:         - namemountPath: {{ include "common.name" . }}/certificates/external
              imagename: "{{ include "common.repository" . }}/{{ .Values.imagefullname" . }}"-cmpv2-certs
          imagePullPolicy: {{ .Values.global.pullPolicy | default .Values.pullPolicy }}readOnly: true
           resources: {{ include "common.resources" . | indent 12 }}end -}}
           ...
  volumeMounts:    volumes:
        {{- mountPath: /certificates/external
 if .Values.global.cmpv2Enabled }}
         -   name: {{ include "common.fullname" . }}-cmpv2-certs
              readOnlyemptyDir: true{}
        {{ end -}}

CMPv2 server

For testing purpose EJBCA is set up.

...

CMPv2 server

For testing purpose EJBCA is set up. It is configured with 2 layer CA hierarchy (root CA and intermediate CA).

EJBCA Setup Script

...

It is configured with 1 layer CA hierarchy (root CA only).

EJBCA Setup Script

Future enhancements

1. Keep CMPv2 server details in e.g. ESR
2. Support configurable output type to output artifacts in desired format: JKS, P12 or PEM - implemented in Guilin release
   
3. Certificate update implementation on server and client side
   1. Add to CertService new endpoint to call certificate update in CMPv2 server
   2. Adjust CertService's client to work as sidecar, not init container

      1. CerService's client adjusted to run in loop (e.g. keep watermark and read it in every run)

         1. If certificate is not enrolled - request certificate
         2. If certificate is already enrolled - request certificate update
   3. Application adjusted to reload keystore/truststore in the runtime or if such is not possible, adjusted to restart itself or inform K8s via probes mechanism that restart is required
4. Adjust logging to ONAP guidance
5. CMPv2 over HTTPS support