docs/sections/usage.rst

   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
   4
   5 .. _cmpv2_cert_provider:
   6
   7 How to use functionality
   8 =========================
   9 Common information how to use CMPv2 certificate provider described below
  10
  11 General information
  12 ------------------------------
  13
  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.
  16
  17 Additional information can be found on a dedicated page:  https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration.
  18
  19 By default CMPv2 provider is enabled.
  20
  21 CMPv2 Issuer
  22 ------------------------------
  23
  24 In order to be able to request a certificate via CMPv2 provider a *CMPv2Issuer* CRD (Customer Resource Definition) instance has to be created.
  25
  26 It is important to note that the attribute *kind* has to be set to **CMPv2Issuer**, all other attributes can be set as needed.
  27
  28 **NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment.**
  29
  30 Here is a definition of a *CMPv2Issuer* provided with ONAP installation:
  31
  32 .. code-block:: yaml
  33
  34   apiVersion: certmanager.onap.org/v1
  35   kind: CMPv2Issuer
  36   metadata:
  37     name: cmpv2-issuer-onap
  38     namespace: onap
  39   spec:
  40     url: https://oom-cert-service:8443
  41     healthEndpoint: actuator/health
  42     certEndpoint: v1/certificate
  43     updateEndpoint: v1/certificate-update
  44     caName: RA
  45     certSecretRef:
  46       name: cmpv2-issuer-secret
  47       certRef: cmpv2Issuer-cert.pem
  48       keyRef: cmpv2Issuer-key.pem
  49       cacertRef: cacert.pem
  50
  51
  52 Certificate enrolling
  53 ------------------------------
  54
  55 In order to request a certificate a K8s *Certificate* CRD (Custom Resource Definition) has to be created.
  56
  57 It is important that in the section issuerRef following attributes have those values:
  58
  59 - group: certmanager.onap.org
  60
  61 - kind: CMPv2Issuer
  62
  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).
  65
  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.
  67
  68 The following SANs types are supported: DNS names, IPs, URIs, emails.
  69
  70 Here is an example of a *Certificate*:
  71
  72 .. code-block:: yaml
  73
  74   apiVersion: cert-manager.io/v1
  75   kind: Certificate
  76   metadata:
  77     name: certificate_name
  78     namespace: onap
  79   spec:
  80     # The secret name to store the signed certificate
  81     secretName: secret_name
  82     # Common Name
  83     commonName: certissuer.onap.org
  84     subject:
  85       organizations:
  86         - Linux-Foundation
  87       countries:
  88         - US
  89       localities:
  90         - San-Francisco
  91       provinces:
  92         - California
  93       organizationalUnits:
  94         - ONAP
  95     # SANs
  96     dnsNames:
  97       - localhost
  98       - certissuer.onap.org
  99     ipAddresses:
 100       - "127.0.0.1"
 101     uris:
 102       - onap://cluster.local/
 103     emailAddresses:
 104       - onap@onap.org
 105     # The reference to the CMPv2 issuer
 106     issuerRef:
 107       group: certmanager.onap.org
 108       kind: CMPv2Issuer
 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
 112     keystores:
 113         jks:
 114           create: true
 115           passwordSecretRef: # Password used to encrypt the keystore
 116             name: certservice-key
 117             key: key
 118         pkcs12:
 119           create: true
 120           passwordSecretRef: # Password used to encrypt the keystore
 121             name: certservice-key
 122             key: key
 123
 124
 125 Here is an example of generated *secret* containing certificates:
 126
 127 .. code-block:: yaml
 128
 129     Name:         secret_name
 130     Namespace:    onap
 131     Labels:       <none>
 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:
 140
 141     Type:  kubernetes.io/tls
 142
 143     Data
 144     ====
 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)
 151
 152 .. _how_to_use_certificate_update:
 153
 154 Certificate update
 155 ------------------------------
 156
 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:
 160
 161 .. code-block:: yaml
 162
 163   ...
 164   certEndpoint: v1/certificate
 165   updateEndpoint: v1/certificate-update
 166   caName: RA
 167   ...
 168
 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.
 172
 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.
 176
 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.