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.