docs/sections/tls_enablement.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 TLS Support
   5 ===========
   6
   7 To comply with ONAP security requirement, all services exposing external API required TLS support using AAF generated certificates. DCAE Platform was updated in R3 to enable certificate distribution mechanism for services needing TLS support. For R6, we have moved from generating certificates manually to retrieving certificates from AAF at deployment time.
   8
   9 Solution overview
  10 -----------------
  11 1. Certificate setup:
  12
  13     AAF requires setting up certificate details in AAF manually before a certificate is generated.
  14     This step is currently done using a test AAF instance in POD25.
  15     Required namespace,  DCAE identity (dcae@dcae.onap.org), roles and Subject Alternative Names for all components are set in the test instance.
  16     We use a single certificate for all DCAE components, with a long list of Subject Alternative Names (SANs).
  17
  18     Current SAN listing::
  19
  20         bbs-event-processor, bbs-event-processor.onap, bbs-event-processor.onap.svc.cluster.local, config-binding-service, config-binding-service.onap, config-binding-service.onap.svc.cluster.local, dcae-cloudify-manager, dcae-cloudify-manager.onap, dcae-cloudify-manager.onap.svc.cluster.local, dcae-datafile-collector, dcae-datafile-collector.onap, dcae-datafile-collector.onap.svc.cluster.local, dcae-hv-ves-collector, dcae-hv-ves-collector.onap, dcae-hv-ves-collector.onap.svc.cluster.local, dcae-pm-mapper, dcae-pm-mapper.onap, dcae-pm-mapper.onap.svc.cluster.local, dcae-prh, dcae-prh.onap, dcae-prh.onap.svc.cluster.local, dcae-tca-analytics, dcae-tca-analytics.onap, dcae-tca-analytics.onap.svc.cluster.local, dcae-ves-collector, dcae-ves-collector.onap, dcae-ves-collector.onap.svc.cluster.local, deployment-handler, deployment-handler.onap, deployment-handler.onap.svc.cluster.local, holmes-engine-mgmt, holmes-engine-mgmt.onap, holmes-engine-mgmt.onap.svc.cluster.local, holmes-rule-mgmt, holmes-rules-mgmt.onap, holmes-rules-mgmt.onap.svc.cluster.local, inventory, inventory.onap, inventory.onap.svc.cluster.local, policy-handler, policy-handler.onap, policy-handler.onap.svc.cluster.local
  21
  22 2. Certificate generation and retrieval:
  23
  24    When a DCAE component that needs a TLS certificate is launched, a Kubernetes init container runs before the main
  25    component container is launched.  The init container contacts the AAF certificate manager server.  The AAF certificate
  26    management server generates a certificate based on the information previously set up in step 1 above and sends the certificate
  27    (in several formats) along with keys and passwords to the init container.  The init container renames the files to conform to
  28    DCAE naming conventions and creates some additional formats.  It stores the results into a volume that's shared with
  29    the main component container.
  30
  31    DCAE platform components are deployed via ONAP OOM.  The Helm chart for each deployment includes the init container
  32    and sets up the shared volume.
  33
  34    DCAE service components (sometimes called "microservices") are deployed via Cloudify using blueprints.  This is described
  35    in more detail in the next section.
  36
  37 3. Plugin and Blueprint:
  38     The blueprint for a component that needs a TLS certificate needs to include the node property called "tls_info" in
  39     the node properties for the component. The property is a dictionary with two elements:
  40
  41         * A boolean (``use_tls``) that indicates whether the component uses TLS.
  42         * A string (``cert_directory``) that indicates where the component expects to find certificate artifacts.
  43
  44         Example
  45
  46 .. code-block:: yaml
  47
  48         tls_info:
  49            cert_directory: '/opt/app/dh/etc/cert'
  50            use_tls: true
  51
  52 (Note that the ``cert_directory`` value does not include a trailing ``/``.)
  53
  54 For this example the certificates are mounted into ``/opt/app/dh/etc/cert`` directory within the container.
  55
  56     During deployment Kubernetes plugin (referenced in blueprint) will check if the ``tls_info`` property is set and ``use_tls`` is set to true, then the plugin will add some elements to the Kubernetes Deployment for the component:
  57           * A Kubernetes volume (``tls-info``) that will hold the certificate artifacts
  58           * A Kubernetes initContainer (``tls-init``)
  59           * A Kubernetes volumeMount for the initContainer that mounts the ``tls-info`` volume at ``/opt/app/osaaf``.
  60           * A Kubernetes volumeMount for the main container that mounts the ``tls-info`` volume at the mount point specified in the ``cert_directory`` property.
  61
  62 Service components that act as HTTPS clients only need access to the root CA certificate used by AAF.  For R6, such
  63 components should set up a tls_info property as described above.  See below for a note about an alternative approach
  64 that is available in R6 but is not currently being used.
  65
  66 4. Certificate artifacts
  67
  68     The certificate directory mounted on the container will include the following files:
  69         * ``cert.jks``: A Java keystore containing the DCAE certificate.
  70         * ``jks.pass``: A text file with a single line that contains the password for the ``cert.jks`` keystore.
  71         * ``trust.jks``: A Java truststore containing the AAF CA certificate.  (Needed by clients that access TLS-protected servers.)
  72         * ``trust.pass``: A text file with a single line that contains the password for the ``trust.jks`` keystore.
  73         * ``cert.p12``: The DCAE certificate and private key packaged in PKCS12 form.
  74         * ``p12.pass``: A text file with a single line that contains the password for ``cert.p12`` file.
  75         * ``cert.pem``: The DCAE certificate concatenated with the intermediate CA certficate from AAF, in PEM form.
  76         * ``key.pem``: The private key for the DCAE certificate. The key is not encrypted.
  77         * ``cacert.pem``: The AAF CA certificate, in PEM form.  (Needed by clients that access TLS-protected servers.)
  78
  79 5. Alternative for getting CA certificate only
  80
  81     The certificates generated by AAF are signed by AAF, not by a recognized certificate authority (CA).  If a component acts
  82     as a client and makes an HTTPS request to another component, it will not be able to validate the other component's
  83     server certificate because it will not recognize the CA.  Most HTTPS client library software will raise an error
  84     and drop the connection.  To prevent this, the client component needs to have a copy of the AAF CA certificate.
  85     As noted in section 3 above, one way to do this is to set up the tls_info property as described in section 3 above.
  86
  87     There are alternatives.  In R6, two versions of the DCAE k8splugin are available: version 1.7.2 and version 2.0.0.
  88     They behave differently with respect to setting up the CA certs.
  89
  90     * k8splugin version 1.7.2 will automatically mount the CA certificate, in PEM format, at ``/opt/dcae/cacert/cacert.pem``.
  91       It is not necessary to add anything to the blueprint.  To get the CA certificate in PEM format in a different directory,
  92       add a  ``tls_info`` property to the blueprint, set ``use_tls`` to ``false``, and set ``cert_directory`` to the directory
  93       where the CA cert is needed.  For example:
  94
  95       .. code-block:: yaml
  96
  97             tls_info:
  98                cert_directory: '/opt/app/certs'
  99                use_tls: false
 100
 101       For this example, the CA certificate would be mounted at ``/opt/app/certs/cacert.pem``.
 102
 103       k8splugin version 1.7.2 uses a configmap, rather than an init container, to supply the CA certificate.
 104
 105     * k8splugin version 2.0.0 will automatically mount the CA certificate, in PEM and JKS formats, in the directory ``/opt/dcae/cacert``.
 106       It is not necessary to add anything to the blueprint.  To get the CA certificates in a different directory, add a ``tls_info`` property to the blueprint, set ``use_tls`` to ``false``, and set ``cert_directory`` to the directory
 107       where the CA certs are needed.  Whatever directory is used, the following files will be available:
 108
 109       * ``trust.jks``: A Java truststore containing the AAF CA certificate.  (Needed by clients that access TLS-protected servers.)
 110       * ``trust.pass``: A text file with a single line that contains the password for the ``trust.jks`` keystore.
 111       * ``cacert.pem``: The AAF CA certificate, in PEM form.  (Needed by clients that access TLS-protected servers.)
 112
 113       k8splugin version 2.0.0 uses an init container to supply the CA certificates.
 114
 115 External TLS Support
 116 --------------------
 117
 118 External TLS support was introduced in order to integrate DCAE with CertService to acquire operator certificates meant to protect external traffic between DCAE's components (VES collector, HV-VES, RestConf collector and DFC) and xNFs. For that reason K8s plugin which creates K8s resources from Cloudify blueprints was enhanced with new TLS properties support. New TLS properties are meant to control CertService's client call in init containers section and environment variables which are passed to it.
 119
 120 This external TLS support doesn't influence ONAP internal traffic which is protected by certificates issued by AAF's CertMan. External TLS Support was introduced in k8splugin 3.1.0.
 121
 122 1. Certificate setup:
 123
 124    To create certificate artifacts, AAF CertService must obtain the certificate details. Common name and list of Subject Alternative Names (SANs) are set in blueprint as described in step 3.
 125    The following parameters with default values are stored in OOM in k8splugin configuration file (k8splugin.json) in group ``external_cert``:
 126
 127        * A string ``image_tag`` that indicates CertService client image name and version
 128        * A string ``request_url`` that indicates URL to Cert Service API
 129        * A string ``timeout`` that indicates request timeout.
 130        * A string ``country`` that indicates country name in ISO 3166-1 alpha-2 format, for which certificate will be created
 131        * A string ``organization`` that indicates organization name, for which certificate will be created.
 132        * A string ``state`` that indicates state name, for which certificate will be created.
 133        * A string ``organizational_unit`` that indicates organizational unit name, for which certificate will be created.
 134        * A string ``location`` that indicates location name, for which certificate will be created.
 135
 136    Group ``external_cert`` from k8splugin.json with default values:
 137
 138    .. code-block:: JSON
 139
 140         {
 141           "image_tag": "nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:$VERSION",
 142           "request_url": "https://aaf-cert-service:8443/v1/certificate/",
 143           "timeout":  "30000",
 144           "country": "US",
 145           "organization": "Linux-Foundation",
 146           "state": "California",
 147           "organizational_unit": "ONAP",
 148           "location": "San-Francisco"
 149         }
 150
 151
 152    Parameters configured in k8splugin are propagated via Helm Charts to Kubernetes ConfigMap and finally they are transfered to Consul.
 153    Blueprint, during start of execution, reads k8splugin.json configuration from Consul and applies it.
 154
 155 2. Certificate generation and retrieval:
 156
 157    When a DCAE component that needs a external TLS certificate is launched, a Kubernetes init container runs before the main
 158    component container is launched.  The init container contacts the AAF CertService.
 159
 160    DCAE service components (sometimes called "microservices") are deployed via Cloudify using blueprints.  This is described
 161    in more detail in the next section.
 162
 163 3. Plugin and Blueprint:
 164    The blueprint for a component that needs a external TLS certificate needs to include the node property called "external_cert" in
 165    the node properties for the component. The property is a dictionary with following elements:
 166
 167        * A boolean (``use_external_tls``) that indicates whether the component uses TLS in external traffic.
 168        * A string (``external_cert_directory``) that indicates where the component expects to find  operator certificate and trusted certs.
 169        * A string (``ca_name``) that indicates name of Certificate Authority configured on CertService side (in cmpServers.json).
 170        * A string (``output_type``) that indicates certificate output type.
 171        * A dictionary (``external_certificate_parameters``) with two elements:
 172            * A string (``common_name``) that indicates common name which should be present in certificate. Specific for every blueprint (e.g. dcae-ves-collector for VES).
 173            * A string (``sans``) that indicates list of Subject Alternative Names (SANs) which should be present in certificate. Delimiter - : Should contain common_name value and other FQDNs under which given component is accessible.
 174
 175    Example
 176
 177    .. code-block:: yaml
 178
 179         external_cert:
 180             external_cert_directory: /opt/app/dcae-certificate/
 181             use_external_tls: true
 182             ca_name: "RA"
 183             cert_type: "P12"
 184             external_certificate_parameters:
 185                 common_name: "simpledemo.onap.org"
 186                 sans: "simpledemo.onap.org;ves.simpledemo.onap.org;ves.onap.org"
 187
 188    For this example the certificates are mounted into ``/opt/app/dcae-certificate/external`` directory within the container.
 189
 190    During deployment Kubernetes plugin (referenced in blueprint) will check if the ``external_cert`` property is set and ``use_external_tls`` is set to true, then the plugin will add some elements to the Kubernetes Deployment for the component:
 191           * A Kubernetes volume (``tls-volume``) that will hold the certificate artifacts
 192           * A Kubernetes initContainer (``cert-service-client``)
 193           * A Kubernetes volumeMount for the initContainer that mounts the ``tls-volume`` volume at ``/etc/onap/aaf/certservice/certs/``.
 194           * A Kubernetes volumeMount for the main container that mounts the ``tls-info`` volume at the mount point specified in the ``external_cert_directory`` property.
 195
 196    Kurbernetes volumeMount tls-info is shared with TLS init container for internal traffic.
 197
 198 4. Certificate artifacts
 199
 200     The certificate directory mounted on the container will include the following:
 201         * Directory ``external`` with files:
 202             * ``keystore.p12``: A keystore containing the operator certificate.
 203             * ``keystore.pass``: A text file with a single line that contains the password for the ``keystore.p12`` keystore.
 204             * ``truststore.p12``: A truststore containing the operator certificate.  (Needed by clients that access TLS-protected servers in external traffic.)
 205             * ``truststore.pass``: A text file with a single line that contains the password for the ``truststore.p12`` keystore.
 206         * ``trust.jks``: The AAF CA certificate and private key packaged in Java form.
 207         * ``trust.pass``: A text file with a single line that contains the password for ``trust.jks`` file.
 208         * ``cacert.pem``: The AAF CA certificate, in PEM form.