|
| 1 | +# How to create and add certificates? |
| 2 | + |
| 3 | +This guide explains how to: |
| 4 | + * create a new self-signed certificate, used for SORMAS to SORMAS communication |
| 5 | + * set up the server address list file |
| 6 | + * add certificates of other SORMAS instances to the local truststore |
| 7 | + * add other servers to the local server list |
| 8 | + |
| 9 | +### Prerequisites |
| 10 | + |
| 11 | +Java is needed, because the keytool is used for certificate import. <br/> |
| 12 | +See [Installing Java](SERVER_SETUP.md#java-11) |
| 13 | + |
| 14 | +### Using the certificate generation script |
| 15 | + |
| 16 | +1. Run ``bash ./generate-cert.sh`` |
| 17 | +2. If the ``sormas2sormas`` directory is not found, you will be prompted to provide its path. |
| 18 | +3. If the ``SORMAS_PROPERTIES`` environment variable is not available, the script will search for the ``sormas.properties`` |
| 19 | +file in ``/opt/domains/sormas/sormas.properties`` by default. If it is not found there, you will be prompted to provide |
| 20 | +the path to the ``sormas.properties`` file. |
| 21 | +4. For the generation of the certificate, the following data is needed: a password, a *Common Name* (CN) |
| 22 | + and an *Organization* (O). These may be set in environment variables (recommended), or provided |
| 23 | + manually as the script executes. |
| 24 | + * The password environment variable should be named ``SORMAS_S2S_CERT_PASS``. Please note that the password has to be |
| 25 | + at least 6 characters, or you will be prompted for a new one. |
| 26 | + * the *Common Name* environment variable should be named ``SORMAS_S2S_CERT_CN``.<br/> |
| 27 | + **Important**: for Germany, this value should be the SurvNet Code Site. <br/> |
| 28 | + E.g. *2.03.1.01.* |
| 29 | + * the *Organization* (O) environment variable should be named ``SORMAS_S2S_CERT_ORG``.<br/> |
| 30 | + **Important**: for Germany, this value should be the name of the Health Department (Gesundheitsamt) |
| 31 | + to which the SORMAS instance will be assigned. <br/> |
| 32 | + E.g. *GA Braunschweig* |
| 33 | +5. After providing the requested data, the certificate files will be generated. <br/> |
| 34 | + The generated certificate has a validity of 3 years. |
| 35 | + The certificate files will be available in the root SORMAS directory, in the folder ``/sormas2sormas``. |
| 36 | +6. A CSV file containing the access data for this instance will also be generated in the folder ``/sormas2sormas``. |
| 37 | + It will be named ``server-access-data.csv``. |
| 38 | + The file will contain on the first two columns of the first row the Common Name and the Organization, as provided |
| 39 | + when creating the certificate. <br/> |
| 40 | + **Please fill in on the third column the full URL of the server.** <br/> |
| 41 | + You will also have to set up a user for communicating with other SORMAS instances. |
| 42 | +7. The generated ``.p12`` file should not be shared with third parties. <br/> |
| 43 | + The generated ``.crt`` file will be verified and shared with other SORMAS instances, from which this instance |
| 44 | + will be able to request data. Conversely, in order to enable other SORMAS instances to request data from this |
| 45 | + instance, their certificate files should be obtained and added to the local truststore. The ``server-access-data.csv`` |
| 46 | + file will also have to be shared so that the access data of this instance is known to other instances. |
| 47 | + More details can be found in the next section. |
| 48 | +8. The relevant properties will be automatically set by the script in the ``sormas.properties`` file. |
| 49 | + |
| 50 | +### Adding a new certificate to the Truststore |
| 51 | + |
| 52 | +To enable other SORMAS instances to send and receive data from this instance, their certificate must be added to the |
| 53 | +truststore of this instance. Furthermore, the access data of other instances must be added to the local server |
| 54 | +list. To complete this setup, please follow the next steps: |
| 55 | +1. Run ``bash ./import-to-truststore.sh`` |
| 56 | +2. If the ``sormas2sormas`` directory is not found, you will be prompted to provide its path. |
| 57 | +3. If the ``SORMAS_PROPERTIES`` environment variable is not available, the script will search for the ``sormas.properties`` |
| 58 | + file in ``/opt/domains/sormas/sormas.properties`` by default. If it is not found there, you will be prompted to provide |
| 59 | + the path to the ``sormas.properties`` file. |
| 60 | +4. If ``sormas2sormas.truststore.p12`` is not found in the folder ``/sormas2sormas``, it will be created. |
| 61 | + The truststore password may be provided in an environment variable ``SORMAS_S2S_TRUSTSTORE_PASS``. |
| 62 | + * If the aforementioned environment variable is not available, the truststore password will be searched in the |
| 63 | + ``sormas.properties`` file. |
| 64 | + * If it is not found there, you will be prompted to provide the truststore password. |
| 65 | + * The relevant properties will be automatically set by the script in the ``sormas.properties`` file. |
| 66 | +5. If the server address list file ``server-list.csv`` is not found in the folder ``/sormas2sormas``, it will also be created. |
| 67 | +6. You will be prompted to provide the file name of the certificate to be imported. This certificate should be located |
| 68 | +in the ``/sormas2sormas`` folder. Please provide the name including the extension. E.g ``mycert.crt`` |
| 69 | +7. After providing the requested data, the certificate will be imported to the truststore. |
| 70 | +8. You should have also received a CSV file with the server access data. From this file, copy the line corresponding to the |
| 71 | + instance you would like to communicate with and add it to the local server address list file. This file is named |
| 72 | + ``server-list.csv`` and is located in the ``/sormas2sormas`` folder. <br/> |
| 73 | + *Note*: You may check that the Common Name and the Organization of the certificate match the ones corresponding to |
| 74 | + the server in the CSV file. |
| 75 | +9. You may now delete the ``.crt`` file. |
0 commit comments