This section includes the following:

1. Admin API (swagger)

2. Vaccination API (swagger)

3. Certificate Access API (swagger)

4. Registration API (swagger)

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Version release date

January 24, 2023

Release summary

With this release, the DIVOC platform provides a user interface (UI) for tenants to log into the DIVOC platform to create and manage different tenants and schemas required for issuing verifiable credentials (VCs).

Terminology

A list of the common terms used in this document:

• represent information found in physical credentials, such as birth registration and driving license, as well as objects that have no physical equivalent, such as ownership of a bank account. VCs are typically QR codes whose information is being signed and can only be modified by the issuer making it a tamper-proof QR code. The QR codes can be read and verified by the verifiers using the public key issued by the issuer and by using the libraries/algorithms used by the issuer system. When a digital document (for example, a lab test report) has a normal QR code, anyone can modify its value and generate a new QR code and then replace it with another QR code with different information. Whereas the information in a verifiable QR code cannot be replaced as the original data or information cannot be changed without a “private key.”

• Issuer: Refers to an issuing authority who can issue claims about a particular entity or individual that can be validated. An issuer gathers the information that needs to be contained in the VC from the entities and sends it across to DIVOC through tenant software. Example: Medical Councils.

• Tenant: Refers to any source system of issuers linked to the DIVOC platform to issue VCs. Examples: Council Software, University software, etc.

• Source systems: The tenant software that interacts with the DIVOC platform to issue VCs.

• Schema: A schema is essentially a template that tells the issuer the content, type, and description required for an attribute that needs to be part of the VC.

New Features

Enhancements from the previous platform release

Purpose

The purpose of this document is to provide information about the certificate generation service of DIVOC. It has the following sections:

• Overview of DIVOC’s digital certificates.

• What information is included in the DIVOC digital certificate?

• Certificate generation service: How does it work?

• Compliance with internationally used COVID-19 certificate schemas.

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Version release date

• March 25, 2022.

Release summary

If your country is implementing DIVOC 2.0, it is important to know the additions/changes that we have made as part of this release:

• Configuration management via etcd: You can make configuration changes to DIVOC’s certificate module via etcd without needing a new deployment. Click here to know more.

• Support for EU compliant digital certificates and Smart Health Cards: DIVOC’s EU-DCC and SHC adapter services facilitate easy travel for residents from DIVOC’s adopter countries. Know more about DIVOC’s EU-DCC and SHC adapter services.

• Print certificates at the facility: We have added the capability to print vaccination certificates when a beneficiary walks into a facility. Click here to know more.

• New API for revocation services: A new Revoke API has been introduced that can be used to revoke an issued certificate for manual revocation use cases. Click here to know more.

• Deployment activities automated reducing installation time:

- Automating our infrastructure setup has reduced our deployment time from about 3 days to 1 day.

- DIVOC’s installation process has been streamlined with the introduction of the new scripts. The details of the scripts are given below:

1. Install the prerequisites and set up the various hardware clusters.

2. Push the docker images to the appropriate registry.

3. Deploy the code from the registry into the Kubernetes cluster.

• Enhanced performance of PDF certificate generation: We have fine-tuned our PDF generating algorithms, which has lowered the consumption of system resources.

DIVOC’s W3C-based digital certificate consists of three core components:

1. Credential metadata (schema version credential/certificate ID, etc).

2. Claim (vaccination event details).

3. Proof (issuer details, date of issue, time stamp, signature, etc).

Data structure

The DIVOC digital certificate QR code includes the following data structure:

Sample certificate payload

To illustrate the data structure of DIVOC certificate outputs, a sample certificate payload is outlined below:

This section covers the following:

• Certificate generation process

• Certify APIs

• API structure

Certificate generation process

It involves the following steps:

• Recording of a health event against a unique beneficiary, either in the source eHealth system (or in the DIVOC vaccination module, if used by a country, for their vaccination campaign). This results in the creation of the dataset for the specific event.

• The event records all transactions associated with it (e.g. beneficiary demographics, vaccinator/facility details, certificate metadata, and timestamp, among others).

• Marking the completion of the "event" in the system triggers a DIVOC certificate generation API (or “Certify” API), with the event data populated as per the defined API structure.

• DIVOC’s certificate module receives the event data.

• A digital certificate, encompassing both a QR code and a human readable document (e.g. PDF) is then issued, which holds the event data for the beneficiary, along with a unique certificate ID.

• The QR code is signed with the issuing authority (e.g. national/provincial health agency) private key.

• A summary of the health event is then used to populate the “human readable” part of the digital certificate.

Output

The generated output has two parts:

• It has a human-readable document (e.g. the PDF) and the machine-readable QR (the signed QR).

• The digital certificate can be presented back to the source system in either of the ways (i.e. either just the signed QR as an image file, or the entire PDF output with the signed QR).

Sample

A sample DIVOC certificate output is further illustrated in the image below:

Certify APIs

The DIVOC certificate generation service provides a “Certify” API for other eHealth systems, to generate digital certificates for specific events. Currently, DIVOC provides two certify APIs for a “COVID-19 vaccination certificate” and “COVID-19 test result certificate” respectively.

API structure

The API structure for the Certify API includes the following:

1. Recipient information: This section contains information about the beneficiary of the specific health event (e.g. COVID-19 vaccination or test event).

2. Vaccination event information: This includes details about the vaccination event such as name, batch, and vaccination date, as well as the vaccinator.

3. Issuer information: It contains information about the issuing authority.

4. Certificate information: It includes details such as certificate ID and expiry date, among others.

5. Meta: This part is used to populate related information about a previous event in the human-readable PDF twin of the digital certificate that can be used by the verifier for cross-reference. It contains additional information, which is not part of the current QR code (the QR code only contains information about the current event), such as the number of past doses taken. For example, If a QR code is generated for the final dose certificate, the QR code will contain all information about the final dose. If a country wants to show information about the previous dose, that can be populated from meta in the certificate PDF.

Purpose

The guide covers everything developers need to know to set up and run DIVOC on their local machines.

What will it cover?

• API documentation

• Setting up DIVOC development environment

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Digitally verifiable certificates have emerged as a solution to help open up businesses and travel globally during the ongoing COVID-19 pandemic. There are four major COVID-19 certificate schemas popularly used in the world today:

• ICAO-VDS

As the interoperability of these certificate schemas is critical to streamline the international travel process, DIVOC has added the ability to issue digital certificates in the EU-DCC and SmartHealthCard formats, in addition to the . This will enable citizens of a country, which is using a DIVOC certificate system, to export their native certificates in a format that is acceptable in the travel destination country.

Note: DIVOC will also add the capability to export the certificates in the ICAO-VDS format in 2022.

All content on this page by is licensed under a .

Release notes for supported versions are given below:

• (on-demand EU-DCC and FHIR-DDCC export)

• (minor enhancements and UI fixes)

• (bug fixes and enhancements)

• (UI enhancements and bug fixes)

• (secondary dosage flows and design enhancements)

• (minor enhancements and UI fixes)

• (design enhancements and bug fixes)

• (facility application enhancements)

• (minor enhancements and bug fixes)

• (minor enhancement on appointment)

• (registration and appointment)

• (generic) and

All content on this page by is licensed under a .

This will cover the following:

• Running DIVOC on a local machine

• DIVOC walkthrough

Running DIVOC on a local machine

Steps

Step 1: Install prerequisites and dependencies

• Update package list - sudo apt-get update.

• Install docker - sudo apt install docker.io.

• Install docker-compose - sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose.

• Install git - sudo apt install git.

• For additional details on Docker, you can find the instructions here.

• You can find the basic Docker Compose commands below:

- Starting services docker-compose up.

- Restarting services docker-compose restart.

- Checking the status of services docker-compose ps.

- Monitoring service logs docker-compose logs.

Step 2: Install DIVOC

• Clone DIVOC repository onto your local machine - git clone https://github.com/egovernments/DIVOC.

• Navigate to DIVOC directory - cd DIVOC.

• Configure DIVOC: Configurations are provided as environment variables and a default set of configurations is provided in the ‘.env.example’ file. Make a copy of this file named ‘.env’ that docker will pick up. Edit these configurations as per your need.

   'cp .env.example .env'

Step 3: Start all services in the detached mode.

docker-compose up -d

• Verify the state of containers. All containers should be up.

• Some services might fail to start because the dependent service may not be ready yet. Restarting the failed service should start it successfully in this case.

• On Mac/Windows, services may crash with exit code:137, if sufficient memory is not set for docker. This can be changed in the Docker desktop preferences, resources tab, as shown here.

Step 4: To build docker images locally after making changes, run following commands

make docker
make docker docker-compose up -d

Step 5: Explore DIVOC

• The following are the routes to access local apps. The remaining routes can be found in nginx/nginx.conf.

DIVOC walkthrough

In this section, we will go through the steps involved in a typical flow, starting from setting up facilities to generating a certificate after vaccination.

Set up Keycloack

• Login to keycloak console (localhost/auth/admin) as admin (password : admin)

• Hover on Master on the left top corner and click on Add realm.

• Click on the Select File button (import option).

• Select realm-export.json in the keycloak directory. path:DIVOC/keycloak.

• Click on create.

Set up CLIENT_SECRET for admin-api

• Login to the keycloak console (localhost/auth/admin) as admin (password:admin).

• Click on Clients in the configure section on the left pane and click on admin-api.

• Go to the credentials tab, click on Regenerate Secret and copy the new secret.

• Change the ADMIN_API_CLIENT_SECRET to the copied secret in docker-compose.yml.

• Rebuild and restart the services that use ADMIN_API_CLIENT_SECRET.

docker-compose up -d --build --no-deps <service1> <service2>...
 docker-compose restart nginx

“For example - sudo docker-compose up -d --build --no-deps certificate-processor portal-api certificate-api gateway.

DIVOC application configuration

DIVOC uses etcd as a configuration store for templates and other configurations. A default set of configurations is available in the default-configuration/etcd folder. The instructions to configure these are available here.

Create admin and controller users in Keycloak

• Login to the keycloak console (localhost/auth/admin) as admin (password : admin).

• Click on Users in the Manage section on the left panel and click on Add User.

• Give the username as 0000000000 and click on save.

• In the Attributes section, add a new key as mobile_number and value as 0000000000. Click on Add and save.

• Go to the Groups section, select system admin in the available groups and click on Join.

• Similarly, create another user with username and mobile_number as 0000000001 and join the controller group.

System admin activities

Login to the portal as system admin (Mobile Number : 0000000000, OTP : 1234).

Upload Facilities.csv:

• Click on the Facilities tab and click on Download Template .csv.

• Click on Upload CSV button and upload the downloaded csv.

• You should see the success message for a facility.

Create a vaccine:

• Click on the Vaccines tab. Fill in all the fields on the form, mark the status as Active and click on save.

• You should see the new vaccine on the right pane in the list of registered medicines/vaccines.

Create a vaccination program:

• Click on the Vaccine Program tab. Fill in all the fields on the form, mark the status as Active, and click on save.

• You should see the new vaccine program on the right pane in the list of registered vaccine programs.

Pre-enroll recipients:

• Click on the Pre-Enrollment tab and click on Downloaf Template .csv

• Click on Upload CSV and upload a CSV file containing all the fields given in the template.

• You should see the number of recipients successfully enrolled and errors if there are any.

Controller activities

Login to the portal as controller (Mobile Number: 0000000001, OTP: 1234).

Activate facilities for vaccination program:

• In the Facility Activation tab, select the vaccination program added in the previous step, select the type of facility as government and mark the status as Active.

• You should be able to see at least one facility in the search results.

• Click on the checkbox for the relevant facility (make note of facility code) and click on MAKE ACTIVE.

• The activated facility should disappear from the search results.

Facility admin activities

Get admin mobile number for the facility code (noted in the previous step), from the facilities.csv uploaded.

Login to Facility Admin portal (localhost/portal/facility_admin) using the mobile number and OTP: 1234.

Add facility_staff user:

• Click on the Role Setup tab and click on the add role icon.

• Create a role with type facility staff and mobile number 1111111111. Set the status as enabled and set the rate of 50 for the vaccination program.

Add Vaccinators:

• Click on Vaccinator Details tab and Click Add Vaccinator.

• Fill in all the details. Select the vaccination program previously created in the certification dropdown.

• Click on Add and click on Back.

• Click on the Make Active button to activate the vaccinator.

Bulk Certification:

• Certificates can also be issued in bulk by the facility admin by uploading a CSV file.

• Go to the Upload Vaccination details tab and click on the download CSV template button.

• Now upload a CSV file, containing all the fields in the template.

• The generated certificates can be viewed on the public app (localhost).

Facility staff activities

Login to the Facility app (localhost/facility_app) (Mobile Number: 1111111111, OTP: 1234).

Enrolling and certifying recipients:

• Click on enrol recipient, fill all the details and proceed.

• Click on Recipient Queue, to proceed for certification.

Certifying pre-enrolled recipients:

• Recipients pre-enrolled by facility admin can be certified by the facility staff.

• Go to the app home and click on Verify Recipient to proceed for vaccination.

Recipient activities

• In the public app (localhost), recipients can:

  • Download/ vaccination certificates

  • Verify certificates by scanning a QR code

  • Report any side effects/symptoms after vaccination

• For the above operations, you need the recipient mobile number (given during pre-enrollment/vaccination). Use OTP: 1234 for all logins.

Deployment note

Change the admin password of Keycloak console

• Go to the admin console, click on the Admin menu in the top right corner and select Manage account.

• Change the password in the password section on the right.

This section will include the following:

• Release notes

• Specification

• Features

• Architecture

• Installation

• Configuration

• Performance report

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Purpose

This section describes the key features of DIVOC and how they work.

What is DIVOC's issue and verify certificate module?

• Countries can use the DIVOC's certificate module to issue digitally verifiable certificates to the entire population at speed and scale in a controlled manner post-vaccination.

• This module is responsible for issuing a QR code-based digital certificate for any registered health event. It can be adapted to other areas too where there is a requirement for secure and tamper-proof documents, such as educational certificates.

• The certificates can be issued in both digital and physical forms, which includes print, pdf, and other formats.

• The module supports multilingual vaccination certificate templates.

• Generates WHO-DDCC (World Health Organisation- Digital Documentation of COVID-19 Certificates) compliant digital vaccination certificates with a W3C (World Wide Web Consortium) JSON schema, for every resident after successful inoculation.

• To aid travel into other countries, the certificate module supports on-demand services for travellers to export their vaccination certificates to other formats (e.g. EU-DCC, SmartHealthCard), used in the destination countries.

• The module supports additional services, including certificate verification, certificate update/correction, and certificate revocation.

• The public key of the adopter country can be published using DIVOC’s verification page that can be embedded into the country's vaccination program-specific website/portal.

What will it cover?

• Creating a DIVOC certificate

• Distributing a DIVOC certificate

• Verifying a DIVOC certificate

• Updating a DIVOC certificate

• Revoking a DIVOC certificate

• DIVOC's native COVID-19 certificate specification

• DIVOC's EU-DCC adapter service

• DIVOC’s SHC Adapter Service

• Difference between a normal QR code (that you may see on a food menu) and a verifiable QR code (for example, DIVOC's QR-code based digital certificates).

• What information goes into a QR code?

• WHO master vaccine checklist

• EU master vaccine checklist

Purpose

The purpose of this document is to outline the features and workflow of DIVOC's “Update Certificate” service.

Overview

• DIVOC provides an “update certificate” feature to help beneficiaries make changes in a certificate if any information was captured incorrectly during the beneficiary registration or vaccination process.

• For this purpose, DIVOC provides an “Update Certificate API,” for a source system (e.g. a vaccination platform) to update the vaccination as well as beneficiary details in digital certificates issued by DIVOC.

• There are multiple ways of using this service. The issuing authority can enable a self-service portal, or set up a call centre, or the source system can capture the update requests directly, which can then call the Update API to facilitate the updates/corrections to the specific certificates. The key requirement here is that the “Update Certificate API” is called by the source system(s) to update an issued certificate. Using this API, the source system can update a beneficiary’s latest as well as previously issued digital certificates.

Update Certificate API

As outlined earlier, DIVOC’s “Update Certificate” API is used by source systems to perform updates to already-issued certificates. You can refer to the update API specification link here.

Sample API Payload

[
  {
    "preEnrollmentCode": "987456126",
    "recipient": {
      "name": "John Doe",  
      "dob": "1987-04-21",
      "nationality": "Dutch",
      "identity": "872550100V",
      "contact": [
        "tel:1691742639"
      ]
    },
    "vaccination": {
      "name": "Covishield",
      "batch": "41202025",
      "manufacturer": "astrazeneca",
      "date": "2021-10-17T13:10",
      "effectiveStart": "2021-10-25",
      "effectiveUntil": "2022-10-24",
      "dose": 1,
      "totalDoses": 2
    },
    "vaccinator": {
      "name": "Bartjan Verduijn"
    },
    "facility": {
      "name": "MOH Gothatuwa"
    }
  }
]

What can be updated/corrected?

1. An issued certificate’s QR code contains the two categories of information:

- Personal information, for example:

• Beneficiary name

• Gender

• Date of Birth

- Event details, for example:

• Vaccine type/prophylaxis

• Vaccine name/brand

• Manufacturer Vaccine batch

• Vaccination date

• Facility ID/name

• Country of issuance

• Issuer

• Dose number

• Total dose count

2. Any or all of the above fields can be corrected/updated by calling the Update Certificate API by a source system.

3. The Update Certificate API requires beneficiary ID/enrollment code and dose number as an input to fetch the right certificate that needs to be updated.

4. Once the certificate is fetched, the update API updates the information against the certificate ID as provided in the API payload input.

5. Once the certificate is updated, a new certificate is issued with a new certificate ID and updated information. The older certificate gets revoked by an automated revocation workflow using DIVOC’s “Revoke API.”

6. The revoked certificate is moved to the Certificate Revocation List (CRL). If the older revoked certificate is scanned by a verifier, the verification screen will show “certificate revoked.”

7. For update scenarios, DIVOC can also enable configuring a custom message for beneficiaries trying to verify the older corrected and revoked certificate as: “certificate revoked, please download the updated certificate from the portal.”

8. Updates/corrections can be made in the provisional and final certificate for any of the fields present in the QR code as per the issuing authority’s requirements and approved flow.

9. It is strongly recommended that an issuing authority should allow information correction/updates only after verifying the required proofs uploaded by the beneficiary.

The verification component of the DIVOC certificate service checks for two things:

1. An issued certificate is valid (that is, the document is currently ‘live’ and is not a revoked document).

2. The document is authentic (that is, the document has not been tampered with).

For verifying authorities

Offline verification:

DIVOC supports offline verification of the QR code-based digital certificates to support verification of certificates in connectivity restricted regions and make it more user-friendly.

The QR code can be verified by third-party authorised verifier applications to enable domestic and cross-border verification of DIVOC-issued certificates.

Use the following steps to verify a DIVOC certificate:

1. Scan to detect the QR code.

2. The verification component uses the QR code reader libraries to read the contents of the QR code embedded in the certificate.

3. Once the QR code is detected by the camera, it reads the binary data encoded in the QR code. (the binary data will be in zipped format).

4. The decompressed Json in the QR code is authenticated using a signing method mentioned in the proof section of the QR code content

5. After unzipping it, you will get a certificate.json file (certificate.json will have the signed, json-ld formatted VaccineCertificate).

6. Json-ld signature will be verified against the public key that is issued by the issuing authority.

7. On successful verification, the revoked API is called to check if a certificate has been revoked or not.

8. Once the signature and revocation are verified, the success screen is shown with beneficiary and vaccine details.

9. Since it is offline verification, the verifier will need to download the CRL within the verifier application. The verification service will also go through the CRL and check for the certificate's revoked status.

10. Please note: In addition to supporting verification by third-party verifiers, DIVOC also provides a verification portal. The portal works on a web browser as well as on a mobile phone browser, and it can be also used by verifying authorities to verify DIVOC-certificates in an “offline” capacity.

Online verification:

• DIVOC provides a public portal that allows verifiers (including self-verification by beneficiaries) to verify certificates.

• Certificates can be scanned and verified on the following URL: https://demo-divoc.egov.org.in/ and clicking on “Verify.”

Next,

• Scan the QR code.

• On successful verification, certificate details will be shown on the screen.

• On unsuccessful verification (unauthenticated/fraudulent certificates), the message will be shown as “Certificate Invalid.”

What will it cover?

• What is DIVOC’s EU-DCC adapter service?

• How does the conversion utility work?

• References:

1. DIVOC’s EU-DCC adapter service: Technical details

2. EU’s technical specification for third-countries

What is DIVOC’s EU-DCC adapter service?

DIVOC is an open-source platform that can be used to issue and verify certificates that are consistent with WHO’s minimum data set specifications. Digital certificates issued by DIVOC are based on the globally accepted W3C Verifiable Credential Data Model. Besides the native DIVOC COVID-19 certificate format, DIVOC has enabled an adapter that can convert a native W3C DIVOC issued certificate QR into an EU Digital COVID Certificate (DCC)-compliant QR code.

Need for the EU-DCC adapter service

• The EU has published technical and operational specifications for third countries to onboard the EU gateway and facilitate smooth travel for their citizens by enabling digital verification of citizens’ COVID-19 vaccine certificates issued by the home country.

• The key design principles on which DIVOC has been built are 'interoperability' and 'coexistence.' The EU-DCC adapter has been developed to ensure interoperability and verifiability of the DIVOC’s natively issued certificates with EU verifier apps.

• This utility was required to facilitate restriction-free travel for residents from DIVOC’s adopter countries by enabling conversion of a DIVOC-issued vaccine certificate to an EU-DCC QR code.

Sample EU-DCC certificate PDF template

How does the conversion utility work?

• The utility is an on-demand service enabled by the DIVOC platform. The service can be triggered by using an “export as” function or calling an API for the EU adapter service. The service uses DIVOC’s “fetch service” to fetch an already issued, digitally signed DIVOC certificate post the holder authentication. Once the W3C JSON is fetched, the adapter takes inputs on holder details, vaccine event, and issuer information from the JSON and converts it into an EU-DCC QR code. The EU-DCC QR payload is then digitally signed using the ECDSA cryptographic signature algorithm. DIVOC facilitates the digital signing of the QR via a self-signing process, by using a DIVOC generated public-private key pair. Alternatively, it also supports signing the QR code using a public-private key pair issued by a country’s root certificate authority.

Steps to generate an EU-DCC compliant QR code

1. To generate a valid EU-DCC compliant COVID-19 certificate for travel into the EU member states, the authorised user (certificate holder) can first provide the enrollment code (of his/her COVID-19 certificate that was generated by the issuing authority) via the national system used by the country to download these certificates.

2. To ensure the privacy and security of the certificate holder, DIVOC authenticates the user via a “mobile OTP” or a “user-password” authentication method.

3. DIVOC’s certificate fetch service uses the enrollment code to fetch the correct certificate from the certificate registry.

4. DIVOC then uses the EU-DCC conversion utility to convert the original W3C JSON payload into an EU-DCC compliant payload.

5. The payload is structured and encoded as a CBOR with a COSE digital signature. This is commonly known as a “CBOR Web Token (CWT)” and is defined in RFC 8392. The payload is transported in a hcert claim.

6. This payload is encoded in a QR code and signed using the ECDSA signing method.

7. DIVOC also supports the generation of a PDF template, as defined by the adopter country. Hence, after a successful conversion process, an EU-DCC certificate document (encompassing both, the EU-DCC QR code as well as the PDF template) is generated.

8. The user can then download the EU-DCC certificate onto their mobile phone or export the same to an integrated digital wallet platform, authorised by the adopter country.

Sample EU payload

{
	1: "IN"
	6: 1635179074, 
	4: 1735179074,
	-260: {
		1: {
			"ver": "1.0.0", 
			"nam": {
				"fn": "Doe",
				"gn": "John"
			},
			"dob": "1986",
			"v": [{
				"tg": "840539006", 
				"vp": "1119349007", 
				"mp": "Covishield", 
				"ma": "ORG-100001981", 
				"dn": 1, 
				"sd": 2, 
				"dt": "2021-10-17", 
				"co": "IN", 
				"is": "Govt Of India", 
				"ci": "URN:UVCI:01:IN:331936150"
			}]
		}
	}
}

References

1. DIVOC’s EU-DCC adapter service: Technical details

• Click on the following URL to see the API details: https://egovernments.github.io/DIVOC/developer-docs/api/admin-api.html#../../main/interfaces/certificate-api.yaml

• https://github.com/Path-Check/dcc-sdk.js SDK has been used to generate a CBOR/COSE-based verifiable QR credential from the EU certificate payload.

2. EU technical specification for third-countries:

• Click here to know more about the EU digital green certificate.

• You can check the EU specifications for onboarding third-countries by clicking on the following link: https://ec.europa.eu/health/system/files/2021-07/covid-certificate_equivalence-decision_en_0.pdf.

• Click here to see third country COVID-19 certificate equivalence decision checklist.

• List of all EU specifications are given here.

• To check the JSON specifications, click on the link mentioned below: https://ec.europa.eu/health/system/files/2021-06/covid-certificate_json_specification_en_0.pdf.

• For QR code specifications, click on the following link: https://ec.europa.eu/health/system/files/2022-02/digital-covid-certificates_v3_en_0.pdf.

• To know the value sets for EU Digital COVID Certificates, click here.

• Guidelines on verifiable vaccination certificates - basic interoperability elements, can be accessed here.

Using the DIVOC certificate generation service, a country can issue a QR code-based digitally verifiable certificate, which serves as proof of the health event, such as the COVID-19 vaccination. It involves an issuer (for example, a government department), a holder (for example, the citizen of a country), and a verifier (for example, security personnel at the airport).

Globally accepted W3C-Verifiable Credential Data Model

• All DIVOC issued digital certificates are based on the globally accepted W3C-Verifiable Credential Data Model 1.0.

• DIVOC uses this data model for encoding the event data into the digital certificate’s QR code. DIVOC also uses a PKI mechanism to cryptographically sign all QR codes in the issued digital certificates.

• Popular cryptographic signing algorithms (like RSA, EDDSA) are adopted in the DIVOC certificate QR signing process.

Key roles of a verifiable credential

A. Holder: Someone who possesses one or more verifiable credentials as a proof of an event/identified use case and is responsible for generating presentations from them. In DIVOC’s vaccination use case, it is the vaccine recipient or beneficiary.

B. Issuer: Reefers to a legal entity that asserts claims about the holder or subject about a verifiable event or an identified use case by issuing a verifiable credential to a holder. Issuers may include central/state governments, authorities, corporations, etc. For instance, in the COVID 19 vaccine scenario, the issuer could be the issuing country or legal authorities.

C. Subject: An entity about which the verifiable claim is made by the issuer, for example, beneficiary or vaccine dose recipient.

D. Verifier: An entity who is responsible for verifying an issued credential. In the COVID-19 travel scenario, verifiers are the arrival country authorities that require a verifiable COVID-19 vaccine proof for allowing access to services and border entries.

E. Verifiable data registry: This refers to a role that a system may perform by mediating the creation and verification of identifiers, keys, and other relevant data, such as verifiable credential schemas, revocation registries, issuer public keys, and so on, which may be required to use verifiable credentials.

Purpose

The purpose of this document is to outline the features of DIVOC's certificate distribution service.

Overview

• DIVOC offers several ways in which countries can distribute certificates at scale.

• The platform is designed to facilitate multiple certificate distribution methods, which includes:

- Printed paper certificate with QR code.

- Digital certificate distribution - download and share QR code via URL link, email attachments, smartphone with user authentication.

- By integrating with a country's vaccination portal, health wallets, PHR, consumer, or travel applications.

- Countries can also distribute certificates for a health event via DIVOC’s Citizen Portal.

• After a health event such as vaccination, citizens can log in to the Citizen Portal with their registered mobile number, and they are given the option to securely download the certificate in PDF or other formats with added user authentication.

Certificate API

The DIVOC certificate distribution service provides a get API so that certificates can be downloaded or printed for specific events. For fetching the right certificate, the get service requires a “pre-enrollment code,” and the latest certificate is fetched.

How does it work?

• The get certificate receives the preEnrollmentCode (beneficiary id) as input:

• Once it receives the input, it,

1. gets all certificates associated with preEnrollmentCode from the database.

2. gets the latest dose certificate by grouping the certificates by dose, and order them by their timestamps.

3. creates the QR code from signed certificate data.

4. using the above-generated QR code and certificate information, it creates a PDF.

• Similarly, there are APIs in certificate-api service which can return the QR code as a png image, which follows the same step as above (till the third point):

• We also have an API to check if a beneficiary has a certificate generated, which follows the same step as above (till the second point):

Overview

The document will cover steps on how to add a new user.

Steps to add a user

Step 1:

Login to keycloak (demo URL: ). Click on the administration console and enter the username and password. Next, click on the "sign in" button.

Step 2:

Go to the 'manage' section, and click on 'users.'

Step 3:

Click on "add user" to create a new user.

Step 4:

Enter your mobile number as the user name, and click on save.

Step 5:

Click on 'attributes' and add the required attribute (mobile_number) by clicking on the 'add' button. Next, click on 'save.'

Step 6:

Click on "role mappings" and select the type of role you want to add from the list of "client roles."

Step 7:

Select the role you want to add from the list of "available roles" and click on "add selected." Once you have completed this step, you will see the new user in the "assigned roles" section.

When the “Certify API” is called by a vaccinating system, a unique QR code is generated for that specific event. This document specifies the data structure that can be used to generate a QR code-based digitally verifiable certificate for a registered health event.

QR payload structure

The payload structure follows the JSON Web Token (JWT) digital signature and is defined in . The payload is transported in a DIVOC certificate. JWT includes the following:

• Header

• Payload

• Signature algorithm

Header

This contains the information about the certificate, which is based on the . The header also indicates the type of certificate being issued.

Payload

This is divided into several parts:

• The first part contains the details of who is issuing the certificate along with the timestamp.

• The second part contains the details of the beneficiary to whom the certificate has been issued.

• The final part contains details on the event for which the certificate has been generated. The event part has details of the health event (such as vaccination) along with a timestamp, which includes information on the type of vaccine, dose details, and location of the vaccination.

Signature algorithm

DIVOC is capable of self-generating a public-private key pair. It also supports a signing configuration where the country has onboarded a CA (certificate authority) responsible for generating the keys. In the latter case, DIVOC will use the private key issued by the CA and sign the QR code.

• The DIVOC certificate is flexible and multiple signing algorithms can be used.

• Self-generated keys or the keys from a country’s PKI service provider can also be used. DIVOC currently uses two default signature algorithms:

1. PS256 - Using "crit" with "b64"

2. ES256

• The public key along with the method of signing will be provided to verifiers to authenticate certificates.

• Based on the algorithm that is being used for certificate generation, the certificate can be verified by the verifier.

Sample Payload

Purpose

This document refers to the revocation of a digital certificate issued to a person. DIVOC’s certificate revocation service will help stakeholders of a program to revoke digital certificates, according to the issuing authority’s predefined policy.

For example, during a COVID-19 vaccination campaign, the vaccination certificate issued to a person, as digitised proof of the event, can get revoked due to multiple reasons like:

• errors in the information encoded in the digital certificate.

• wilful tampering of the digital certificate (QR or PDF output) by external entities who have gained unauthorized access to the certificate data contents.

• or if a specific batch of vaccines is found to be faulty, among others.

The purpose of this document is to provide an overview of the certificate revocation service offered by DIVOC. It describes the steps involved in the revocation process, as well as the maintenance of the revoked certificate list for verifiers.

What is DIVOC’s certificate revocation service?

Revocation API

• DIVOC has enabled a “Revoke API” that can be used to revoke an issued certificate for manual revocation use cases.

• The API uses a “beneficiary ID/pre-enrollment code” and either the “dose number(s)” or the “all doses” flag as input parameters to search and fetch the certificate(s) that need to be revoked from the certificate registry.

• If the “dose number(s)” parameter is passed, it must be a sequential list of doses that includes the latest dose.

• DIVOC stores the revoked certificate ID within a centrally-maintained “certificate revocation list (or CRL).”

Revocation List

• DIVOC maintains a certificate revocation list to store certificate IDs of the revoked certificates. The revocation list can be hosted by an issuing authority (either inside or outside its central certificate registry) or can be periodically downloaded as a file and stored by a verifier application.

• When a revoked certificate’s QR code is scanned using the DIVOC’s online verification service, the service searches the CRL for the certificate ID to check if the certificate is a valid or revoked certificate.

• If the certificate ID is found in the CRL of the scanned QR code, the verification screen displays the certificate as revoked.

• Each CRL has a serial number, time, and date on which the certificate was revoked.

• It includes the date and time when the CRL was published, and when the next update to the CRL will be published.

How does it work?

• A revocation is triggered when the revocation API is called by the source system (for example, a vaccination platform), on specific transactions (for example, the correction or update of a certificate).

• As input parameters from the source system, the revoke API receives beneficiary ID/enrollment code and dose number(s) or the all doses flag.

• The relevant certificate is fetched and DIVOC performs a “soft delete” of the certificate (also referred to as the “revocation” process).

• The revoked certificate’s "certificate ID" is then moved to the certificate revocation list.

• Certificate IDs of all revoked certificates are maintained in the CRL within the certificate registry. The revoked certificate IDs can be indexed in chronological order against the respective unique certificate ID, along with its revocation date and time.

• The certificate revocation list will be regularly updated to support the verification flow by approved domestic and international verifiers.

• If the certificate was revoked, the same information will be displayed to the third-party verifier application in real-time. On scanning, the verifier application will display the result as an “Invalid certificate.”

• DIVOC’s certificate revocation list can be configured to support both offline and online verifications flows. For instance,

- On scanning a revoked certificate, a third-party verifier application can call the APIs (i.e. fetch APIs provided by DIVOC to the country’s issuing authority) to fetch the certificate revocation list to validate the “revoked” status of the digital certificate.

- The certificate revocation list can be downloaded by the third-party verifier application (in their local system) on a periodic basis.

You have likely seen a lot more QR codes over the last two years due to the pandemic. At many restaurants, for example, which are keen not to share physical menus, customers scan a QR code with their phone camera to open a website for the online menu.

What is a QR code?

• Short for Quick Response, a QR code stores all kinds of information that can be scanned and accessed by a digital device such as your smartphone.

• The machine-readable format can also be printed on a piece of paper.

• While barcodes are one-dimensional, which means that information can be scanned only horizontally, QR codes are two-dimensional. Hence, information on a QR code can be read both horizontally and vertically, allowing it to store more data.

• QR codes allow you to download applications, join WiFi networks without having to key in any password, scan coupons, and much more. They can be embedded on a company’s website to gather feedback, facilitate registrations, collect customer data, and order details. QR codes can be used on physical products as a way to provide more information.

• QR codes are also used for document verification to check if a credential is genuine. This has gained popularity during the pandemic with some countries opting for QR code-based vaccination certificates to open up travel and business.

Normal QR Code vs Signed/Verifiable QR Code

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

What will it cover?

• Overview of the Smart Health Card specification

• What is DIVOC’s Smart Health Card adapter?

• How does the conversion utility work?

• References:

- Technical specification

Overview of the Smart Health Card specification

A Smart Health Card (SHC) is a globally popular HL7 FHIR (Fast Healthcare Interoperability Resources) and W3C verifiable credential standards - based open standard for generating tamper-proof health credentials.

• An SHC provides a framework that facilitates the generation, storing and verification of the SHC holder’s clinical information.

• To enable people to access a digital record of their COVID-19 vaccine history, SHCs ascertaining an individual’s vaccination and test result status, have been rolled out in US-States (California, Colorado, Connecticut, Delaware, Hawaii, Illinois, New York, and 9 others), Canada, and Japan.

• You can find the registry of verified Smart Health Card issuers for vaccinators here and here.

(Information courtesy SMART Health Card)

• To understand how they work and where they can be used, click here and here.

What is DIVOC’s SHC adapter service?

Besides it’s native COVID-19 certificate schema, the DIVOC platform has also developed an adapter service to convert a native DIVOC W3C-JSON certificate into a Smart Health Card-compliant QR code.

Need for the SHC-Adapter service

• This utility was required to facilitate restriction-free international travel for residents from DIVOC’s adopter countries by enabling conversion of a DIVOC issued vaccine certificate to an SHC-QR code.

• The key design principles on which DIVOC has been built are “interoperability” and “coexistence.” The SHC adapter service has been developed to ensure interoperability and verifiability of the DIVOC’s natively issued certificates with the multiple verifier apps used in the SHC adopter countries.

How does the conversion utility work?

DIVOC’s adapter issues a digital certificate, as per the SHC data model, and is presented as a signed-QR code. When a source system calls DIVOC’s SHC adapter API, the following steps are undertaken;

• DIVOC first checks within the certificate registry (using the beneficiary enrolment code, passed from the source system) to see if a certificate is present for the given beneficiary.

• If present within the certificate registry, it fetches the respective certificate and then converts the native DIVOC W3C certificate to a SHC-certificate (https://build.fhir.org/ig/HL7/fhir-shc-vaccination-ig/) using a custom-built npm module.

• This SHC-certificate payload is then signed and the resulting JWS is used to create a QR code (using the open-source https://github.com/Path-Check/shc-sdk.js library).

• It returns the generated QR code or the full-certificate PDF (including the signed-QR), based on type parameters.

• The source system can then allow the download of the generated SHC-QR certificate onto a beneficiary’s mobile phone or allow the export to a beneficiary’s digital wallet platform.

References

Technical specification

• To know more on SHC specification, click https://spec.smarthealth.cards/.

• You can check the SHC vaccination and testing implementation guide here.

A vaccination certificate is a proof that a person has received the shot to protect them from an infectious disease such as COVID-19 or the flu. We have given below the type of information (mandatory and optional) that should be there in a QR code-based COVID-19 vaccination certificate, as specified by the World Health Organisation (WHO).

All content on this page by is licensed under a .

This section will cover the following:

• How to install DIVOC

• Backup & Restore: Postgres, Clickhouse, Kafka, & Redis

• Infrastructure Recovery

• Server Hardening

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Create a user type

The facility/system administrator can print the certificates. The administrator can also create a user type (from the list of available roles) for a person who will print the certificates. Click here to add a user type in DIVOC.

Steps to print certificates at a facility

Step 1:

Once the user has been created, the person can log in to the portal using the following URL: https://demo-divoc.egov.org.in/portal. Enter the registered mobile number, and the OTP, and click on "login to portal."

Step 2:

Enter the phone number and the date of birth given during registration. Next, click on the search button.

You will see the name(s) displayed on the screen.

Step 3:

Click on 'print' to print the certificate. To save it on your desktop/laptop, click on 'save.'

Step 4:

Log out once you have printed the required certificate(s).

Highly flexible and configurable, DIVOC’s architecture is designed to accommodate changes and allow the addition of new capabilities and functionalities. For example, during a vaccination campaign, you can configure vaccines, vaccination frequency, approved facilities, trained vaccinators, certificate templates, and authentication mechanisms, among others. Built on open source and open standards, the DIVOC architecture ensures privacy and security by design.

Architecture highlights

• DIVOC has been built using a micro-services architecture with open API integration capabilities. It can be hosted on the cloud and on-premise cloud.

• It is built on top of the generalised electronic registry and the credentialing framework is available under Sunbird Registry and Credentialing, as well as on-premise bare metal servers.

• DIVOC’s modules can work in various combinations based on a country’s requirements as well as end-user needs. Accordingly, countries can use specific or all micro-services.

• It is designed to plug and play with different certificate distribution schemes, such as printed with QR code, digital using smartphones, SMS/email attachments, digital lockers, etc.

• Allows interoperability with various ID, payment, and other systems.

• DIVOC is designed to cater to the diversity of use cases in terms of the choice of the facility (such as government and to private facilities) across geographies within a country; choice of payment (government funding, employer funding, or individual funding, among others); and choice of IDs (digital IDs, and mobile numbers.

• The platform is extensible. For example, many parts of the software can be extended, as well as replaced with country-specific components without having to customise. This, in turn, facilitates easy upgradability.

Kubernetes

Recovering control plane

• To recover from broken nodes in the control plane, use the "recover-control-plane.yml" playbook.

• Back up what you can.

• Provision new nodes to replace the broken ones.

• Place the surviving nodes of the control plane first in the "etcd" and "kube_control_plane" groups.

• Add the new nodes below the surviving control plane nodes in the "etcd" and "kube_control_plane" groups.

Examples of what broken means in this context:

• One or more bare metal node(s) suffer from unrecoverable hardware failure.

• One or more node(s) fail during patching or upgrading.

• Etcd database corruption.

• Other node-related failures that leave your control plane degraded or nonfunctional.

• Note: You need at least one functional control plane node to be able to recover using this method. If all control planes go down, there is no scope of recovery, and you will have to reinstall Kubernetes. Typically, even if the control plane goes down, the application still functions. Kubernetes functions like scaling, creating new pods, upgrading deployments, etc. will not work. The application, as is available, will continue to function.

Runbook

• Move any broken etcd nodes into the "broken_etcd" group, make sure the "etcd_member_name" variable is set.

• Move any broken control plane nodes into the "broken_kube_control_plane" group.

• Run the playbook with --limit etcd,kube_control_plane, and increase the number of etdc retries by setting -e etcd_retries=10 or something even larger. The amount of retries required is difficult to predict.

• Once you are done, you should have a fully working control plane again.

Recover from the last quorum

• The playbook attempts to figure out if the etcd quorum is intact. If the quorum is lost, it will attempt to take a snapshot from the first node in the "etcd" group and restore from that.

• To restore from an alternate snapshot, set the path to that snapshot in the "etcd_snapshot" variable: -e etcd_snapshot=/tmp/etcd_snapshot.

Adding or replacing a node

Removal of first kube_control_plane and etcd-master

Currently, you cannot remove the first node in your kube_control_plane and etcd-master list. If you still want to remove this node, you have to do the following:

1. Modify the order of your control plane list by pushing your first entry to any other position, such as if you want to remove node-1 of the following example:

2. Run upgrade-cluster.yml or cluster.yml. After this, you are good to go on with the removal.

Adding or replacing a worker node

1. Add a new node to the inventory.

2. Run scale.yml. You can use --limit=NODE_NAME to limit Kubespray to avoid disturbing other nodes in the cluster. Before using --limit, run playbook facts.yml without the limit to refresh facts cache for all nodes.

3. Remove an old node with remove-node.yml. With the old node still in the inventory, run remove-node.yml. You need to pass -e node=NODE_NAME to the playbook to limit the execution to the node being removed. If the node you want to remove is not online, you should add reset_nodes=false and allow_ungraceful_removal=true to your extra-vars: -e node=NODE_NAME -e reset_nodes=false -e allow_ungraceful_removal=true. Use this flag even when you remove other types of nodes like a control plane or etcd nodes.

4. Remove node from the inventory.

Adding or replacing a control plane node

1. Append the new host to the inventory and run cluster.yml. You cannot use scale.yml for that.

2. In all hosts, restart nginx-proxy pod. This pod is a local proxy for the apiserver. Kubespray will update its static config, but it needs to be restarted to reload:

3. With the old node still in the inventory, run remove-node.yml. You need to pass -e node=NODE_NAME to the playbook to limit the execution to the node being removed. If the node you want to remove is not online, you should add reset_nodes=false and allow_ungraceful_removal=true to your extra-vars.

Learn how to configure DIVOC:

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

DIVOC’s certificate module has been adopted for the ongoing COVID-19 vaccination programs in multiple countries. The guide and its different sections describe the various steps that you have to follow when implementing one or more features of the certification and verification component, depending on your country’s needs.

Country-specific requirements may include the following:

1. Certificate Component -

• Generate certificates

• Update certificates

• Revoke fake or incorrect certificates

• Fetch certificates

• Fetch QR code

• Notify beneficiaries

2. Verification component

What will the sections cover?

The template for the QR code generation is provided under vaccination-context. The QR code structure must match the vaccination-context. Any updates made in the QR code content must reflect in the vaccination-context.js file.

Steps:

a. Open the file .

b. Go to the function transformW3 and add the fields according to your requirement. This function will read the data received from the certificate generation API call and convert it into QR code Json format.

c. Add the newly-added field to the data variable

Note:

Certificate signing

Supported key types

1. RSA (default)

2. ED25519 (recommended for performance)

Environment variable configuration

Key pair configuration for DIVOC certificate

Environment variables

The expected values for these configurations change depending on the type of key in use:

RSA -

• Private key format: 2048 bit, PEM

• Public key format: PEM

ED25519 -

Reference steps for key generation

RSA key generation using openssl

ED25519

Key pair configuration for EU certificate

Generation of key pair for signing an EU certificate:

• Open the cert.conf file and edit it according to your requirement.

• For generation of RSA key pair: ./gen-dsc.sh RSA CSR

• For generation of ECDSA key pair: ./gen-dsc.sh ECDSA CSR

• The script will generate the following 3 files:

1. private key filename - DSC01privkey.key

2. CSR filename - DSC01csr.pem CERTIFICATE key filename - DSC01cert.pem

3. Public key format: PEM

Configuring EU certificate retrieval from the certificate-API service

1. Generate the key pair required for signing the EU certificate and share the CSR file for signing with CA.

2. In the divoc-config configMap, set the following environment variables:

• EU_CERTIFICATE_PRIVATE_KEY - Private key for signing the EU payload (in PKCS8 format).

• EU_CERTIFICATE_PUBLIC_KEY - The certificate provided by CA after signing the CSR.

• EU_CERTIFICATE_EXPIRY - Expiry of the certificate in months (for example, 12).

Overview

This document will help an implementer configure a certificate (template and QR code) for a health event such as vaccination. This section includes configuring:

API

The DIVOC platform provides API services for generating digitally verifiable QR code-based vaccination certificates. The API for certificate generation has 6 sections:

1. PreEnrollmentCode: This section is linked to the 'dose' in the vaccination section to uniquely identify an event. For example, beneficiary registration number (R101) and dose number (1) as (R101-1) will be used to identify the first dose event uniquely. Similarly, beneficiary registration number (R101) and dose number (2) as (R101-2) will be used to identify the second dose event uniquely.

2. Recipient: It contains information about the beneficiary.

3. Vaccination: It contains details about the vaccination event such as name, batch, and vaccination date.

4. Vaccinator: It contains details about the vaccinator.

5. Facility: It contains details about the facility where beneficiaries will get vaccinated.

6. Meta: It contains additional information, which is not part of the QR code, such as the number of past doses taken.

Sample for default certificate generation request

• You can refer to the API service call with sample data below:

Key Functionalities

• Generate configured QR code

• Generate configured certificate template

Prerequisite: Get details on API request and field validations

Making the changes

Click the following to see how you can make the changes:

Example

Include the beneficiary’s parent name in the certificate. The parent’s name is “Sam Mandosa.” This is a mandatory field.

Steps

Step 1: Create a certification generation request

a. Open this file: https://github.com/egovernments/DIVOC/blob/main/backend/vaccination_api/pkg/certify_handler.go

b. Add a parameter in the function “convertToCertifyUploadFields” called RecipientParentName.

func convertToCertifyUploadFields(data *Scanner) *db.CertifyUploadFields {
	return &db.CertifyUploadFields{
		PreEnrollmentCode:         data.Text("preEnrollmentCode"),
		RecipientName:             data.Text("recipientName"),
RecipientParentName:        data.Text("recipientParentName"),
		RecipientMobileNumber:  data.Text("recipientMobileNumber"),
		RecipientDOB:              data.Text("recipientDOB"),
		RecipientGender:           data.Text("recipientGender"),
		RecipientNationality:      data.Text("recipientNationality"),
		RecipientIdentity:         data.Text("recipientIdentity"),
		RecipientAge:              data.Text("recipientAge"),
		RecipientAddressLine1:  data.Text("recipientAddressLine1"),
		RecipientAddressLine2:  data.Text("recipientAddressLine2"),
		RecipientDistrict:         data.Text("recipientDistrict"),
		RecipientState:            data.Text("recipientState"),
		RecipientPincode:          data.Text("recipientPincode"),
		VaccinationBatch:          data.Text("vaccinationBatch"),
		VaccinationDate:           data.Text("vaccinationDate"),
		VaccinationDose:           data.Text("vaccinationDose"),
		VaccinationTotalDoses:   data.Text("vaccinationTotalDoses"),
	VaccinationEffectiveStart:data.Text("vaccinationEffectiveStart"),
	VaccinationEffectiveEnd:data.Text("vaccinationEffectiveEnd"),
	VaccinationManufacturer:   data.Text("vaccinationManufacturer"),
		VaccinationName:           data.Text("vaccinationName"),
		VaccinatorName:            data.Text("vaccinatorName"),
		FacilityName:              data.Text("facilityName"),
		FacilityAddressLine1:      data.Text("facilityAddressLine1"),
		FacilityAddressLine2:      data.Text("facilityAddressLine2"),
		FacilityDistrict:          data.Text("facilityDistrict"),
		FacilityState:             data.Text("facilityState"),
		FacilityPincode:           data.Text("facilityPincode"),
	}
}

c. Add RecipientParentName in the function “createCertificate” to make the field mandatory.

recipient := &models.CertificationRequestRecipient{
		Name: &certifyData.RecipientName,
		Age:  recipientAge,
		Address: &models.CertificationRequestRecipientAddress{
			AddressLine1: &certifyData.RecipientAddressLine1,
			AddressLine2: certifyData.RecipientAddressLine2,
			District:     &certifyData.RecipientDistrict,
			Pincode:      &certifyData.RecipientPincode,
			State:        &certifyData.RecipientState,
		},
		Contact:     contact,
		Dob:         dateAdr(strfmt.Date(dob)),
		Gender:      &certifyData.RecipientGender,
		Nationality: &certifyData.RecipientNationality,
		ParentName: &certifyData.RecipientParentName,
		Identity:    &certifyData.RecipientIdentity,
	}

d. If the data is uploaded via CSV, then add this column to the CSV template for this field. Open “application-default.yml” and update the certificate section in this file.

Note:

• As a standard practice, we recommend you to update the informative files mentioned in step 1 of this section.

• Make sure the name matches exactly with the name convertToCertifyUploadFields function that you edited in step 1.

Overview

The document will help an implementer make changes to DIVOC’s verification component in line with any changes made to the certificate. It could include changes in the QR code section of the certificate or the logo, among others.

This section will cover the steps to update the verification component by configuring:

1. Verification portal home page

2. Verification confirmation page

Prerequisite: Get details on functions used for certificate verification

1. The user will be directed to the verification page according to the route defined in this file:

 <div style={{paddingBottom: "3rem", paddingTop: "3rem"}}>
  <Switch>
	<Route exact path={"/"} component={Home}/>
	<Route exact path={config.urlPath + "/login"} component={Login}/>
	<Route exact path={"/side-effects"} component={SideEffects}/>
	<Route exact path={"/feedback"} component={SideEffects}/>
	<PrivateRoute exact path={"/feedback/verify"} component={SubmitSymptomsForm} role={RECIPIENT_ROLE} clientId={RECIPIENT_CLIENT_ID}/>
	<Route exact path={"/dashboard"} component={Dashboard}/>
	<Route exact path={"/verify-certificate"} component={VerifyCertificate}/>
	<Route exact path={"/learn"} component={Learn}/>
	<Route exact path={"/not-found"} component={PageNotFound}/>
 </Switch>
</div>

2. You can configure the timeout period for the camera to read the QR code in config.CERTIFICATE_SCAN_TIMEOUT.

3. If the camera is unable to read the QR code content, the timeout can be set to retry.

const onScanWithQR = () => {
        setShowScanner(true);
        setTimeout(() => {
            if(!result) {
                setShowTimeout(true);
            }
        }, config.CERTIFICATE_SCAN_TIMEOUT);
    };


const onTryAgain = () => {
        setShowTimeout(false);
        setShowScanner(false)
    };

4. The QR code scan is triggered from the ‘VerifyCertificate’ method. Once the QR code is read by the application, it is unzipped using the jsZip library.

Verification portal home page

How to update the verification page:

• The required UI changes, including messaging and branding, can be configured on this file.

• You can refer to this file as an example of a country-specific configuration (https://verify.icmr.org.in/).

Verification confirmation page

How to update the vaccination confirmation details:

Example: Include the beneficiary’s parent name as a mandatory field in the verification confirmation page.

• Open this file: https://github.com/egovernments/DIVOC/blob/main/vaccination-context/vaccination-context.js.

• Add a parameter in the function “vaccinationContextV2” to set the schema.

"Person": {
      "@id": "schema:Person",
      "@context": {
        "@version": 1.1,
        "@protected": true,
        "refId": "schema:id",
        "uhid": "schema:id",
        "name": "schema:name",
        "age": "schema:Number",
        "gender": "schema:gender",
        "nationality": "schema:nationality",
        "recipientParentName": "schema:name",
        "address": {
          "@id": "schema:PostalAddress",
          "@context": {
            "@version": 1.1,
            "@protected": true,
            "streetAddress": "schema:streetAddress",
            "streetAddress2": "vac:addressLine2",
            "city": "vac:city",
            "district": "vac:district",
            "addressRegion": "schema:addressRegion",
            "postalCode": "schema:postalCode",
            "addressCountry": "schema:addressCountry"
          }
        }
      }
    },

• Add recipientParentName in the certificate variable inside the function createCertificate.

"certificate": {
    "Name": "Name",
    "Age": "Age",
    "DOB": "DOB",
    "Gender": "Gender",
    "recipientParentName":"Recipient Parent Name",
    "Certificate ID": "Certificate ID",
    "Vaccine Name": "Vaccine Name",
    "Vaccine Type": "Vaccine Type",
    "Date of Issue": "Date of Issue",
    "Valid Until": "Valid Until",
    "Dose": "Dose",
    "Total Doses": "Total Doses",
    "Vaccination Facility": "Vaccination Facility"
  },

• Build and deploy your changes.

• Click here to know what information is included in the DIVOC certificate.

Note:

• The ‘recipientParentName’ should match with the key in the QR code Json file available in the main.js.

• To remove any value (such as “vaccine type”) from the UI screen, you can remove that parameter in the certification field.

Setting up DIVOC in your country to orchestrate a new health programme? The guide covers everything you need to know to implement DIVOC. The different sections are meant for people who are involved in planning and managing the various aspects of the implementation process, as well as those involved in the technical work. The documents cover the various steps and configurations required.

What will it cover?

A. Skills needed to set up DIVOC

B. Implementation Checklist

C. Setting up DIVOC

D. Backup & Restore: Postgres, Clickhouse, and Kafka

E. Infrastructure Recovery

F. Server Hardening

G. Certificate and Verification Component

H. Platform Policy Guidelines

I. Privacy Policy Recommendations

Each country will have its own set of requirements in line with globally accepted standards for issuing certificates. The guides will walk you through:

• How to configure the certificate component?

• How to set up the verification portal for your implementation?

• How to configure the update certificate API?

What does this section cover?

• Skills needed for a simple setup scenario

• Skills needed for a complex setup scenario

Simple setup: Only setup and configuration

This includes:

1. Setting up infrastructure on cloud or on-premise.

2. Deployment of application components/services.

3. Configuration of components to connect to work as a single system:

- Configure templates, such as data import templates for facility registry.

- Keycloak to change OTP-based login in keycloak to password-based login.

- Configuration of certificate templates.

Skills the team should have:

• Experience in setting up Kubernetes cluster / Docker-based deployment.

• Experience in setting up and configuring platforms such as Kafka, Redis, Postgres, and Keycloak.

• Experience in HTML templates design.

Complex setup: Setup, configuration, and customisation

Customise DIVOC as per the country-specific requirements and its implementation need, such as:

1. Changes in registry schema: This includes changes in the type of information being captured on various events.

2. UI: This includes applying country-specific branding on the various UI pages of the portal.

3. Add and Update APIs: This includes the introduction of new API calls within as well as with third-party applications, such as integration with the supply chain system to provide updates on the stock used at the facility level. It also involves updating existing APIs, such as changing mandatory fields to non-mandatory in API payloads and changing response structure, among others.

Skills the team should have:

• Experience in technologies such as HTML, Jquery, React, JavaScript for UI level changes.

• Experience in technologies such as Go for API-related changes.

• Experience in OpenSaber and Postgres for registry-related changes.

• Experience in integrating platform services used in selected components for customisation and implementation.

Overview

This is the generic solution for backup and restore. Depending on the backup strategy used, the tools might change.

Backing up and restoring Postgres

• The Ansible script will automatically configure pg_basebackup, pgbackrest, wal-g and other recovery tools. For the sake of simplicity, we can use pg_dump and pg_restore.

• The following command takes a backup. This will create a compressed tarball backup in the directory mentioned:

• This can be scheduled using a cron as shown below:

• Pg_basebackup is installed along with psql client

• You can restore from pg_dump as follows:

Backing up and restoring Clickhouse

The plan is to use clickhouse-backup, which is open sourced under the liberal MIT license. This tool has the ability to create archived backups and upload them to NFS, S3, GCS, AZBlob, SFTP and other remote data repositories.

• Download the latest release from https://github.com/AlexAkulov/clickhouse-backup/releases

• Untar the archive

• Create a configuration file as follows, call it config.ini

• Ensure configuration under clickhouse and general section of the configuration file. The rest are not mandatory.

• If automated remote upload functionality is needed, the appropriate section needs to be filled in: sftp, ftp, s3, GCS, AZBlob, etc.

• The following command can be run:

• The following is the list of possible commands which can be executed:

Backing up and restoring Kafka

• Backup zookeeper state data

- Go to file

- Copy location of dataDir property (typically, /tmp/zookeeper)

- Run the following command:

• Backup Kafka topics and messages

- Go to the file kafka/config/server.properties

- Copy location of log.dirs (typically, /tmp/kafka-logs)

- Stop Kafka:

- Login as kafka user:

- Run the following command:

• Restore zookeeper

- sudo systemctl stop kafka

- sudo systemctl stop zookeeper

- sudo -iu kafka

- rm -r /tmp/zookeeper/*

- tar -C /tmp/zookeeper -xzf /home/kafka/zookeeper-backup.tar.gz

--strip-components 2

• Restore kafka

- rm -r /tmp/kafka-logs/*

- tar -C /tmp/kafka-logs -xzf /home/kafka/kafka-backup.tar.gz --strip-components 2

- sudo systemctl start kafka

- sudo systemctl start zookeeper

• Verification of Restoration

- ~/kafka/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic

BackupTopic --from-beginning

Backing up and restoring Redis

Redis provides an in-built command to save a backup.

• Install redis-cli using

• The following command takes a backup of the redis-server:

• This will save the backup as dump.rdb within:

Restoration can be done in the following way:

• Locate the redis data directory, typically:

• Move the dump.rdb file into this folder

• Start redis server

• This will ensure that data is restored automatically

Each country will have a separate certificate template with country-specific branding, and language.

Steps:

a. The DIVOC certificate template has been designed in the HTML format. To configure the HTML-based certificate template according to your country’s requirement, open certificate_template.html and map the dynamic fields in the certificate template.

<tr>
        <td><span class="d-flex pt-1 pb-1 font-bold">Beneficiary Name</span></td>
        <td><span class="d-flex pt-1 pb-1 font-bold">Beneficiary Parent Name</span></td>
    </tr>
    <tr>
        <td><span class="d-flex">{{name}}</span></td>
        <td><span class="d-flex">{{parentName}}</span></td>
    </tr>

b. Any modifications that you make (such as combining address fields as a single string) to the address value must be performed in controller.js. The dynamic values will be sent from controller.js.

function prepareDataForVaccineCertificateTemplate(certificateRaw, dataURL) {
    certificateRaw.certificate = JSON.parse(certificateRaw.certificate);
    const {certificate: {credentialSubject, evidence}} = certificateRaw;
    const certificateData = {
        name: credentialSubject.name,
        parentName: credentialSubject.parentName,
        age: credentialSubject.age,
        gender: credentialSubject.gender,
        identity: formatId(credentialSubject.id),
        beneficiaryId: credentialSubject.refId,
        recipientAddress: formatRecipientAddress(credentialSubject.address),
        vaccine: evidence[0].vaccine,
        vaccinationDate: formatDate(evidence[0].date) + ` (Batch no. ${evidence[0].batch} )`,
        vaccineValidDays: `after ${getVaccineValidDays(evidence[0].effectiveStart, evidence[0].effectiveUntil)} days`,
        vaccinatedBy: evidence[0].verifier.name,
        vaccinatedAt: formatFacilityAddress(evidence[0]),
        qrCode: dataURL,
        dose: evidence[0].dose,
        totalDoses: evidence[0].totalDoses,
        isFinalDose: evidence[0].dose === evidence[0].totalDoses,
        currentDoseText: `(${getNumberWithOrdinal(evidence[0].dose)} Dose)`
    };

    return certificateData;
}

Note:

• To check the PDF/print version, which will be generated after an update, open the HTML file in the browser and check for the print preview.

• The page size should be A4 as the HTML is developed according to A4 dimensions.

Overview

This section will help an implementer configure the DIVOC “Update Certificate” API.

Intended output

• Implementers can use the “Update Certificate” API to process the requested updates - both in the QR code and human-readable sections of a specific certificate.

API

• The DIVOC platform provides API services for updating vaccination certificates. You can refer to the API service call ‘​/v3​/certificate’ for the method PUT here.

• The payload of the update service is the same as that of the certificate generation request. Click here to know more.

• The platform provides flexibility to update values in the ‘recipient,’ ‘vaccination,’ ‘vaccinator,’ and ‘facility’ sections. Click here if you want to understand the mandatory and non-mandatory information that should be there in a vaccination certificate, according to global standards.

Methods - Get details on the API request and field validations:

a. The update certificate request is processed in this function. The pre-enrollment code and dose-wise certificates will be searched in the system to make an update request. The function will trigger the subsequent process to update the certificates.

for _, request := range params.Body {
if certificateId := getCertificateIdToBeUpdated(request); certificateId != nil{
log.Infof("Certificate update request approved %+v", request)
	if request.Meta == nil {
		request.Meta = map[string]interface{}{
			"previousCertificateId": certificateId,
			"certificateType":       CERTIFICATE_TYPE_V3,
		}
	} else {
		meta := request.Meta.(map[string]interface{})
		meta["previousCertificateId"] = certificateId
		meta["certificateType"] = CERTIFICATE_TYPE_V3
	}
	if jsonRequestString, err := json.Marshal(request); err == nil {
		kafkaService.PublishCertifyMessage(jsonRequestString, nil, nil)
	}
} else {
	log.Infof("Certificate update request rejected %+v", request)
	return certification.NewUpdateCertificateV3PreconditionFailed()
}
}
return certification.NewUpdateCertificateV3OK()

b. An implementer has the provision to restrict the number of update requests against a specific certificate in order to avoid the misuse of this functionality (that is, fraudulent generation of multiple certificate copies). For instance, the implementer can configure the “Update Limit” to only “5,” in which case the certificate can only be updated five times. The following steps are needed to enable this configuration:

Step 1: Open this file and check the function that will limit the number of certificates being updated.

if count < (config.Config.Certificate.UpdateLimit + 1) {
  certificateId := doseWiseCertificateIds[int(*request.Vaccination.Dose)][count-1]
	return &certificateId
} else {
	log.Error("Certificate update limit reached")
}

Step 2: Open this file and update the limit by configuring CERTIFICATE_UPDATE_LIMIT.

UpdateLimit int `env:"CERTIFICATE_UPDATE_LIMIT" default:"5"`

• Click here to understand how DIVOC's “Update Certificate” service works.

This is the minimum list of hardening and other steps that need to be performed to secure the Linux server containing the DIVOC platform. The assumption is that the installation happens on a bare metal setup. While the concepts remain the same, the methodology might differ for commercial cloud setups.

Check for open ports

• Identifying open connections to the internet is a critical mission.

• Once you have identified the open ports, you can stop/purge the applications which keep unnecessary ports open.

• The only acceptable open ports are 22 and 443. Access to the other ports outside the Kubernetes network should be prohibited.

• All ingress should be routed through the 443 port only as needed.

Secure SSH

SSH is secure, but we need to harden this service as well. If we can disable SSH, then the problem is solved. However, if we want to use it, we have to change the default configuration of SSH. Password-based authentication should be disabled and only key-based authentication should be allowed. The steps for creating sudo users with public and private keys are as follows:

• Create a non-root sudo user

• Add the user to sudo users group

• Login to the machine as the user

• Create SSH directory with appropriate permissions

• Generate a key pair for the protocol, and run:

• Share the public key created with users you expect to connect to the server

• You can modify your SSH configuration to be more secure by performing the following changes to the configuration file:

• Make sure that root cannot login remotely through SSH

• Allow some specific users

• Enable public key-based authentication and disable password-based authentication

• There are some additional options that must exist in the “sshd_config” file: MaxAuthTries 5

• Finally, set the permissions on the sshd_config file so that only root users can change its contents:

Assumptions

• Use a Debian-based Linux distribution (preferably Ubuntu)

• Experience in running simple shell and bash commands

Pre-requisites

• Debian-based OS (Ubuntu)

• sshpass

• Ansible

• GIT

• kubectl

• List of servers and ability to access them using key-based authentication

• Server map to list servers against software

• Access to the DIVOC installer repository

• Access to the implementation-specific DIVOC code