How to use functionality
Common information how to use CMPv2 certificate provider described below
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.
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
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:
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: - email@example.com # 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)
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.