|
| 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 | + * add certificates of other SORMAS instances to the local truststore |
| 6 | + |
| 7 | +### Prerequisites |
| 8 | + |
| 9 | +Java is needed, because the keytool is used for certificate import. <br/> |
| 10 | +See [Installing Java](SERVER_SETUP.md#java-11) |
| 11 | + |
| 12 | +### Using the certificate generation script |
| 13 | + |
| 14 | +1. Run ``bash ./generate-cert.sh`` |
| 15 | +2. If the ``sormas2sormas`` directory is not found, you will be prompted to provide its path. |
| 16 | +3. If the ``SORMAS_PROPERTIES`` environment variable is not available, the script will search for the ``sormas.properties`` |
| 17 | +file in ``/opt/domains/sormas/sormas.properties`` by default. If it is not found there, you will be prompted to provide |
| 18 | +the path to the ``sormas.properties`` file. |
| 19 | +4. For the generation of the certificate, the following data is needed: a password, a *Common Name* (CN) |
| 20 | + and an *Organization* (O). These may be set in environment variables (recommended), or provided |
| 21 | + manually as the script executes. |
| 22 | + * The password environment variable should be named ``SORMAS_S2S_CERT_PASS``. Please note that the password has to be |
| 23 | + at least 6 characters, or you will be prompted for a new one. |
| 24 | + * the *Common Name* environment variable should be named ``SORMAS_S2S_CERT_CN``.<br/> |
| 25 | + **Important**: for Germany, this value should be the SurvNet Code Site. <br/> |
| 26 | + E.g. *2.03.1.01.* |
| 27 | + * the *Organization* (O) environment variable should be named ``SORMAS_S2S_CERT_ORG``.<br/> |
| 28 | + **Important**: for Germany, this value should be the name of the Health Department (Gesundheitsamt) |
| 29 | + to which the SORMAS instance will be assigned. <br/> |
| 30 | + E.g. *GA Braunschweig* |
| 31 | +5. After providing the requested data, the certificate files will be generated. <br/> |
| 32 | + The generated certificate has a validity of 3 years. |
| 33 | + The certificate files will be available in the root SORMAS directory, in the folder ``/sormas2sormas``. |
| 34 | +6. The generated ``.p12`` file should not be shared with third parties. <br/> |
| 35 | + The generated ``.crt`` file will be verified and shared with other SORMAS instances, from which this instance |
| 36 | + will be able to request data. Conversely, in order to enable other SORMAS instances to request data from this |
| 37 | + instance, their certificate files should be obtained and added to the local truststore. More details can be found |
| 38 | + in the next section. |
| 39 | +7. The relevant properties will be automatically set by the script in the ``sormas.properties`` file. |
| 40 | + |
| 41 | +### Adding a new certificate to the Truststore |
| 42 | + |
| 43 | +To enable other SORMAS instances to request data from this instance, their certificate must be added to the |
| 44 | +truststore of this instance. After obtaining their certificate file, which should be a ``.crt`` file, please |
| 45 | +follow the next steps: |
| 46 | +1. Run ``bash ./import-to-truststore.sh`` |
| 47 | +2. If the ``sormas2sormas`` directory is not found, you will be prompted to provide its path. |
| 48 | +3. If the ``SORMAS_PROPERTIES`` environment variable is not available, the script will search for the ``sormas.properties`` |
| 49 | + file in ``/opt/domains/sormas/sormas.properties`` by default. If it is not found there, you will be prompted to provide |
| 50 | + the path to the ``sormas.properties`` file. |
| 51 | +4. If ``sormas2sormas.truststore.p12`` is not found in the folder ``/sormas2sormas``, it will be created. |
| 52 | + The truststore password may be provided in an environment variable ``SORMAS_S2S_TRUSTSTORE_PASS``. |
| 53 | + * If the aforementioned environment variable is not available, the truststore password will be searched in the |
| 54 | + ``sormas.properties`` file. |
| 55 | + * If it is not found there, you will be prompted to provide the truststore password. |
| 56 | + * The relevant properties will be automatically set by the script in the ``sormas.properties`` file. |
| 57 | +5. You will be prompted to provide the file name of the certificate to be imported. This certificate should be located |
| 58 | +in the ``/sormas2sormas`` folder. Please provide the name including the extension. E.g ``mycert.crt`` |
| 59 | +6. After providing the requested data, the certificate will be imported to the truststore. |
| 60 | +7. You may now delete the ``.crt`` file. |
0 commit comments