docs/sections/cmpv2-cert-provider.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 NOKIA
   4
   5 CMPv2 certificate provider
   6 ==============================
   7
   8 General information
   9 ------------------------------
  10
  11 CMPv2 certificate provider is a part of certificate distribution infrastructure in ONAP.
  12 The main functionality of the provider is to forward Certificate Signing Requests (CSRs) created by cert-mananger (https://cert-manager.io) to CertServiceAPI.
  13
  14 Additional information can be found on a dedicated page:  https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration.
  15
  16 By default CMPv2 provider is **disabled**. To enable it set following global helm value:
  17
  18 - CMPv2CertManagerIntegration = true
  19
  20 CMPv2 Issuer
  21 ------------------------------
  22
  23 In order to be able to request a certificate via CMPv2 provider a *CMPv2Issuer* CRD (Customer Resource Definition) instance has to be created.
  24
  25 It is important to note that the attribute *kind* has to be set to **CMPv2Issuer**, all other attributes can be set as needed.
  26
  27 **NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment.**
  28
  29 Here is a definition of a *CMPv2Issuer* provided with ONAP installation:
  30
  31 .. code-block:: yaml
  32
  33   apiVersion: certmanager.onap.org/v1
  34   kind: CMPv2Issuer
  35   metadata:
  36     name: cmpv2-issuer-onap
  37     namespace: onap
  38   spec:
  39     url: https://oom-cert-service:8443
  40     healthEndpoint: actuator/health
  41     certEndpoint: v1/certificate
  42     caName: RA
  43     certSecretRef:
  44       name: cmpv2-issuer-secret
  45       certRef: cmpv2Issuer-cert.pem
  46       keyRef: cmpv2Issuer-key.pem
  47       cacertRef: cacert.pem
  48
  49
  50 Certificate enrolling
  51 ------------------------------
  52
  53 In order to request a certificate a K8s *Certificate* CRD (Custom Resource Definition) has to be created.
  54
  55 It is important that in the section issuerRef following attributes have those values:
  56
  57 - group: certmanager.onap.org
  58
  59 - kind: CMPv2Issuer
  60
  61 After *Certificate* CRD has been placed cert manager will send a *CSR* (Certificate Sign Request) to CA (Certificate Authority) via CMPv2 provider.
  62 Signed certificate as well as trust anchor (CA root certificate) will be stored in the K8s *secret* specified in *Certificate* CRD (see secretName attribute).
  63
  64 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.
  65
  66 The following SANs types are supported: DNS names, IPs, URIs, emails.
  67
  68 Here is an example of a *Certificate*:
  69
  70 .. code-block:: yaml
  71
  72   apiVersion: cert-manager.io/v1
  73   kind: Certificate
  74   metadata:
  75     name: certificate_name
  76     namespace: onap
  77   spec:
  78     # The secret name to store the signed certificate
  79     secretName: secret_name
  80     # Common Name
  81     commonName: certissuer.onap.org
  82     subject:
  83       organizations:
  84         - Linux-Foundation
  85       countries:
  86         - US
  87       localities:
  88         - San-Francisco
  89       provinces:
  90         - California
  91       organizationalUnits:
  92         - ONAP
  93     # SANs
  94     dnsNames:
  95       - localhost
  96       - certissuer.onap.org
  97     ipAddresses:
  98       - "127.0.0.1"
  99     uris:
 100       - onap://cluster.local/
 101     emailAddresses:
 102       - onap@onap.org
 103     # The reference to the CMPv2 issuer
 104     issuerRef:
 105       group: certmanager.onap.org
 106       kind: CMPv2Issuer
 107       name: cmpv2-issuer-onap
 108     # Section keystores is optional and defines in which format certificates will be stored
 109     # If this section is omitted than only PEM format will be present in the secret
 110     keystores:
 111         jks:
 112           create: true
 113           passwordSecretRef: # Password used to encrypt the keystore
 114             name: certservice-key
 115             key: key
 116         pkcs12:
 117           create: true
 118           passwordSecretRef: # Password used to encrypt the keystore
 119             name: certservice-key
 120             key: key
 121
 122
 123 Here is an example of generated *secret* containing certificates:
 124
 125 .. code-block:: yaml
 126
 127     Name:         secret_name
 128     Namespace:    onap
 129     Labels:       <none>
 130     Annotations:  cert-manager.io/alt-names: localhost,certissuer.onap.org
 131                   cert-manager.io/certificate-name: certificate_name
 132                   cert-manager.io/common-name: certissuer.onap.org
 133                   cert-manager.io/ip-sans:
 134                   cert-manager.io/issuer-group: certmanager.onap.org
 135                   cert-manager.io/issuer-kind: CMPv2Issuer
 136                   cert-manager.io/issuer-name: cmpv2-issuer-onap
 137                   cert-manager.io/uri-sans:
 138
 139     Type:  kubernetes.io/tls
 140
 141     Data
 142     ====
 143     tls.crt:         1675 bytes  <-- Certificate (PEM)
 144     tls.key:         1679 bytes  <-- Private Key (PEM)
 145     truststore.jks:  1265 bytes  <-- Trusted anchors (JKS)
 146     ca.crt:          1692 bytes  <-- Trusted anchors (PEM)
 147     keystore.jks:    3786 bytes  <-- Certificate and Private Key (JKS)
 148     keystore.p12:    4047 bytes  <-- Certificate and Private Key (P12)
 149
 150
 151