Onboarding Checklist

This repository contains the a checklist for onboarding the Trust Network Participants. This includes CSCAs, Auth information, signing information and other relevant files for onboarding a participant. Videos guides to the steps described here are available on this page.

Onboarding Process

Onboarding Process

Prerequisites for Onboarding

Before beginning the onboarding process, please ensure the following tools, permissions, and environment configurations are in place. This checklist is crucial for a seamless setup experience.

Tools/RequirementDescription
GitHub Account - Ensure you have an active GitHub account with access to the relevant repositories.
- Permissions: Confirm the necessary repository permissions (read/write access if required for pushing commits).
OpenSSL - Required for generating and managing digital certificates.
- Minimum Version: 1.1.1 or higher.
- Verify: openssl version.
- Path Configuration: Ensure OpenSSL is correctly added to the system path.
- Download OpenSSL
cURL - Necessary for command-line data transfers, especially useful for API requests.
- Minimum Version: 7.68.0 or higher.
- Verify: curl --version.
- Download cURL
Git - Essential for version control and interacting with GitHub repositories.
- Minimum Version: 2.28.0 or higher (recommended for improved configuration capabilities).
- Verify: git --version.
- Download Git
GPG - Gnu Privacy Guard - Essential for singing you git tags in your private repository.
- Minimum Version: 2.2 - 2.4 any fewer version is outdated.
- Verify: gpg --version.
- Download GPG
Text Editor or IDE (Optional) - Use a reliable text editor or IDE such as Visual Studio Code, Sublime Text, or Notepad++ for editing files.
- Extensions: If using VS Code, consider adding extensions for Markdown and GitHub integration.
- Download Visual Studio Code
Network and Firewall Permissions - Network Access: Ensure network settings allow access to GitHub and other required external resources (e.g., API endpoints).
- Firewall Permissions: Verify firewall permissions to avoid connectivity issues.
CLI Tools and Path Configuration - Confirm that all tools (e.g., openssl, curl, git) are available in the system PATH for easy command-line access.
- OS Compatibility: These instructions are applicable for Linux, macOS, and Windows.
Environment Configuration - Environment Variables: Set required environment variables (e.g., API keys, tokens, or paths) as specified.
Additional Resources and Documentation - Familiarize yourself with supplementary documentation, including API references, security guidelines, and data handling policies needed for the onboarding process.

Save For Later: Be sure to securely save items like GPG Keys, Secrets, GitHub usernames, GitHub Repository URL, GitHub PAT (Personal Access Token), and other configurations as they will be needed in upcoming steps.

Steps to Be Followed by Participant Country:

Git Repository

Create a private git repository on github. One for each Environment (DEV, UAT, PROD)

Please check Create private repository video for reference

Save For Later: Be sure to securely save items like GitHub usernames, and Repository Name, URL as they will be needed in upcoming steps.

Create PAT (Personal Access Token) for Github account if not created already

Save For Later: Be sure to securely save the GitHub PAT (Personal Access Token), as it will be needed in upcoming steps.

Local Repository

Invite tng-bot

Generate GPG Key

Create Certificates

Certificate Preparation for DEV and UAT

Disclaimer: This script is designed to create self-signed certificates solely for non-production environments, such as DEV and UAT, not intended to be used on production environments. To use it, choose the appropriate script for your operating system:

Unix/Linux: Use the gen_all_certs.sh bash script on Linux/Unix/Mac operating system.

Windows: Use the gen_all_certs.ps1 PowerShell script on Windows operating system.

These scripts, along with the provided configuration files, serve as guidelines for certificate preparation .

If your Operating Systems is Unix/Linux/Mac
export OSSL_COUNTRY_NAME="XC"
export OSSL_STATE_NAME="Test State"
export OSSL_LOCALITY_NAME="TEST"
export OSSL_ORGANIZATION_NAME="WHO"
export OSSL_ORGANIZATIONAL_UNIT_NAME="R&D"
export OSSL_COMMON_NAME="NationXC_TNP

Note: OSSL_COUNTRY_NAME should be ISO 2 letter name of the country mapped to the name used in repository.

If your Operating Systems is Windows

For Windows, use the gen_all_certs.ps1 PowerShell script. You can modify the environment variables directly within the script or set them in your current PowerShell session:

1.Open PowerShell on your Windows machine.

2.Set the required environment variables.

$env:OSSL_COUNTRY_NAME="XC"
$env:OSSL_STATE_NAME="Test State"
$env:OSSL_LOCALITY_NAME="TEST"
$env:OSSL_ORGANIZATION_NAME="WHO"
$env:OSSL_ORGANIZATIONAL_UNIT_NAME="RND"
$env:OSSL_COMMON_NAME="NationXC_TNP"

Note: OSSL_COUNTRY_NAME should be ISO 2 letter name of the country mapped to the name used in repository.

Please note that you need to have OpenSSL installed (e.g. Win64 OpenSSL v3.3.0 Light) and added to your PATH environment variable. Also you may need allow the execution by setting an execution policy.

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
How to Run Script :
**For Mac/Linux/Unix**
cd scripts/certgen
./gen_all_certs.sh DN_template.cnf	    ## Provide DN_template.cnf file as a script argument.
zsh ./gen_all_certs.sh DN_template.cnf      ## Use this if you are using Zsh on your Ubuntu system.
        
**For Windows:**
cd scripts/certgen
./gen_all_certs.ps1

This setup generates all required certificates (TLS, SCA, UP) and keys in a timestamped subfolder, based on the configuration specified in DN_template.cnf for Unix/Linux and the environment variables set in the current PowerShell session for Windows.

Prepare Folders

Note: keep your private keys safe and secure. Do not share them with anyone.

Copy the generated certificates to the respective folders and change the file names to match the naming convention. For the case of self-signed TLS certificates, the CA.pem is just a copy of the TLS.pem (check to have keyCertSign in the keyUsage). The CA.pem should exist, since it is used to verify the TLS client certificate when connecting to the TNG application. Files to be copied in respective folders are as follows:

Note: On DEV and UAT environment, if the files are generated using a script, delete the generated folder before committing the files.

Certification Preparation for Prod

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.Self-signed certificates are typically used in DEV and UAT environments.

For production, It is strongly recommended to use certificates signed by a trusted Certificate Authority (CA). This is just an example reference on how to use a Trusted CA certificate in a production environment. You should refer to the specific procedures provided by the public Trusted Certificate Authority (CA) of your choice for accurate and detailed instructions Reference- Recommendation to use Trusted Public CA Certificate in Prod

Only following signature algoriths are supported for the certificate.

SCA certificate (TNPSCA) generation example

Please check SCA Creation video for reference

DSC generation example

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.

TNPUP generation example
TNPTLS generation example

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.

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

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.

Provide

Please check Signing (tag) certificates video for reference

Everyone Must Sign - Always a good idea Signing tags and commits is great, but if you decide to use this in your normal workflow, you’ll have to make sure that everyone on your team understands how to do so. This can be achieved by asking everyone working with the repository to run git config –local commit.gpgsign true to automatically have all of their commits in the repository signed by default. If you don’t, you’ll end up spending a lot of time helping people figure out how to rewrite their commits with signed versions. Make sure you understand GPG and the benefits of signing things before adopting this as part of your standard workflow.

Send an onboarding/participation request

Validate the connection

THe following are the endpoints for the Trust Network Gateway for each of development (DEV), user-acceptence testing (UAT) and production (PROD) *environments:

EnvironmentEndpointURL
PRODhttps://tng.who.int
UAThttps://tng-uat.who.int
DEVhttps://tng-dev.who.int

Please ensure you replace with your actual environment’s endpoint URL wherever indicated.

Windows Users – cURL Certificate Validation Note:

Windows ships with cURL that uses Schannel, which does not support PKI/KEY certificates. To avoid validation errors, use a cURL build with OpenSSL. Users should check their current version with curl –version and download an OpenSSL-based build if necessary. DownloadLink After extracting, go to the bin folder and verify with ./curl.exe –version (it should show LibreSSL or OpenSSL).

Windows Platform Users Only: Run all below validation commands using ./curl.exe … to ensure the correct SSL backend is used.

curl -v <<EndpointURL>>/trustList --cert TLS.pem --key TLS.key

You should see a output like:

[
{
    "kid": "+jrpHSqdqZY=",
    "timestamp": "2023-05-25T07:55:21Z",
    "country": "XC",
    "certificateType": "UPLOAD",
    "thumbprint": "fa3ae91d...",
    "signature": "MIAGCSqGSIb3D...",
    "rawData": "MIIErTCCA5WgAwIBAgII..."
}
]

Upload DSC Certificate

Method 1 - Command line . Before running the below commands we need DSC certificate : To Generate DSC through command line - Follow section 4.1.1.5.6.2

openssl x509 -outform der -in DSC.pem -out cert.der
openssl cms -sign -nodetach -in cert.der -signer UP.pem -inkey UP.key -out signed.der -outform DER -binary
openssl base64 -in signed.der -out DSC_cms.b64 -e -A

curl -v <<EndpointURL>>/trustList/DSC/XC --cert TLS.pem --key TLS.key

curl -v -X POST -H "Content-Type: application/json" --cert TLS.pem --key TLS.key -H "Accept: application/json" --data '{"cms": "'"$(cat DSC_cms.b64)"'", "properties": {}, "domain": "DCC|IPS-PILGRIMAGE", "group": "DSC|DESC"}' <<EndpointURL>>/trustedCertificate

Note: Replace domain, group, and EndpointURL with the appropriate values for your onboarding environment.

DCC for domain, DSC for group, and https://tng-dev.who.int for DEV environment endpoint.

Example

Example

curl -v <<EndpointURL>>/trustList/DSC/XC --cert TLS.pem --key TLS.key

Method 2 - Scripts

The DSC generation and upload of CMS package to TNG Gateway could be achieved through the below mentioned scripts. For DEV and UAT environments you may use script.

Generate DSCs

Upload DSCs

The Distinguished Name ( DN) configuration file while will parse as source DN_template.cnf is an example.

Please replace with your actual OSSL_COUNTRY_NAME, OSSL_STATE_NAME etc parameters accordingly of DN_template.cnf file.

The script expects at least two arguments: A configuration file (DN_template.cnf) that contains the Distinguished Name (DN) template. A subdirectory where the SCA (Signing Certificate Authority) PEM and KEY files are located. An optional third argument can be provided to specify the purpose of the DSC (e.g., test, vax, rec). If this argument is not provided, the DSC will be generated for all purposes.

How to to run DSC Generate Script gen_dsc.sh

./gen_dsc.sh DN_template.cnf path/to/sca_directory [test/vax/rec-purpose]

./gen_dsc.sh: Script name

/path/to/sca: Create SCA directory which contains SCA.pem and SCA.key

How to run upload_dsc.sh script to upload CMS Package: upload_dsc.sh

./upload_dsc.sh /path/to/subdir  /path/to/DSC_dir [DCC]

./upload_dsc.sh: Script name

/path/to/subdir: Create subdir directory which contains UP.pem and UP.key.

/path/to/DSC_dir: Create DSC_dir directory which contain the DSC.pem.

DCC: The domain name to be used. If omitted, the script will default to DCC.

Important : Once above command executed sucessfully that’s mean your CMS package uploaded to gateway

Check DSC Status

Please replace XC with your actual two letter country code

curl -v <<EndpointURL>>/trustList/DSC/XC --cert TLS.pem --key TLS.key

Note: Some versions of curl don’t attach the client certificates automatically. This can be checked via curl –version Ensure that the used version is linked to OpenSSL. Especially under Windows (https://curl.se/windows/):

Curl version on Unix/Mac: We strongly recommend updating curl and nss to newer latest versions for full compatibility with modern cryptographic standards.The outdated version of curl or nss and may not support modern SSL/TLS protocols or elliptic curve cryptography (ECC) cipher suites properly.

Working Setup

Working Setup

Non-working setup

Non-working setup

Certificate Validation on Grafana: Once the CMS package is uploaded to the gateway, your DSC certificate entry will be reflected in Grafana.

Environment
DEV
UAT
PROD

Appendix

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.

Steps to Obtain and Use a CA-Signed Certificate
openssl req -new -nodes -newkey ec:<(openssl ecparam -name prime256v1) -keyout CAprivkey.key -out CAreq.csr -config sca.conf

CAprivkey.key: This file contains the private key.

CAreq.csr: This file contains the Certificate Signing Request.

sca.conf: This is the OpenSSL configuration file used during the CSR generation.

More information about Git commit, signing and tagging commands

Signing Your Work

Signing Tags

Verifying Tags

Signing Commits

Edit this page on GitHub