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 connection to CertService API to obtain certificate and trust anchors
  14
  15   - REQUEST_URL *(default: https://aaf-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
  20
  21 2. Parameters to generate Certificate Signing Request (CSR):
  22
  23   - COMMON_NAME *(required)* - Common name for which certificate from CMPv2 server should be issued
  24   - ORGANIZATION *(required)* - Organization for which certificate from CMPv2 server should be issued
  25   - ORGANIZATION_UNIT *(optional)* - Organization unit for which certificate from CMPv2 server should be issued
  26   - LOCATION *(optional)* - Location for which certificate from CMPv2 server should be issued
  27   - STATE *(required)* - State for which certificate from CMPv2 server should be issued
  28   - COUNTRY *(required)* - Country for which certificate from CMPv2 server should be issued
  29   - SANS *(optional)(SANS's should be separated by a colon e.g. test.onap.org:onap.com)* - Subject Alternative Names (SANs) for which certificate from CMPv2 server should be issued.
  30
  31 3. Parameters to establish secure communication to CertService:
  32
  33   - KEYSTORE_PATH *(required)*
  34   - KEYSTORE_PASSWORD *(required)*
  35   - TRUSTSTORE_PATH *(required)*
  36   - TRUSTSTORE_PASSWORD *(required)*
  37
  38 CertService client image can be found on Nexus repository :
  39
  40 .. code-block:: bash
  41
  42   nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:$VERSION
  43
  44
  45 As standalone docker container
  46 ------------------------------
  47 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=aaf%2Fcertservice.git;a=summary>`__
  48
  49 To run CertService client as standalone docker container execute following steps:
  50
  51 1. Create file '*$PWD/client.env*' with environments as in example below:
  52
  53 .. code-block:: bash
  54
  55   #Client envs
  56   REQUEST_URL=<URL to CertService API>
  57   REQUEST_TIMEOUT=10000
  58   OUTPUT_PATH=/var/certs
  59   CA_NAME=RA
  60
  61   #CSR config envs
  62   COMMON_NAME=onap.org
  63   ORGANIZATION=Linux-Foundation
  64   ORGANIZATION_UNIT=ONAP
  65   LOCATION=San-Francisco
  66   STATE=California
  67   COUNTRY=US
  68   SANS=test.onap.org:onap.com
  69
  70   #TLS config envs
  71   KEYSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-keystore.jks
  72   KEYSTORE_PASSWORD=<password to certServiceClient-keystore.jks>
  73   TRUSTSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-truststore.jks
  74   TRUSTSTORE_PASSWORD=<password to certServiceClient-truststore.jks>
  75
  76 2. Run docker container as in following example (API and client must be running in same network):
  77
  78 .. code-block:: bash
  79
  80  docker run \
  81     --rm \
  82     --name aafcert-client \
  83     --env-file <$PWD/client.env (same as in step1)> \
  84     --network <docker network of cert service> \
  85     --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)> \
  86     --volume <local path to keystore in JKS format>:<KEYSTORE_PATH> \
  87     --volume <local path to truststore in JKS format>:<TRUSTSTORE_PATH> \
  88     nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:$VERSION
  89
  90
  91
  92 After successful creation of certifications, container exits with exit code 0, expected log looks like:
  93
  94 .. code-block:: bash
  95
  96   INFO 1 [           main] o.o.a.c.c.c.f.ClientConfigurationFactory : Successful validation of Client configuration. Configuration data: REQUEST_URL: https://aaf-cert-service:8443/v1/certificate/, REQUEST_TIMEOUT: 10000, OUTPUT_PATH: /var/certs, CA_NAME: RA
  97   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
  98   INFO 1 [           main] o.o.a.c.c.c.KeyPairFactory               : KeyPair generation started with algorithm: RSA and key size: 2048
  99   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
 100   INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Creation of CSR has been completed successfully
 101   INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Conversion of CSR to PEM has been started
 102   INFO 1 [           main] o.o.a.c.c.c.PrivateKeyToPemEncoder       : Attempt to encode private key to PEM
 103   INFO 1 [           main] o.o.a.c.c.h.HttpClient                   : Attempt to send request to API, on url: https://aaf-cert-service:8443/v1/certificate/RA
 104   INFO 1 [           main] o.o.a.c.c.h.HttpClient                   : Received response from API
 105   INFO 1 [           main] o.o.a.c.c.c.c.PemToPKCS12Converter       : Conversion of PEM certificates to PKCS12 keystore
 106   DEBUG 1 [           main] o.o.a.c.c.c.c.PKCS12FilesCreator         : Attempt to create PKCS12 keystore files and saving data. Keystore path: /var/certs/keystore.jks
 107   INFO 1 [           main] o.o.a.c.c.c.c.PemToPKCS12Converter       : Conversion of PEM certificates to PKCS12 truststore
 108   DEBUG 1 [           main] o.o.a.c.c.c.c.PKCS12FilesCreator         : Attempt to create PKCS12 truststore files and saving data. Truststore path: /var/certs/truststore.jks
 109   INFO 1 [           main] o.o.a.c.c.AppExitHandler                 : Application exits with following exit code: 0 and message: Success
 110
 111
 112 If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
 113
 114 As init container for Kubernetes
 115 --------------------------------
 116
 117 In order to run CertService client as init container for ONAP component you need to:
 118
 119     - define an init container and use CerService Client image
 120     - provide client configuration through ENV variables in the init container
 121     - define two volumes:
 122
 123         - first for generated certificates - it will be mounted in the init container and in the component container
 124         - second with secret containing keys and certificates for secure communication between CertService Client and CertService - it will be mounted only in the init container
 125     - mount both volumes to the init container
 126     - mount first volume to the component container
 127
 128 You can use the following deployment example as a reference:
 129
 130 .. code-block:: yaml
 131
 132     ...
 133   kind: Deployment
 134   metadata:
 135     ...
 136   spec:
 137   ...
 138     template:
 139     ...
 140       spec:
 141         containers:
 142           - image: sample.image
 143             name: sample.name
 144             ...
 145             volumeMounts:
 146               - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
 147                 name: certs
 148             ...
 149         initContainers:
 150           - name: cert-service-client
 151             image: nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
 152             imagePullPolicy: Always
 153             env:
 154               - name: REQUEST_URL
 155                 value: http://aaf-cert-service:8080/v1/certificate/
 156               - name: REQUEST_TIMEOUT
 157                 value: "1000"
 158               - name: OUTPUT_PATH
 159                 value: /var/certs
 160               - name: CA_NAME
 161                 value: RA
 162               - name: COMMON_NAME
 163                 value: onap.org
 164               - name: ORGANIZATION
 165                 value: Linux-Foundation
 166               - name: ORGANIZATION_UNIT
 167                 value: ONAP
 168               - name: LOCATION
 169                 value: San-Francisco
 170               - name: STATE
 171                 value: California
 172               - name: COUNTRY
 173                 value: US
 174               - name: SANS
 175                 value: test.onap.org:onap.com
 176               - name: KEYSTORE_PATH
 177                 value: /etc/onap/aaf/certservice/certs/certServiceClient-keystore.jks
 178               - name: KEYSTORE_PASSWORD
 179                 value: secret
 180               - name: TRUSTSTORE_PATH
 181                 value: /etc/onap/aaf/certservice/certs/truststore.jks
 182               - name: TRUSTSTORE_PASSWORD
 183                 value: secret
 184             volumeMounts:
 185               - mountPath: /var/certs
 186                 name: certs
 187               - mountPath: /etc/onap/aaf/certservice/certs/
 188                 name: tls-volume
 189           ...
 190         volumes:
 191         - name: certs
 192           emptyDir: {}
 193         - name tls-volume
 194           secret:
 195             secretName: aaf-cert-service-client-tls-secret  # Value of global.aaf.certService.client.secret.name
 196         ...
 197
 198