...

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.

CertService's client communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.

...

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

...

REST API

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

Components description

CertService

REST API

CMPv2 server properties

CertService contains configuration of CMPv2 servers. To enroll certificate at least one CMPv2 server has to be configured. CMPv2 server configuration is read during CertService startup and runtime changes require CertService restart.

Section holds all properties which are planned to be supported by CertService for CMPv2 based server.

...

String (1-128)

...

Url to CMPv2 server; includes mandatory parts: scheme (http://) and IPv4/FQDN and optional parts: port and path (alias); e.g. http://127.0.0.1:8080/pkix or http://127.0.0.1/ejbca/publicweb/cmp/cmp

NOTE: If FQDN is given ONAP must be able to resolve it without extra manual configuration

...

Must be correct URL

Must start with http:// scheme

If port given, port from 1-65535 range

...

String (4-256)

Correct DN

...

Value from predefined set

...

String (1-256)

...

String (1-256)

Example

...

Return HTTP codes:

OpenAPI

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.

Section holds all properties which are planned to be supported by CertService for CMPv2 based server.

Example

{
   "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"
         }
      }
   ]
}

CMPv2 client

Input table for CMPv2 client

CMPv2 will get two POJOs: first with CSR, plain fields extracted from CSR (like subject DN, list of SANs, etc) and private key (in general data passed via REST API call) and second with CMPv2 server details and one String: CA name.

CMPv2 client call to CMPv2 server

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

@Test
  public void testServerWithRealUrl() throws CmpClientException {

    setValidCsrMetaValuesAndDateValues();

    csrMeta.caUrl("http://127.0.0.1/ejbca/publicweb/cmp/cmpRA");
    csrMeta.password("mypassword");

    CmpClientImpl cmpClient = new CmpClientImpl(HttpClients.createDefault());
    cmpClient.createCertificate("data", "RA", csrMeta, cert, notBefore, notAfter);
  }

  private void setValidCsrMetaValuesAndDateValues() {
    ArrayList<RDN> rdns = new ArrayList<>();
    try {
      rdns.add(new RDN("O=CommonCompany"));
    } catch (CertException e) {
      e.printStackTrace();
    }
    csrMeta = new CSRMeta(rdns);
    csrMeta.cn("CN=CommonName");
    csrMeta.san("CommonName.com");
    csrMeta.password("password");
    csrMeta.email("CommonName@cn.com");
    csrMeta.issuerCn("CN=ManagementCA");
    when(kpg.generateKeyPair()).thenReturn(keyPair);
    csrMeta.keypair();
    csrMeta.caUrl("http://127.0.0.1/ejbca/publicweb/cmp/cmp");

    try {
      notBefore =
              new SimpleDateFormat("yyyy/MM/dd HH:mm:ss").parse("2019/11/11 12:00:00");
      notAfter =
              new SimpleDateFormat("yyyy/MM/dd HH:mm:ss").parse("2020/11/11 12:00:00");
    } catch (ParseException e) {
      e.printStackTrace();
    }
  }

Usage

Docker

Run CertService as docker via following command: 

docker run -p $PORT_MAPPING --name $NAME --mount $CMPV2_SERVERS_CONFIGURATION $IMAGE_NAME
e.g.
docker run -p 8080:8080 --name aaf-certservice-api --mount type=bind,source=/<absolute_path>/cmpServers.json,target=/etc/onap/aaf/certservice/cmpServers.json nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-api:$VERSION

Kubernetes

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

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

CertService's client

CertService's client input properties

Below table presents all properties which should/can be passed to CertService's client to make a successful call to CertService to enroll certificate.

Results

As the successful result of running CertService's client (exitCode = 0) following artifacts are created:

In case of error CertService's client returns other exit codes (errorCode != 0). 

Usage

Docker

Run CertService's client as docker via following command:

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 }}",
         "issuerDN":"CN=ManagementCA",
         "caMode":"CLIENT",
         "authentication":{
            "iak":"xxx",
            "rv":"yyy"imagePullPolicy: {{ .Values.global.pullPolicy | default .Values.pullPolicy }}
         }
      }, env:
      {
      -   "caName":"TEST2",name: REQUEST_URL
         "url":"http://127.0.0.1/ejbca/publicweb/cmp/cmp",
     value: {{ .Values.global.aaf.certServiceClient.envVariables.requestURL }}
           "issuerDN":"CN=ManagementCA2",
    - name: REQUEST_TIMEOUT
      "caMode":"RA",
         "authentication":{
value: {{ .Values.global.aaf.certServiceClient.envVariables.requestTimeout}}
            - "iak":"xxx",name: OUTPUT_PATH
            "rv":"yyy"
  value: {{ .Values.certificate.outputPath }}
    }
      }
   ]
}

CMPv2 client

Input table for CMPv2 client

CMPv2 will get two POJOs and one String: first with CSR, plain fields extracted from CSR (like Common Name, Country, etc) and private key (in general data passed via REST API call) and second with CMPv2 server details and CA name

More info TBA

Currently the POC for CMPv2 client is working based on the inputs below.

...

Input Values

...

Description

...

Usage

...

csrMeta: CA Details

...

.cer file

...

used to validate response (.crt)/ certificate send from EJBCA server

...

Relevant values in Certificate Request message to EJBCA:

...

Value

...

Description

...

Information Included

...

SenderDN

IssuerDN

ProtectionAlgorithm (used for PkiProtection below)

...

CertificateRequestMessage, which includes:

SubjectDN

IssuerDN

SubjectPublicKey

...

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

@Test
    public void testServerWithRealUrl()
        throws CmpClientException {
- name: CA_NAME
              value: {{ .Values.global.aaf.certServiceClient.envVariables.caName }}
            - name: COMMON_NAME
              value: {{ .Values.certificate.commonName }}
            - name: ORGANIZATION
              value: {{ .Values.global.aaf.certServiceClient.envVariables.cmpv2Organization }}
            - name: ORGANIZATION_UNIT
              value: {{ .Values.global.aaf.certServiceClient.envVariables.cmpv2OrganizationalUnit }}
            - name: LOCATION
              value: {{ .Values.global.aaf.certServiceClient.envVariables.cmpv2Location }}
            - name: STATE
              value: {{ .Values.global.aaf.certServiceClient.envVariables.cmpv2State }}
            - name: COUNTRY
              value: {{ .Values.global.aaf.certServiceClient.envVariables.cmpv2Country }}
            - name: SANS
        setValidCsrMetaValuesAndDateValues();

      value: {{ csrMeta.externalCaUrl("http://127.0.0.1/ejbca/publicweb/cmp/cmp");
 .Values.certificate.sans }}
       csrMeta.password("mypassword");

     - name: KEYSTORE_PATH
 CmpClientImpl  cmpClient = new CmpClientImpl();
        tryvalue: {{
   .Values.global.aaf.certServiceClient.envVariables.keystorePath }}
          cmpClient.createCertRequest("data", "RA", csrMeta, cert, notBefore, notAfter);
 - name: KEYSTORE_PASSWORD
         }   catch (CAOfflineException e)value: {{ .Values.global.aaf.certServiceClient.envVariables.keystorePassword }}
            -  e.printStackTrace();name: TRUSTSTORE_PATH
        }
      value: }
{{ .Values.global.aaf.certServiceClient.envVariables.truststorePath }}
    private void setValidCsrMetaValuesAndDateValues() {
     -   ArrayList<RDN> rdns = new ArrayList<>();name: TRUSTSTORE_PASSWORD
        try {
     value:       rdns.add(new RDN("O=CommonCompany"));{{ .Values.global.aaf.certServiceClient.envVariables.truststorePassword }}
        } catch (CertException e) { volumeMounts:
            e.printStackTrace();
        - mountPath: {{ .Values.certService.outputPath }}
        csrMeta = new CSRMeta(rdns);
   name: {{ include "common.fullname"  csrMeta.cn("Node123");. }}-cmpv2-certs
      {{  csrMeta.san("CommonName.com");
end -}}
      containers:
    csrMeta.password("password");
    - name: {{ include csrMeta"common.email(name"CommonName@cn.com"); . }}
        csrMeta.issuerCn("ManagementCA");
  image: "{{ include "common.repository" .  when(kpg.generateKeyPair()).thenReturn(keyPair);}}/{{ .Values.image }}"
        csrMeta.keypair(trans);
  imagePullPolicy: {{     csrMeta.externalCaUrl("http://127.0.0.1/ejbca/publicweb/cmp/cmp");

.Values.global.pullPolicy | default .Values.pullPolicy }}
         try {resources:
            notBefore{{ =include "common.resources" Optional.ofNullable(new SimpleDateFormat("yyyy/MM/dd HH:mm:ss").parse("2019/11/11 12:00:00"));
      | indent 12 }}
          volumeMounts:
            {{- if .Values.global.cmpv2Enabled }}
        notAfter =  Optional.ofNullable(new SimpleDateFormat("yyyy/MM/dd HH:mm:ss").parse("2020/11/11 12:00:00"));
 - mountPath: /certificates/external
           } catch (ParseException e) {
name: {{ include "common.fullname" . }}-cmpv2-certs
               e.printStackTrace();readOnly: true
        }
    }

CertService's client

CertService's client properties

...

    {{ end -}}
          ...
      volumes:
        {{- if .Values.global.cmpv2Enabled }}
        - name: {{ include "common.fullname" . }}-cmpv2-certs
          emptyDir: {}
        {{ end -}}

CMPv2 server

For testing purpose EJBCA is set up. 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

...

CSR details

...

Usage

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.

Within you K8s workload add CertService's client as init container:

Make sure you pass as ENV variables all required parameters.

Mount to init container and your application container the same volume.

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

...