Overview

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.

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

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.

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.

Components description

CertService

REST API

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.

Return HTTP codes:

OpenAPI

Swagger will be added here

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

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

CMPv2 client

Input table for CMPv2 client

CMPv2 will get two POJOs and one String: 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 CA name

Input value	Input type	Description	Usage
CsrModel	Object	POJO which transfers sent CSR, plain fields extracted from CSR (like Common Name, Country, etc)
CsrModel:: csr	org.bouncycastle.pkcs.PKCS10CertificationRequest	Certificate Signing Request received via REST API
CsrModel:: subjectDN	org.bouncycastle.asn1.x500.X500Name	SubjectDN retrieved from sent CSR
CsrModel:: privateKey	java.security.PrivateKey	Private key received via REST API
CsrModel:: publicKey	java.security.PublicKey	Public key retrieved from sent CSR
CsrModel:: sans	List of Strings	Subject Alterative Names retrieved from sent CSR
CsrModel::	Others (plain data extracted from sent CSR)  if needed
CMPv2ServerDetails	Object	POJO which transfers CMPv2 server properties
CMPv2ServerDetails:: CA name	String	CA name as configured in CMPv2 server properties
CMPv2ServerDetails:: URL	URL or String	URL to CMPv2 server as configured in CMPv2 server details
CMPv2ServerDetails:: IssuerDN	org.bouncycastle.asn1.x500.X500Name	Issuer DN as configured in CMPv2 server details
CMPv2ServerDetails:: CA mode	ENUM	CA mode as configured in CMPv2 server details
CMPv2ServerDetails:: IAK	String	IAK as configured in CMPv2 server details
CMPv2ServerDetails:: RV	String	RV as configured in CMPv2 server details
CA name	String	CA name received via REST API

Return values from CMPv2 client

  CMPv2 client returns:

either 3 values:

java.security.cert.X509Certificate endCertificate

List <java.security.cert.X509Certificate> extraCerts

List <java.security.cert.X509Certificate> caPubs

Or 2 values:

List <java.security.cert.X509Certificate> certificateChain

List <java.security.cert.X509Certificate> trustedCerts

CMPv2 client POC

TBD

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

Relevant values in Certificate Request message to EJBCA:

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/cmpSubRA");
    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: TBA

docker run -p 8080:8080 --name cert-service $IMAGE_NAME

Kubernetes

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

CertService's client

CertService's client input properties

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

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

...                                 # WARNING - work in progress so still can change
kind: Deployment
metadata:
  ...
spec:
...
  template:
  ...
    spec:
      initContainers:
        - name: cert-service-client
          image: {{ .Values.global.csClientRepository }}/{{ .Values.global.csClientImage }}
          imagePullPolicy: {{ .Values.global.pullPolicy | default .Values.pullPolicy }}
          env:
            - name: REQUEST_URL
              value: {{ .Values.certService.url }}
            - name: REQUEST_TIMEOUT
              value: {{ .Values.certService.timeout }}
            - name: OUTPUT_PATH
              value: {{ .Values.certService.outputPath }}
            - name: CA_NAME
              value: {{ .Values.global.certService.caName }}
            - name: COMMON_NAME
              value: {{ .Values.certService.commonName }}
            - name: ORGANIZATION
              value: {{ .Values.global.certService.organization }}
            - name: ORGANIZATION_UNIT
              value: {{ .Values.global.certService.organizationUnit }}
            - name: LOCATION
              value: {{ .Values.global.certService.location }}
            - name: STATE
              value: {{ .Values.global.certService.state }}
            - name: COUNTRY
              value: {{ .Values.global.certService.country }}
            - name: SANS
              value: {{ .Values.certService.sans }}
          volumeMounts:
            - mountPath: {{ .Values.certService.outputPath }}
              name: {{ include "common.fullname" . }}-cmpv2-certs
      containers:
        - name: {{ include "common.name" . }}
          image: "{{ include "common.repository" . }}/{{ .Values.image }}"
          imagePullPolicy: {{ .Values.global.pullPolicy | default .Values.pullPolicy }}
          resources:
{{ include "common.resources" . | indent 12 }}
          volumeMounts:
            - mountPath: /certificates/external
              name: {{ include "common.fullname" . }}-cmpv2-certs
              readOnly: true
          ...
      volumes:
        - name: {{ include "common.fullname" . }}-cmpv2-certs
          emptyDir: {}

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