1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. Copyright 2020-2021 NOKIA
5 .. _cmpv2_cert_provider:
7 How to use functionality
8 =========================
9 Common information how to use CMPv2 certificate provider described below
12 ------------------------------
14 CMPv2 certificate provider is a part of certificate distribution infrastructure in ONAP.
15 The main functionality of the provider is to forward Certificate Signing Requests (CSRs) created by cert-mananger (https://cert-manager.io) to CertServiceAPI.
17 Additional information can be found on a dedicated page: https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration.
19 By default CMPv2 provider is enabled.
22 ------------------------------
24 In order to be able to request a certificate via CMPv2 provider a *CMPv2Issuer* CRD (Customer Resource Definition) instance has to be created.
26 It is important to note that the attribute *kind* has to be set to **CMPv2Issuer**, all other attributes can be set as needed.
28 **NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment.**
30 Here is a definition of a *CMPv2Issuer* provided with ONAP installation:
34 apiVersion: certmanager.onap.org/v1
37 name: cmpv2-issuer-onap
40 url: https://oom-cert-service:8443
41 healthEndpoint: actuator/health
42 certEndpoint: v1/certificate
43 updateEndpoint: v1/certificate-update
46 name: cmpv2-issuer-secret
47 certRef: cmpv2Issuer-cert.pem
48 keyRef: cmpv2Issuer-key.pem
53 ------------------------------
55 In order to request a certificate a K8s *Certificate* CRD (Custom Resource Definition) has to be created.
57 It is important that in the section issuerRef following attributes have those values:
59 - group: certmanager.onap.org
63 After *Certificate* CRD has been placed cert manager will send a *CSR* (Certificate Sign Request) to CA (Certificate Authority) via CMPv2 provider.
64 Signed certificate as well as trust anchor (CA root certificate) will be stored in the K8s *secret* specified in *Certificate* CRD (see secretName attribute).
66 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.
68 The following SANs types are supported: DNS names, IPs, URIs, emails.
70 Here is an example of a *Certificate*:
74 apiVersion: cert-manager.io/v1
77 name: certificate_name
80 # The secret name to store the signed certificate
81 secretName: secret_name
83 commonName: certissuer.onap.org
102 - onap://cluster.local/
105 # The reference to the CMPv2 issuer
107 group: certmanager.onap.org
109 name: cmpv2-issuer-onap
110 # Section keystores is optional and defines in which format certificates will be stored
111 # If this section is omitted than only PEM format will be present in the secret
115 passwordSecretRef: # Password used to encrypt the keystore
116 name: certservice-key
120 passwordSecretRef: # Password used to encrypt the keystore
121 name: certservice-key
125 Here is an example of generated *secret* containing certificates:
132 Annotations: cert-manager.io/alt-names: localhost,certissuer.onap.org
133 cert-manager.io/certificate-name: certificate_name
134 cert-manager.io/common-name: certissuer.onap.org
135 cert-manager.io/ip-sans:
136 cert-manager.io/issuer-group: certmanager.onap.org
137 cert-manager.io/issuer-kind: CMPv2Issuer
138 cert-manager.io/issuer-name: cmpv2-issuer-onap
139 cert-manager.io/uri-sans:
141 Type: kubernetes.io/tls
145 tls.crt: 1675 bytes <-- Certificate (PEM)
146 tls.key: 1679 bytes <-- Private Key (PEM)
147 truststore.jks: 1265 bytes <-- Trusted anchors (JKS)
148 ca.crt: 1692 bytes <-- Trusted anchors (PEM)
149 keystore.jks: 3786 bytes <-- Certificate and Private Key (JKS)
150 keystore.p12: 4047 bytes <-- Certificate and Private Key (P12)
152 .. _how_to_use_certificate_update:
155 ------------------------------
157 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.
158 It is performed automatically by cert-manager close to the expiration date or can be triggered manually.
159 This use case requires the update endpoint configured for *CMPv2Issuer* CRD:
164 certEndpoint: v1/certificate
165 updateEndpoint: v1/certificate-update
169 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.
170 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,
171 make sure the updateEndpoint is present in *CMPv2Issuer* CRD.
173 There are two possible types of requests when a certificate needs to be updated: Key Update Request (KUR) and Certification Request (CR).
174 Certification Service internally compares the old and new certificates fields. When they are equal, KUR request is sent.
175 If there is a difference, the type of request is CR.
177 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.
178 The old certificate and the old private key are required to be sent in the headers of the update request.