DDCCGW-651 -Enhance Documentation in praticipant template repo - smart-trust_README_NEW.md

README_NEW.md

@@ -114,13 +114,16 @@ This repository contains the template for building [onboarding](https://github.c
 **Certificate Preperation**
 	> Disclaimer: The script generates self-signed certificates not intended to be used on production environments.
 
-	You must adapt the following default certificate parameter in gen_all_certs.sh to your needs:
+	You must adapt the following default certificate parameter of [DN_template.cnf](https://github.com/WorldHealthOrganization/tng-participant-template/blob/main/scripts/certgen/DN_template.cnf) file which will used  in gen_all_certs.sh to your needs:  
 	```
-	export OSSL_COUNTRY_NAME="XA"
+	# Configuration Template for Certificate Generation
+	# Modify for your own needs
+
+	export OSSL_COUNTRY_NAME="XC"
 	export OSSL_STATE_NAME="Test State"
-	export OSSL_LOCALITY_NAME="Geneva"
+	export OSSL_LOCALITY_NAME="TEST"
 	export OSSL_ORGANIZATION_NAME="WHO"
-	export OSSL_ORGANIZATIONAL_UNIT_NAME="R&D"
+	export OSSL_ORGANIZATIONAL_UNIT_NAME="RND"
 
 	```
 	> Note: OSSL_COUNTRY_NAME should be ISO 2 letter name of the country mapped to the name used in repository.
@@ -155,11 +158,15 @@ This repository contains the template for building [onboarding](https://github.c
    	- TLS.pem -> onboarding/DCC/TLS
 
 	**Note** On DEV and UAT environment, if the files are generated using a script, delete the generated folder before committing the files.
-
 
-- For Prod
-**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.
+
+  **For ProductionConcepts 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. 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](#steps-to-obtain-and-use-a-ca-signed-certificate)
+
+
 
 	### Elliptic Curve Public Key Certificates (ECDSA with NIST-p-256)
 	#### SCA certificate (TNP~SCA~) generation example:
@@ -186,11 +193,15 @@ This guide follows the certificate templates defined in the certificate governan
 	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):
+**For Prod to use** [Trusted CA issued  Certificated](#steps-to-obtain-and-use-a-ca-signed-certificate) **recommended,**  As below command for self-siged certificate generation as it's usually only recommened for DEV/UAT enviornment.
+
 	```
 	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.
 
@@ -214,6 +225,8 @@ extendedKeyUsage &emsp; 1.3.6.1.4.1.1847.2021.1.2 for Vacination Issuers\
 extendedKeyUsage &emsp; 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 machine that will use the certificate in order to avoid copying the private key (DSC01privkey.key) to this machine 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:
 	```
@@ -222,10 +235,14 @@ The above example contains all three extended key usages.
 	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
 	```
+  **Important Recommendations for Prod**: Please replace your CAcert.pem and CAprivkey.key which issued by your public Trusted Certificate Authority (CA) insterad of self-signged one.
+
 	#### TNP~UP~  generation example
 	##### uploadCert.conf
 	> Please check [UP Creation](https://github.com/WorldHealthOrganization/smart-trust/releases/download/v1.1.1/1.1.full-video.UP.v2.mp4)  video for reference
@@ -531,4 +548,303 @@ Please be aware that RSA is NOT RECOMMENDED for the DSC and if you want to use R
 8. Send an onboarding/participation request to [email protected] which contains:
 - URL of the private repository created as a prerequisite
 - The GPG key exported in Step 4
-
+
+Once you recieve confirmation on sucesfull onboarding from TNG Support Team ( [email protected]) 
+
+After onboarding in the DEV/UAT/Pro Environment, check the connectivity with the Trust Network Gateway using its API. This can be acheived with following command:
+
+TNG-WHO Endpoints:
+-	PRD:	 https://tng.who.int
+-	UAT:	 https://tng-uat.who.int
+-	DEV:	 https://tng-dev.who.int
+
+
+```
+curl -v https://tng-dev.who.int/trustList --cert TLS.pem --key TLS_key.pem
+```
+You should see a output like:
+
+```
+[
+{
+    "kid": "+jrpHSqdqZY=",
+    "timestamp": "2023-05-25T07:55:21Z",
+    "country": "XC",
+    "certificateType": "UPLOAD",
+    "thumbprint": "fa3ae91d...",
+    "signature": "MIAGCSqGSIb3D...",
+    "rawData": "MIIErTCCA5WgAwIBAgII..."
+}
+]
+```
+4) Test the other Trustlist Routes in the same style (e.g. with DSC/SCA/Upload/Authentication…)
+5) Create an Document Signer Certificate and sign it by the SCA [Refer](https://github.com/arajnor99/smart-trust/blob/main/README_NEW.md#elliptic-curve-public-key-certificates-ecdsa-with-nist-p-256)
+6) Create an CMS Package with the following Command:
+    Note: Step 5 and 6 could be achived through two menthod commandline [Commandline reference](#dsc-generation-example)
+ and script respectively .
+
+**Method 1 - Commandline .**
+```
+openssl x509 -outform der -in cert.pem -out cert.der
+openssl cms -sign -nodetach -in cert.der -signer signing.crt -inkey signing.key -out signed.der -outform DER -binary
+openssl base64 -in signed.der -out cms.b64 -e -A
+
+```
+**Note**: cert.der is your DSC, signing.crt is the TNPUP.
+
+**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](https://github.com/WorldHealthOrganization/tng-participant-template/tree/main/scripts/certgen#generate-dscs)
+
+[Upload DSCs](https://github.com/WorldHealthOrganization/tng-participant-template/tree/main/scripts/certgen#upload-dscs0)
+
+The Distinguised Nmae ( DN) configuration file while will parse as source  [DN_template.cnf](https://github.com/WorldHealthOrganization/tng-participant-template/blob/main/scripts/certgen/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.
+
+**Howto to run DSC Generate Script** [gen_dsh.sh](https://github.com/WorldHealthOrganization/tng-participant-template/blob/main/scripts/certgen/gen_dsc.sh)
+
+``` 
+./script_name.sh DN_template.cnf directory_of_SCA_files [test/vax/rec-purpose}
+
+```
+**How to run upload.sh script:**
+
+./upload_dsc.sh: Replace this with the actual name of your script.
+
+/path/to/subdir: Path to the directory containing UP.pem and UP.key.
+
+/path/to/DSC_dir: Path to the directory containing the DSC files (DSC.pem, DSC.key).
+
+DCC: The domain name to be used. If omitted, the script will default to DCC.
+```
+./upload_dsc.sh /path/to/subdir-up_pem_key  /path/to/DSC_dir [DCC]
+```
+
+7) Check DSC is already exist before upload CMS package
+```   
+curl -v https://tng-dev.who.int/trustList/DSC/XC --cert TLS.pem --key TLS.key
+```
+9) Upload the CMS Package to the Gateway
+```    
+curl -v -X POST -H "Content-Type: application/cms" --cert TLS.pem --key TLS_key.pem --data @cms.b64 https://tng-dev.who.int/signerCertificate
+
+```
+11) Download the Trustlist again, and check if your DSC is available.
+```   
+curl -v https://tng-dev.who.int/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/):
+
+
+
+
+
+
+
+=======================================================================
+# Certificate Renewal Procedures
+
+=======================================================================
+
+## 1. **Renewing TLS Certificates**
+
+The TLS, UP and SCA certificate renewal proces is same as fresh new TLS/UP/SCA certfication generation during fresh new full onboarding you had followed . Once you get notified by TNG Support Team prior 30 days by E-mail communication on certificate expiration, so accordinlgy you have to renew your respective certificate(s) .
+
+**Validity periods**
+Digital certificates contain a validity period that enforces certificate renewal. Renewal is necessary to use fresh cryptographic keys and to adapt the key sizes when improvements in computation or new attacks threaten the security of the cryptographic algorithm that is used. The shell model applies (see Section “Signing Certificate Authorities and Validation Model”). The following validity periods are recommended based on the assumption of the one-year maximum validity for Verifiable Digital Health Certificates :
+
+SCA: 4 years
+DSC: 2 years
+Upload: 1-2 years
+TLS Client authentication: 1-2 years
+For a timely renewal, the following usage period for the private keys are recommended:
+
+SCA: 1 year
+DSC: 6 months
+GDHCN Participants MUST create new upload certificates and TLS certificates timely, e.g. one month, before expiration in order to allow smooth operation. SCA and DSC SHOULD be renewed at least one month before the private key usage ends (considering the necessary operational procedures). GDHCN Participants MUST provide updated SCA, upload and TLS certificates to the GDHCN Secretariat.
+
+
+
+### For Production Environment:
+
+### **Renewing UP (TLS Certificates)**
+1. **Create TLS Configuration File (`TLSClient.conf`):**
+
+    ```plaintext
+    [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, keyCertSign
+    extendedKeyUsage = clientAuth
+    ```
+
+2. **Generate New Private Key and Certificate:**
+
+    ```bash
+    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
+
+    ```
+
+## 2. **Renewing UP (Upload Certificates)**
+
+### For Production Environment:
+1. **Create UP Configuration File (`uploadCert.conf`):**
+
+    ```plaintext
+    [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
+    ```
+
+2. **Generate New Private Key and Certificate:**
+
+    ```bash
+    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
+    ```
+
+## 3. **Renewing SCA (Signing Certificate Authority)**
+
+### For Production Environment:
+1. **Create SCA Configuration File (`sca.conf`):**
+
+    ```plaintext
+    [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
+    ```
+
+2. **Generate New Private Key and Certificate:**
+
+    ```bash
+    openssl req -x509 -new -days 1461 -newkey ec:<(openssl ecparam -name prime256v1) -extensions ext -keyout CAprivkey.key -nodes -out CAcert.pem -config sca.conf
+
+
+    ```
+
+## General Notes:
+- Make sure to replace configuration file details with your specific information.
+- Ensure to back up any existing certificates before renewing.
+- Verify and update any configurations or deployment settings to use the new certificates.
+- Self-signed certificates are generally used for DEV and UAT environments. **For production**, use certificates signed by **Trusted Certificate Authority(CA).**
+
+
+
+
+## Git Commit and Tag Push
+
+### General Steps for Committing and Tagging Renewed Certificates:
+
+1. **Add the renewed certificate to Git:**
+
+    ```bash
+    git add path/to/renewed-certificate.pem
+    ```
+
+2. **Commit the changes:**
+
+    ```bash
+    git commit -m "Add renewed certificate"
+    ```
+
+3. **Push the changes to the main branch:**
+
+    ```bash
+    git push origin main
+    ```
+
+4. **Tag the commit with an appropriate version:**
+
+    ```bash
+    git tag -a v1.3 -m "Renewed certificate"
+    ```
+
+5. **Push the tag to the remote repository:**
+
+    ```bash
+    git push origin v1.3
+    ```
+
+Feel free to adjust the file names and tags as needed for your specific context.
+
+Once you done with nrewal of your certificates(s) then inform TNG-Support Team by email 
+
+
+
+## Steps to Obtain and Use a CA-Signed Certificate
+
+**1. Generate a Certificate Signing Request (CSR)**
+To begin, generate a CSR using the following OpenSSL command. This request will include a new private key and a configuration file:
+
+```
+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.
+C**Areq.csr:** This file contains the Certificate Signing Request.
+**sca.conf:** This is the OpenSSL configuration file used during the CSR generation.
+
+**2. Submit the CSR to a Public Certificate Authority (CA)**
+Submit the generated CAreq.csr file to the public CA of your choice. The CA will use this CSR to issue a certificate. Upon approval, the CA will provide you with:
+
+**2. Submit CSR to the Public CA**
+Submit the generated CAreq.csr file to the public CA of your choice. They will use the CSR to issue a certificate. The CA will provide you with the signed certificate and possibly a certificate chain or intermediate certificates.
+
+**3. Use the CA-Signed Certificate**
+Once you receive the CA-signed certificate, you will use it instead of generating a new self-signed certificate. Here’s how you can replace the placeholders with the signed certificate:
+cp signed_CA_cert.pem ${subdir}/CAcert.pem 
+cp CAprivkey.key ${subdir}/CAprivkey.key
+
+
+
+
+
+
+