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. All SANs types are supported (DNS names, IPs, URIs, emails).
  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,onap@onap.org,127.0.0.1,onap://cluster.local/
  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.o.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.o.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: [{SAN value: example.org, type: dNSName}, {SAN value: test.onap.org, type: dNSName}, {SAN value: onap@onap.org, type: rfc822Name}, {SAN value: 127.0.0.1, type: iPAddress}, {SAN value: onap://cluster.local/, type: uniformResourceIdentifier}]
 104    INFO 1 [           main] o.o.o.c.c.c.KeyPairFactory               : KeyPair generation started with algorithm: RSA and key size: 2048
 105    INFO 1 [           main] o.o.o.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: [{SAN value: example.org, type: dNSName}, {SAN value: test.onap.org, type: dNSName}, {SAN value: onap@onap.org, type: rfc822Name}, {SAN value: 127.0.0.1, type: iPAddress}, {SAN value: onap://cluster.local/, type: uniformResourceIdentifier}]
 106    INFO 1 [           main] o.o.o.c.c.c.CsrFactory                   : Creation of CSR has been completed successfully
 107    INFO 1 [           main] o.o.o.c.c.c.CsrFactory                   : Conversion of CSR to PEM has been started
 108    INFO 1 [           main] o.o.o.c.c.c.PrivateKeyToPemEncoder       : Attempt to encode private key to PEM
 109    INFO 1 [           main] o.o.o.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.o.c.c.h.HttpClient                   : Received response from API
 111   DEBUG 1 [           main] o.o.o.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.o.c.c.c.c.PemConverter               : Conversion of PEM certificates to PKCS12 keystore
 113   DEBUG 1 [           main] o.o.o.c.c.c.w.CertFileWriter             : Attempt to save file keystore.p12 in path /var/certs
 114   DEBUG 1 [           main] o.o.o.c.c.c.w.CertFileWriter             : Attempt to save file keystore.pass in path /var/certs
 115   DEBUG 1 [           main] o.o.o.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.o.c.c.c.c.PemConverter               : Conversion of PEM certificates to PKCS12 truststore
 117   DEBUG 1 [           main] o.o.o.c.c.c.w.CertFileWriter             : Attempt to save file truststore.p12 in path /var/certs
 118   DEBUG 1 [           main] o.o.o.c.c.c.w.CertFileWriter             : Attempt to save file truststore.pass in path /var/certs
 119    INFO 1 [           main] o.o.o.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,onap@onap.org,127.0.0.1,onap://cluster.local/
 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