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