WHO SMART Trust
1.1.5 - CI Build

WHO SMART Trust, published by WHO. This guide is not an authorized publication; it is the continuous build for version 1.1.5 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/WorldHealthOrganization/smart-trust/tree/onboarding_checklist_enhancement and changes regularly. See the Directory of published versions

## Concepts Certificate Preparation

This guide follows the certificate templates defined in the certificate governance. Public Key Certificates generated by following this guide will include the minimal required fields - further fields can be added in the configuration files if needed.

### Elliptic Curve Public Key Certificates (ECDSA with NIST-p-256)

#### SCA certificate (TNPSCA) generation example:

##### sca.conf

Create a new file called sca.conf and replace the dn entries with your jurisdiction's details.

    [req]
    prompt = no
    default_md = sha256
    distinguished_name = dn

    [dn]
    C = DE
    ST = NRW
    L = Bonn
    O = MinistryOfTest
    OU = DGCOperations
    CN = SCA_DGC_DE_01

    [ext]
    basicConstraints = critical, CA:TRUE, pathlen:0
    keyUsage = critical, cRLSign, keyCertSign
    subjectKeyIdentifier = hash

##### Certificate generation

Open a command line prompt in the folder where the sca.conf is located and use the following OpenSSL command to create the private key (CAprivkey.key) and the certificate (CAcert.pem):

    openssl req -x509 -new -days 1461 -newkey ec:<(openssl ecparam -name prime256v1) -extensions ext -keyout CAprivkey.key -nodes -out CAcert.pem -config sca.conf

#### DSC generation example

Document Signer Certificates (DSCs) must be signed by the SCA. Hence, you have to create the SCA certificate (with the corresponding private key) before you can issue DSCs.

##### DSC.conf

Create a new file called DSC.conf in the folder where your CA's private key is located and add the following fields:

    [ext]
    keyUsage = critical, digitalSignature
    subjectKeyIdentifier = hash
    authorityKeyIdentifier = keyid:always
    crlDistributionPoints = URI:http://crl.exampledomain.example/CRL/SCA.crl
    extendedKeyUsage = 1.3.6.1.4.1.1847.2021.1.1,1.3.6.1.4.1.1847.2021.1.2,1.3.6.1.4.1.1847.2021.1.3

It is recommended that a SCA provides certificate revocation lists. Therefore, replace the crlDistributionPoints URI with the information for your jurisdiction.
The extendedKeyUsage field is optional and can be used to further restrict the DSC certificate as follows:

Field | Value
--- | ---
extendedKeyUsage | 1.3.6.1.4.1.1847.2021.1.1 for Test Issuers
extendedKeyUsage | 1.3.6.1.4.1.1847.2021.1.2 for Vacination Issuers
extendedKeyUsage | 1.3.6.1.4.1.1847.2021.1.3 for Recovery Issuers

The above example contains all three extended key usages.

##### Create a certificate signing request (CSR)

In order to create a certificate for a Document Signer, first create a Certificate Signing Request preferably on the maschine that will use the certificate in order to avoid copying the private key (DSC01privkey.key) to this maschine later. The CSR must contain the Distinguished Name (DN) information that will be included in the DSC. Open a command prompt and use the following command to create the CSR:

    openssl req -newkey ec:<(openssl ecparam -name prime256v1) -keyout DSC01privkey.key -nodes -out DSC01csr.pem

If needed, you can repeat this procedure to create multiple CSRs for different DSCs (on different maschines). When prompted, enter the necessary information (e.g. C= your jurisdicion (MUST), O = your Organisation (OPTIONAL), CN = non-empty and unique CN (MUST), …).

##### Issue the certificate

Copy the CSR (DSC01csr.pem) to the folder where the private key of your CA is located. Open a command prompt and use the following command to issue the DSC (DSCcert.pem):

    openssl x509 -req -in DSC01csr.pem -CA CAcert.pem -CAkey CAprivkey.key -CAcreateserial -days 730 -extensions ext -extfile DSC.conf -out DSCcert.pem

#### TNPUP generation example

##### uploadCert.conf

Create a new file called uploadCert.conf and replace the dn entries with your jurisdiction's details.

    [req]
    prompt = no
    default_md = sha256
    distinguished_name = dn

    [dn]
    C = DE
    ST = NRW
    L = Bonn
    O = MinistryOfTest
    OU = DGCOperations
    CN = NationX_TNPUP

    [ext]
    keyUsage = critical, digitalSignature

##### Certificate generation

Open a command line prompt in the folder where the uploadCert.conf is located and use the following OpenSSL command to create the private key (TNP_UP.key) and the certificate (TNP_UP.pem):

    openssl req -x509 -new -days 365 -newkey ec:<(openssl ecparam -name prime256v1) -extensions ext -keyout TNP_UP.key -nodes -out TNP_UP.pem -config uploadCert.conf

#### TNPTLS generation example

##### TLSClient.conf

Create a new file called TLSClient.conf and replace the dn entries with your jurisdiction's details.

    [req]
    prompt = no
    default_md = sha256
    distinguished_name = dn

    [dn]
    C = DE
    ST = NRW
    L = Bonn
    O = MinistryOfTest
    OU = DGCOperations
    CN = NationX_TNP_TLS

    [ext]
    keyUsage = critical, digitalSignature
    extendedKeyUsage = clientAuth

NOTE :Beware that self-signed certificates should also contain the key usage Certificate signing (keyCertSign), so that the (self) signature of the certificate can be verified.

    [ext]
    keyUsage = critical, digitalSignature, keyCertSign
    extendedKeyUsage = clientAuth

##### Certificate generation

Open a command line prompt in the folder where the TLSClient.conf is located and use the following OpenSSL command to create the private key (TNP_TLS.key) and the certificate (TNP_TLS.pem):

    openssl req -x509 -new -days 365 -newkey ec:<(openssl ecparam -name prime256v1) -extensions ext -keyout TNP_TLS.key -nodes -out TNP_TLS.pem -config TLSClient.conf

### RSA Public Key Certificates

In case you want to use RSA certificates you can still use the configuration files provided above. During the CSR/certificate creation, replace the `-newkey ec:<(openssl ecparam -name prime256v1)` with `-newkey rsa:4096` for a 4096 Bit RSA key.
Please be aware that RSA is NOT RECOMMENDED for the DSC and if you want to use RSA as your document signing algorithm, please create either a 2048 bit RSA key or at maximum a 3072 bit RSA key due to the space limitations on the QR codes.

### Appendix A: Further example configuration files

The following configuration files have been provided during the alignment on the certificate governance. The configuration files contain additional fields that a Trust Network Participant might want to include and use. The config-files are not tested with the OpenSSL commands provided above.

#### SCA Conf

    [ sca_ext ]
    basicConstraints        = critical,CA:true,pathlen:0
    keyUsage                = critical,keyCertSign,cRLSign
    subjectKeyIdentifier    = hash
    authorityKeyIdentifier  = keyid:always
    issuerAltName           = dirName:dir_sect
    subjectAltName          = dirName:dir_sect
    crlDistributionPoints   = URI:http://crl.publichealth.xx/CRLs/XX-Health.crl
    2.5.29.16               = ASN1:SEQUENCE:CAprivateKeyUsagePeriod

    [ CAprivateKeyUsagePeriod ]
    notBefore               = IMPLICIT:0,GENERALIZEDTIME:$ENV::PRIV_KEY_START
    notAfter                = IMPLICIT:1,GENERALIZEDTIME:$ENV::CA_PRIV_KEY_END

    [dir_sect]
    L=XX

#### DSC conf

    [ document_signer_all_ext ]
    keyUsage                = critical,digitalSignature
    subjectKeyIdentifier    = hash
    authorityKeyIdentifier  = keyid:always
    subjectAltName          = dirName:dir_sect
    issuerAltName           = dirName:dir_sect
    crlDistributionPoints   = URI:http://crl.npkd.nl/CRLs/NLD-Health.crl
    extendedKeyUsage        = 1.3.6.1.4.1.1847.2021.1.1,1.3.6.1.4.1.1847.2021.1.2,1.3.6.1.4.1.1847.2021.1.3
    2.5.29.16               = ASN1:SEQUENCE:DSprivateKeyUsagePeriod

    [ document_signer_test_ext ]
    keyUsage                = critical,digitalSignature
    subjectKeyIdentifier    = hash
    authorityKeyIdentifier  = keyid:always
    subjectAltName          = dirName:dir_sect
    issuerAltName           = dirName:dir_sect
    crlDistributionPoints   = URI:http://crl.npkd.nl/CRLs/NLD-Health.crl
    extendedKeyUsage        = 1.3.6.1.4.1.1847.2021.1.1
    2.5.29.16               = ASN1:SEQUENCE:DSprivateKeyUsagePeriod

    [ document_signer_vaccinations_ext ]
    keyUsage                = critical,digitalSignature
    subjectKeyIdentifier    = hash
    authorityKeyIdentifier  = keyid:always
    subjectAltName          = dirName:dir_sect
    issuerAltName           = dirName:dir_sect
    crlDistributionPoints   = URI:http://crl.npkd.nl/CRLs/NLD-Health.crl
    extendedKeyUsage        = 1.3.6.1.4.1.1847.2021.1.2
    2.5.29.16               = ASN1:SEQUENCE:DSprivateKeyUsagePeriod

    [ document_signer_recovery_ext ]
    keyUsage                = critical,digitalSignature
    subjectKeyIdentifier    = hash
    authorityKeyIdentifier  = keyid:always
    subjectAltName          = dirName:dir_sect
    issuerAltName           = dirName:dir_sect
    crlDistributionPoints   = URI:http://crl.npkd.nl/CRLs/NLD-Health.crl
    extendedKeyUsage        = 1.3.6.1.4.1.1847.2021.1.3
    2.5.29.16               = ASN1:SEQUENCE:DSprivateKeyUsagePeriod

    [ DSprivateKeyUsagePeriod ]
    notBefore               = IMPLICIT:0,GENERALIZEDTIME:$ENV::PRIV_KEY_START
    notAfter                = IMPLICIT:1,GENERALIZEDTIME:$ENV::DS_PRIV_KEY_END