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 NOKIA
   4
   5 How to use functionality
   6 =========================
   7 Common information to docker and Kubernetes modes described below
   8
   9 Basic information
  10 -----------------
  11 CertService client needs the following configuration parameters to work properly:
  12
  13 1. Parameters for generating certification artifacts and connecting to CertService API to obtain certificate and trust anchors
  14
  15   - REQUEST_URL *(default: https://oom-cert-service:8443/v1/certificate/)* - URL to CertService API
  16   - REQUEST_TIMEOUT *(default: 30000[ms])* - Timeout in milliseconds for REST API calls
  17   - OUTPUT_PATH *(required)* - Path where client will output generated certificate and trust anchor
  18   - CA_NAME *(required)* - Name of CA which will enroll certificate. Must be same as configured on server side. Used in REST API calls
  19   - OUTPUT_TYPE *(default: P12)* - Type of certificate which will be generated. Supported types:
  20
  21       - JKS - Java KeyStore (JKS)
  22       - P12 - Public Key Cryptography Standard #12 (PKCS#12)
  23       - PEM - Privacy-Enhanced Mail (PEM)
  24
  25
  26 2. Parameters to generate Certificate Signing Request (CSR):
  27
  28   - COMMON_NAME *(required)* - Common name for which certificate from CMPv2 server should be issued
  29   - ORGANIZATION *(required)* - Organization for which certificate from CMPv2 server should be issued
  30   - ORGANIZATION_UNIT *(optional)* - Organization unit for which certificate from CMPv2 server should be issued
  31   - LOCATION *(optional)* - Location for which certificate from CMPv2 server should be issued
  32   - STATE *(required)* - State for which certificate from CMPv2 server should be issued
  33   - COUNTRY *(required)* - Country for which certificate from CMPv2 server should be issued
  34   - SANS *(optional)(SANS's should be separated by a comma e.g. test.onap.org,onap.com)* - Subject Alternative Names (SANs) for which certificate from CMPv2 server should be issued.
  35
  36 3. Parameters to establish secure communication to CertService:
  37
  38   - KEYSTORE_PATH *(required)*
  39   - KEYSTORE_PASSWORD *(required)*
  40   - TRUSTSTORE_PATH *(required)*
  41   - TRUSTSTORE_PASSWORD *(required)*
  42
  43 CertService client image can be found on Nexus repository :
  44
  45 .. code-block:: bash
  46
  47   nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:$VERSION
  48
  49
  50 As standalone docker container
  51 ------------------------------
  52 You need certificate and trust anchors to connect to CertService API via HTTPS. Information how to generate truststore and keystore files you can find in project repository README `Gerrit GitWeb <https://gerrit.onap.org/r/gitweb?p=oom%2Fplatform%2Fcert-service.git;a=summary>`__
  53
  54 To run CertService client as standalone docker container execute following steps:
  55
  56 1. Create file '*$PWD/client.env*' with environment variables as in example below:
  57
  58 .. code-block:: bash
  59
  60   #Client envs
  61   REQUEST_URL=<URL to CertService API>
  62   REQUEST_TIMEOUT=10000
  63   OUTPUT_PATH=/var/certs
  64   CA_NAME=RA
  65   OUTPUT_TYPE=P12
  66
  67   #CSR config envs
  68   COMMON_NAME=onap.org
  69   ORGANIZATION=Linux-Foundation
  70   ORGANIZATION_UNIT=ONAP
  71   LOCATION=San-Francisco
  72   STATE=California
  73   COUNTRY=US
  74   SANS=test.onap.org,onap.com
  75
  76   #TLS config envs
  77   KEYSTORE_PATH=/etc/onap/oom/certservice/certs/certServiceClient-keystore.jks
  78   KEYSTORE_PASSWORD=<password to certServiceClient-keystore.jks>
  79   TRUSTSTORE_PATH=/etc/onap/oom/certservice/certs/certServiceClient-truststore.jks
  80   TRUSTSTORE_PASSWORD=<password to certServiceClient-truststore.jks>
  81
  82 2. Run docker container as in following example (API and client must be running in same network):
  83
  84 .. code-block:: bash
  85
  86  docker run \
  87     --rm \
  88     --name oomcert-client \
  89     --env-file <$PWD/client.env (same as in step1)> \
  90     --network <docker network of cert service> \
  91     --mount type=bind,src=<path to local host directory where certificate and trust anchor will be created>,dst=<OUTPUT_PATH (same as in step 1)> \
  92     --volume <local path to keystore in JKS format>:<KEYSTORE_PATH> \
  93     --volume <local path to truststore in JKS format>:<TRUSTSTORE_PATH> \
  94     nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:$VERSION
  95
  96
  97
  98 After successful creation of certifications, container exits with exit code 0, expected log looks like:
  99
 100 .. code-block:: bash
 101
 102    INFO 1 [           main] o.o.a.c.c.c.f.ClientConfigurationFactory : Successful validation of Client configuration. Configuration data: REQUEST_URL: https://oom-cert-service:8443/v1/certificate/, REQUEST_TIMEOUT: 10000, OUTPUT_PATH: /var/certs, CA_NAME: RA, OUTPUT_TYPE: P12
 103    INFO 1 [           main] o.o.a.c.c.c.f.CsrConfigurationFactory    : Successful validation of CSR configuration. Configuration data: COMMON_NAME: onap.org, COUNTRY: US, STATE: California, ORGANIZATION: Linux-Foundation, ORGANIZATION_UNIT: ONAP, LOCATION: San-Francisco, SANS: test.onap.org:onap.org
 104    INFO 1 [           main] o.o.a.c.c.c.KeyPairFactory               : KeyPair generation started with algorithm: RSA and key size: 2048
 105    INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Creation of CSR has been started with following parameters: COMMON_NAME: onap.org, COUNTRY: US, STATE: California, ORGANIZATION: Linux-Foundation, ORGANIZATION_UNIT: ONAP, LOCATION: San-Francisco, SANS: test.onap.org:onap.org
 106    INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Creation of CSR has been completed successfully
 107    INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Conversion of CSR to PEM has been started
 108    INFO 1 [           main] o.o.a.c.c.c.PrivateKeyToPemEncoder       : Attempt to encode private key to PEM
 109    INFO 1 [           main] o.o.a.c.c.h.HttpClient                   : Attempt to send request to API, on url: https://oom-cert-service:8443/v1/certificate/RA
 110    INFO 1 [           main] o.o.a.c.c.h.HttpClient                   : Received response from API
 111   DEBUG 1 [           main] o.o.a.c.c.c.c.ConvertedArtifactsCreator  : Attempt to create keystore files and saving data. File names: keystore.p12, keystore.pass
 112    INFO 1 [           main] o.o.a.c.c.c.c.PemConverter               : Conversion of PEM certificates to PKCS12 keystore
 113   DEBUG 1 [           main] o.o.a.c.c.c.w.CertFileWriter             : Attempt to save file keystore.p12 in path /var/certs
 114   DEBUG 1 [           main] o.o.a.c.c.c.w.CertFileWriter             : Attempt to save file keystore.pass in path /var/certs
 115   DEBUG 1 [           main] o.o.a.c.c.c.c.ConvertedArtifactsCreator  : Attempt to create truststore files and saving data. File names: truststore.p12, truststore.pass
 116    INFO 1 [           main] o.o.a.c.c.c.c.PemConverter               : Conversion of PEM certificates to PKCS12 truststore
 117   DEBUG 1 [           main] o.o.a.c.c.c.w.CertFileWriter             : Attempt to save file truststore.p12 in path /var/certs
 118   DEBUG 1 [           main] o.o.a.c.c.c.w.CertFileWriter             : Attempt to save file truststore.pass in path /var/certs
 119    INFO 1 [           main] o.o.a.c.c.AppExitHandler                 : Application exits with following exit code: 0 and message: Success
 120
 121
 122
 123
 124 If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
 125
 126 As init container for Kubernetes
 127 --------------------------------
 128
 129 In order to run CertService client as init container for ONAP component you need to:
 130
 131     - define an init container and use CerService Client image
 132     - provide client configuration through ENV variables in the init container
 133     - define two volumes:
 134
 135         - first for generated certificates - it will be mounted in the init container and in the component container
 136         - second with secret containing keys and certificates for secure communication between CertService Client and CertService - it will be mounted only in the init container
 137     - mount both volumes to the init container
 138     - mount first volume to the component container
 139
 140 You can use the following deployment example as a reference:
 141
 142 .. code-block:: yaml
 143
 144     ...
 145   kind: Deployment
 146   metadata:
 147     ...
 148   spec:
 149   ...
 150     template:
 151     ...
 152       spec:
 153         containers:
 154           - image: sample.image
 155             name: sample.name
 156             ...
 157             volumeMounts:
 158               - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
 159                 name: certs
 160             ...
 161         initContainers:
 162           - name: cert-service-client
 163             image: nexus3.onap.org:10001/onap/org.onap.oom.platform.cert-service.oom-certservice-client:latest
 164             imagePullPolicy: Always
 165             env:
 166               - name: REQUEST_URL
 167                 value: https://oom-cert-service:8443/v1/certificate/
 168               - name: REQUEST_TIMEOUT
 169                 value: "1000"
 170               - name: OUTPUT_PATH
 171                 value: /var/certs
 172               - name: CA_NAME
 173                 value: RA
 174               - name: OUTPUT_TYPE
 175                 value: P12
 176               - name: COMMON_NAME
 177                 value: onap.org
 178               - name: ORGANIZATION
 179                 value: Linux-Foundation
 180               - name: ORGANIZATION_UNIT
 181                 value: ONAP
 182               - name: LOCATION
 183                 value: San-Francisco
 184               - name: STATE
 185                 value: California
 186               - name: COUNTRY
 187                 value: US
 188               - name: SANS
 189                 value: test.onap.org:onap.com
 190               - name: KEYSTORE_PATH
 191                 value: /etc/onap/oom/certservice/certs/certServiceClient-keystore.jks
 192               - name: KEYSTORE_PASSWORD
 193                 value: secret
 194               - name: TRUSTSTORE_PATH
 195                 value: /etc/onap/oom/certservice/certs/truststore.jks
 196               - name: TRUSTSTORE_PASSWORD
 197                 value: secret
 198             volumeMounts:
 199               - mountPath: /var/certs
 200                 name: certs
 201               - mountPath: /etc/onap/oom/certservice/certs/
 202                 name: tls-volume
 203           ...
 204         volumes:
 205         - name: certs
 206           emptyDir: {}
 207         - name tls-volume
 208           secret:
 209             secretName: oom-cert-service-client-tls-secret  # Value of global.oom.certService.client.secret.name
 210         ...
 211