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.

The template for the QR code generation is provided here 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 main.js.

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.

function transformW3(cert, certificateId) {
  const certificateType = R.pathOr('', ['meta', 'certificateType'], cert);
  const namespace = certificateType === CERTIFICATE_TYPE_V3 ? CERTIFICATE_NAMESPACE_V2 : CERTIFICATE_NAMESPACE;
  const recipientIdentifier = R.pathOr('', ['recipient', 'identity'], cert);
  const preEnrollmentCode = R.pathOr('', ['preEnrollmentCode'], cert);
  const recipientName = R.pathOr('', ['recipient', 'name'], cert);
  const recipientGender = R.pathOr('', ['recipient', 'gender'], cert);
  const recipientNationality = R.pathOr('', ['recipient', 'nationality'], cert);
  const recipientParentName = R.pathOr('', ['recipient', 'parentName'], cert);

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

let data = {
    namespace, recipientIdentifier, preEnrollmentCode, recipientName, recipientGender, recipientDob, recipientAge, recipientNationality, recipientParentName, recipientAddressLine1, recipientAddressLine2, recipientAddressDistrict, recipientAddressCity, recipientAddressRegion, recipientAddressCountry, recipientAddressPostalCode,
    issuer, issuanceDate, evidenceId, InfoUrl, feedbackUrl,
    certificateId, batch, vaccine, icd11Code,  prophylaxis, manufacturer, vaccinationDate, effectiveStart, effectiveUntil, dose, totalDoses,
    verifierName,
    facilityName, facilityAddressLine1, facilityAddressLine2, facilityAddressDistrict, facilityAddressCity, facilityAddressRegion, facilityAddressCountry, facilityAddressPostalCode
  };

Note:

Certain constant values are also listed in the main.js. If you want to update any of the constant values such as “certificate controller,” please refer to the DockerFile.

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?

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:

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.

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

Use an external library such as ed25519-verification-key-2018 to generate a key-pair in the required format.

Key pair configuration for EU certificate

Generation of key pair for signing an EU certificate:

• Copy the certificate generation script file gen-dsc.sh and put it in the desired location.

• Copy the certificate configuration file cert.conf and put it in the same folder where the certificate generation script was copied to.

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

• Run the gen-dsc.sh file to generate the key pair for signing the EU certificate.

• 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

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 file:

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.

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:

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.

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

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

• Build and deploy your changes.

Note:

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

Environment variables are added in divoc-config.yml in the orchestration node.

Steps to add the environment variables:

• To display the config map, run the following command:

• If multiple config maps exist, add environment variables to all the config maps.

• To edit the config map, run the following command:

• Next, add the variables under ‘data.’ Save and exit.

• Restart the services where environment variables have been used by running the following command:

All content on this page by is licensed under a .

Making changes to DIVOC’s certificate module via etcd

We have added etcd as a configuration management tool for DIVOC. This makes it easier for implementing partners to add new vaccines, edit templates or the QR code payload, as well as add new configurations without deploying any components. Use any etcd client that you like - for example, the . Following are the steps to set up the etcd-manager:

• Open the URL: and click on Download.

• To configure the host and port number: open the etcd manager app → go to settings → click on etcd → enter the respective host IP and port.

• If authentication is configured for etcd, enter the authentication credentials. Go to Settings -> Auth -> enter username and password.

• Click on the test connection to confirm connectivity and click on save.

• Next, go to the Manage keys tab on the left. You should be able to see the configurations already setup.

Once the etcd manager app is installed, the following can be seamlessly managed within DIVOC:

All content on this page by is licensed under a .

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 .

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

• The platform provides flexibility to update values in the ‘recipient,’ ‘vaccination,’ ‘vaccinator,’ and ‘facility’ sections. Click 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 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.

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:

Using ETCD CLI, the same can be dynamically updated in two files (VACCINE_ICD.json and ICD.json) without any service deployments.

Steps to update the vaccine name and its ICD-11 mapping:

• Go to the specific folder where etcd files are available.

• Open the files to add the new vaccine.

• Run the command: vim VACCINE_ICD.json.

• Run the command: vim ICD.json.

• To reflect the change, run the command: ./updateConfigs.sh. It shows "OK OK OK...." This means that the etcd has been updated with new vaccine list successfully.

• Create the certificate and generate the PDF with the new vaccine.

There are different International Classification of Diseases (ICD) codes based on the category of vaccines. To add a new vaccine, identify the ICD-11 code to which the vaccine belongs. Once you have mapped the vaccine to the relevant ICD-11 code, you can update the vaccine name and its ICD-11 mapping in etcd.

Steps to update the vaccine name and its ICD-11 mapping:

• Go to the Manage keys tab of the etcd-manager app. To add or update mappings, two keys must be updated: “VACCINE_ICD” and “ICD.”

• To add the vaccine name, ICD-11 code, and description VACCINE_ICD, go to VACCINE_ICD and click on the Edit key.

- Example of VACCINE_ICD value for Covaxin:

{“vaccineName”: “covaxin”, “icd11Code”: “XM1G90”}

• Click on Save. A popup will appear as “operation successful.” Click on Close.

• Click on the edit button of the “ICD” key to add ICD-11 code and click on the Edit key.

- Example of ICD value for Covaxin:

{“XM1G90”: {“vaccineType”: “inactivated virus”, “icd11Term”: “COVID-19 vaccine, inactivated virus”}}

• Click on Save. A popup will appear as “operation successful.” Click on Close.

• Make the certificate generation request call and fetch the certificate to test the changes. Once updated, any new certificate can be issued using the new vaccine name.

With the ETCD CLI, the same can be dynamically updated in the files (euVaccineProph.json and euVaccineCode.json) without any service deployments.

Steps to add the extra EU vaccine configurations

• Go to the specific path where etcd is configured.

• Open the files to add the new vaccine or update the existing vaccine.

• Run the command: vim euVaccineCode.json.

• Run the command:vim euVaccineProph.json.

• To reflect the change, run the command: ./updateConfigs.sh. It shows "OK OK OK...."This means that etcd has been updated with the new vaccine list successfully.

• Create the certificate and generate the PDF with the new vaccine.

Any template-related changes can be done by updating the HTML template using ETCD CLI. Before making any change, the PDF template will look like:

Example: Adding a field such as ‘nationality’ to the PDF template.

Steps to add 'nationality' to the PDF template:

• Go to the specific path where etcd is configured.

• Open the file to add the new field that will get displayed in the template (vim vaccineCertificateTemplate.html).

• To reflect the change, run the updateConfigs shell script using the command: ./updateConfigs.sh. It shows "OK OK OK...." This means that etcd has been updated with the new template successfully.

• Generate the PDF again using GET API.

To add a new vaccine to an EU certificate, a country must identify the EU code to which the vaccine belongs. The coded value sets used in EU vaccination certificates include:

• vp: COVID-19 vaccine or prophylaxis

• mp: COVID-19 vaccine product

• ma: COVID-19 vaccine marketing authorisation holder or manufacturer

Steps to add the extra field in the certificate:

• Go to the specific path where etcd is configured.

• To add the extra field in the template, go to the Manage keys where etcd is configured.

• To add the vaccine code, go to euVaccineCode and click on the Edit key to add the vaccine name and code.

- Example for Covaxin:

{“covaxin”: “Covaxin”}

• Click on Save. A popup will appear as “operation successful.” Click on Close.

• To add the prophylaxis, go to euVaccineProph and click on the Edit key to add the vaccine name and code.

- Example for Covaxin:

{“covaxin”: “J07BX03”}

• Click on Save. A popup will appear as “operation successful.” Click on Close.

• To add the manufacturer, go to euVaccineManuf. Click on the Edit key to add the new manufacturer.

- Example for Covaxin:

{“bharat”: “Bharat-Biotech”}

• Click on Save. A popup will appear as “operation successful.” Click on Close.

• Once the mappings are available in etcd, you can create the certificate and generate the PDF with the new vaccine.

Any template-related changes can be done by updating the HTML template in the etcd manager. Supported fields include the following:

Example: Adding a field such as ‘nationality’ to the PDF template.

Steps to add ‘nationality’ to the PDF template:

• Go to the Manage keys in the etcd-manager.

• Go to the “vaccineCertificateTemplate” key and click on the Edit key to update the template. In this case, the ‘nationality’ field is being added. The value expected for the “vaccineCertificateTemplate” configuration is html and can be customised as per your needs.

• The same will be reflected in the PDF of the vaccination certificate. Click on Save. A popup will appear as “operation successful.” Click on Close.

• Call “GET VaccineCertificate API,” which will return the PDF certificate template. Verify if the new field ‘nationality’ is getting reflected.

Currently, only the optional fields that already exist can be removed. New fields cannot be added as of now.

Note: Do not remove the mandatory fields.

Steps to remove an optional field:

Run the command: vim DDCC_TEMPLATE.template.

To reflect the change, run the command: ./updateConfigs.sh. It shows "OK OK OK...." This means that etcd has been updated with the new QR Code template successfully.

• DIVOC certificates are natively digital, verifiable, digitally signed, and also printable with a secure and tamper-proof QR code.

• The QR payload structure is based on the W3C verifiable credentials data model.

• Previously, any changes in the QR payload required changing it in the certificate-signer service and subsequent deployment.

• With DIVOC 2.0, QR payload changes can now be made by changing it in etcd without any deployments.

• Currently, only the optional fields that already exist can be removed. New fields cannot be added as of now.

• Note: Do not remove the mandatory fields.

Steps to remove an optional field:

• Go to DDCC_TEMPLATE. Click on the Edit key if you want to remove an optional field.

• Click on Save. A popup will appear as “operation successful.” Click on Close.