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 Certification Service Client needs the following configuration parameters to work properly:
  12
  13 1. Parameters for connection to Certification Service API to obtain certificate and trust anchors
  14
  15   - REQUEST_URL *(default: https://aaf-cert-service:8443/v1/certificate/)* - URL to Certification Service API
  16   - REQUEST_TIMEOUT *(default: 30000[ms])* - Timeout In miliseconds 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 CSR file:
  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:
  32
  33   - KEYSTORE_PATH *(required)*
  34   - KEYSTORE_PASSWORD *(required)*
  35   - TRUSTSTORE_PATH *(required)*
  36   - TRUSTSTORE_PASSWORD *(required)*
  37
  38 Certification Service 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 certification service 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 Certification Service 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 certification service API>
  57   REQUEST_TIMEOUT=10000
  58   OUTPUT_PATH=/var/certs
  59   CA_NAME=RA
  60   #CSR config envs
  61   COMMON_NAME=onap.org
  62   ORGANIZATION=Linux-Foundation
  63   ORGANIZATION_UNIT=ONAP
  64   LOCATION=San-Francisco
  65   STATE=California
  66   COUNTRY=US
  67   SANS=test.onap.org:onap.com
  68   #TLS config envs
  69   KEYSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-keystore.jks
  70   KEYSTORE_PASSWORD=<password to keystore.jks>
  71   TRUSTSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-truststore.jks
  72   TRUSTSTORE_PASSWORD=<password to certServiceClient-truststore.jks>
  73
  74 2. Run docker container as in following example (API and client must be running in same network):
  75
  76 .. code-block:: bash
  77
  78  docker run \
  79     --rm \
  80     --name aafcert-client \
  81     --env-file <$PWD/client.env (same as in step1)> \
  82     --network <docker network of cert service> \
  83     --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)> \
  84     --volume <local path to keystore.jks>:<KEYSTORE_PATH> \
  85     --volume <local path to trustore.jks>:<TRUSTSTORE_PATH> \
  86     nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:$VERSION
  87
  88
  89
  90 After successful creation of certifications, container exits with exit code 0, expected logs looks like:
  91
  92 .. code-block:: bash
  93
  94   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
  95   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
  96   INFO 1 [           main] o.o.a.c.c.c.KeyPairFactory               : KeyPair generation started with algorithm: RSA and key size: 2048
  97   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
  98   INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Creation of CSR has been completed successfully
  99   INFO 1 [           main] o.o.a.c.c.c.CsrFactory                   : Conversion of CSR to PEM has been started
 100   INFO 1 [           main] o.o.a.c.c.c.PrivateKeyToPemEncoder       : Attempt to encode private key to PEM
 101   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
 102   INFO 1 [           main] o.o.a.c.c.h.HttpClient                   : Received response from API
 103   INFO 1 [           main] o.o.a.c.c.c.c.PemToPKCS12Converter       : Conversion of PEM certificates to PKCS12 keystore
 104   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
 105   INFO 1 [           main] o.o.a.c.c.c.c.PemToPKCS12Converter       : Conversion of PEM certificates to PKCS12 truststore
 106   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
 107   INFO 1 [           main] o.o.a.c.c.AppExitHandler                 : Application exits with following exit code: 0 and message: Success
 108
 109
 110 If container exits with non 0 exit code, you can find more information in logs, see :ref:`cert_logs` page.
 111
 112 As init container for Kubernetes
 113 --------------------------------
 114
 115 To run Certification Service Client as init container for ONAP component, add following configuration to deploymnet:
 116
 117 .. code-block:: yaml
 118
 119     ...
 120   kind: Deployment
 121   metadata:
 122     ...
 123   spec:
 124   ...
 125     template:
 126     ...
 127       spec:
 128         containers:
 129           - image: sample.image
 130             name: sample.name
 131             ...
 132             volumeMounts:
 133               - mountPath: /var/certs #CERTS CAN BE FOUND IN THIS DIRECTORY
 134                 name: certs
 135             ...
 136         initContainers:
 137           - name: cert-service-client
 138             image: nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:latest
 139             imagePullPolicy: Always
 140             env:
 141               - name: REQUEST_URL
 142                 value: http://aaf-cert-service:8080/v1/certificate/
 143               - name: REQUEST_TIMEOUT
 144                 value: "1000"
 145               - name: OUTPUT_PATH
 146                 value: /var/certs
 147               - name: CA_NAME
 148                 value: RA
 149               - name: COMMON_NAME
 150                 value: onap.org
 151               - name: ORGANIZATION
 152                 value: Linux-Foundation
 153               - name: ORGANIZATION_UNIT
 154                 value: ONAP
 155               - name: LOCATION
 156                 value: San-Francisco
 157               - name: STATE
 158                 value: California
 159               - name: COUNTRY
 160                 value: US
 161               - name: SANS
 162                 value: test.onap.org:onap.com
 163               - name: KEYSTORE_PATH
 164                 value: /etc/onap/aaf/certservice/certs/certServiceClient-keystore.jks
 165               - name: KEYSTORE_PASSWORD
 166                 value: secret
 167               - name: TRUSTSTORE_PATH
 168                 value: /etc/onap/aaf/certservice/certs/truststore.jks
 169               - name: TRUSTSTORE_PASSWORD
 170                 value: secret
 171             volumeMounts:
 172               - mountPath: /var/certs
 173                 name: certs
 174               - mountPath: /etc/onap/aaf/certservice/certs/
 175                 name: tls-volume
 176           ...
 177         volumes:
 178         - name: certs
 179           emptyDir: {}
 180         - name tls-volume
 181           secret:
 182             secretName: aaf-cert-service-client-tls-secret  # Value of global.aaf.certService.client.secret.name
 183         ...
 184
 185