summaryrefslogtreecommitdiffstats
path: root/docs/sections/usage.rst
blob: 3031f36417bc99fd74b7a9a9eec9c9388ecb53dc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. Copyright 2020-2021 NOKIA

How to use functionality
=========================
Common information how to use CMPv2 certificate provider described below

General information
------------------------------

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.

CMPv2 Issuer
------------------------------

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:

.. code-block:: yaml

  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
    caName: RA
    certSecretRef:
      name: cmpv2-issuer-secret
      certRef: cmpv2Issuer-cert.pem
      keyRef: cmpv2Issuer-key.pem
      cacertRef: cacert.pem


Certificate enrolling
------------------------------

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:

- group: certmanager.onap.org

- kind: CMPv2Issuer

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*:

.. code-block:: yaml

  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:
      - onap@onap.org
    # 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:

.. code-block:: yaml

    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)