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

Gliffy

macroId	6a3d83fc-f517-42f8-ae64-3ab4157d9b07
name	cmpv2_context_view
pagePin	4

Architecture sketch

Gliffy

macroId	992e69e0-eba0-4ee9-a266-ea3ee9c09ae1
name	certservice_high_level
pagePin	49

Simplified certificate enrollment flow

Gliffy

size	M
name	certService_cert_enrollment_flow
pagePin	34

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.

...

HTTP code	Description
200 (OK)	Everything is ok. Certificate chain and trusted certificates returned
400 (Bad Request)	Incorrect/missing CSR and/or private key
401 (Unauthorized)	Missing client certificate or presented certificate is not trusted
404 (Not found)	Invalid CA name in REST API call or wrong endpoint called
500 (Internal Server Error)	In case of exception on server side.

OpenAPI

Info
The best way to open Swagger documentation is to open it in new tab and, when asked, open it in your favorite browser.

View file

name	CertServiceApi.html
height	250

...

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.

...

Parameter name	Required	Syntax	Description	Validation rules
CA Name	Yes	String (1-128)	The CA name should include the name of the external CA server and the issuerDN, which is the distinguished name of the CA on the external CA server that will sign our certificate.	String (1-128)	URL	Yes	Should be URL safe as it is used by clients as path parameter in REST calls
URL	Yes	Schema + IPv4/FQDN + port + path	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
Issuer DN	Yes	String (4-256)	Distinguished Name of the CA that will sign the certificate on the CMPv2 server side. When creating an end entity on the external CA server for client mode this IssuerDN will be passed through as the ca to sign for that user.	String (4-256) Correct DN
CA Mode	Yes	Enum (CLIENT\|RA)	Issuer mode (either Registration Authority (RA) or client mode)	Value from predefined set
Authentication data::IAK	Yes	String (1-256)	Initial authentication key, used, together with RV, to authenticate request in CMPv2 server	String (1-256)
Authentication data::RV	Yes	String (1-256)	Reference value, used, together with IAK, to authenticate request in CMPv2 server	String (1-256)

Example

Code Block

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

...

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

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

...

Parameter name	ENV variable name	Required	Default	Syntax	Validation rules	Description	Origin
Url	REQUEST_URL	No	http(s)https://aaf-cert-service-service:80808443/v1/certificate/	URL	Syntax column	URL to Cert Service. Default value will be aligned with ONAP K8s deployment (Cert Service's K8s service name and port). Needs to be changed for plain docker deployment.	Application helm chart
Timeout	REQUEST_TIMEOUT	No	30000	Int (0-120000)	Syntax column	Timeout for REST API calls. In miliseconds. A timeout value of zero is interpreted as an infinite timeout.	Application helm chart
Path	OUTPUT_PATH	Yes		String (1-256)	Syntax column Path is valid *inx path	Path where client will output generated keystore and truststore. Normally this path should be on a volume which is used to transfer keystore and truststore between CertService's client and end component	Application helm chart
CA name	CA_NAME	Yes		String (1-128)	Syntax column Must contain only alphanumeric characters	Name of CA which will enroll certificate. Must be same as configured on server side. Used in REST API calls	OOM global value
Common Name	COMMON_NAME	Yes		String (1-256)	Syntax column CN can't contain (special characters (?, $, % and so on), IP addresses, Port numbers, or "http:// or https://")	Common name for which certificate from CMPv2 server should be issued	Application helm chart
Organization	ORGANIZATION	Yes		String (1-256)	Syntax column Organization can't contain invalid characters from list "! @ # $ % ^ * ( ) ~ ? > < / \" (without "")	Organization for which certificate from CMPv2 server should be issued	OOM global value
Organization Unit	ORGANIZATION_UNIT	No	Not available in generated certificate	String (0-256)	Syntax column	Organization unit for which certificate from CMPv2 server should be issued	OOM global value
Location	LOCATION	No	Not available in generated certificate	String (0-256)	Syntax column	Location for which certificate from CMPv2 server should be issued	OOM global value
State	STATE	Yes		String (1-256)	Syntax column	State for which certificate from CMPv2 server should be issued	OOM global value
Country	COUNTRY	Yes		String(2)	C must be a 2-character ISO format country code	Country for which certificate from CMPv2 server should be issued	OOM global value
SANs	SANS	No	Not available in generated certificate	String (0-2048) SAN1[:SAN2]	Syntax column	Subject Alternative Names (SANs) for which certificate from CMPv2 server should be issued. Colon is used as delimiter, e.g. example.com:example.pl. The only supported type of SANs is DNS domain name. NOTE: starting Honolulu release comma is used as delimiter, e.g. example.com,example.pl.	Application helm chart

Results

...

Name	Description
keystore.jks	Keystore with certificate chain saved under 'certificate' alias. Protected by random generated password. keystoreKeystore in PKCS#12 format.
keystore.pass	File with password to keystore. Password should be min. 16 chars long and should contain only alphanumeric characters and special characters like Underscore (_), Dollar ($) and Pound (#). Password should be random.
truststore.jks	Truststore with all trusted certificates. Protected by random generated password. Every trusted certificate is saved under alias with 'trusted-certificate-' prefix. Truststore in PKCS#12 format.
truststore.pass	File with password to truststore. Password should be min. 16 chars long and should contain only alphanumeric characters and special characters like Underscore (_), Dollar ($) and Pound (#). Password should be random.

...

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

Code Block
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

...

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

...

linenumbers	true

46-48). Volume to transfer generated artifacts can be an emptyDir type (lines 64-67).

Code Block

linenumbers	true

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

View file

name	ejbcaSetup.sh
height	250

Future enhancements

Keep CMPv2 server details in e.g. ESR
~~Support configurable output type to output artifacts in desired format: JKS, P12 or PEM~~ - implemented in Guilin release
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
Adjust logging to ONAP guidance
CMPv2 over HTTPS support

Versions Compared

Old Version 85

New Version Current

Key

Context view

Architecture sketch

Simplified certificate enrollment flow

Security considerations

OpenAPI

Example

Results

Kuberenetes

Example

Kuberenetes

Example

CMPv2 server

CMPv2 server

EJBCA Setup Script

EJBCA Setup Script

Future enhancements

Page Comparison

Versions Compared

Old Version 85

New Version Current

Key

Context view

Architecture sketch

Simplified certificate enrollment flow

Security considerations

OpenAPI

Example

Results

Kuberenetes

Example

Kuberenetes

Example

CMPv2 server

CMPv2 server

EJBCA Setup Script

EJBCA Setup Script

Future enhancements