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?

1. Generating signed key pairs

2. How to configure the certificate generation component?

3. How to set up the verification portal for your implementation?

4. How to configure the update certificate API?

5. Configuring environment variables in 2.0

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 and map the dynamic fields in the certificate template.

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.

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

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).

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:

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

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

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.

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:

• Generating signed key pairs

• Certificate generation request

• QR code section

• Certificate template

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:

[
    {
        "preEnrollmentCode": "62",
        "recipient": {
            "name": "Sam",
            "uhid": "abc2232",
            "dob": "1990-09-14",
            "age": "31",
            "gender": "Male",
            "nationality": "India",
            "identity": "did:in.gov.uidai.aadhaar:11112222334",
            "contact": [
                "tel:1111111313"
            ],
            "address": {
                "addressLine1": "123, Koramangala",
                "addressLine2": "",
                "district": "Bengaluru South",
                "state": "bihar",
                "pincode": "560033"
            }
        },
        "vaccination": {
            "name": "covaxin",
            "batch": "AB348FS",
            "manufacturer": "Bharat Biotech",
            "date": "2021-07-12T19:21:19.646Z",
            "effectiveStart": "2021-07-12",
            "effectiveUntil": "2021-08-12",
            "dose": 2,
            "totalDoses": 2
        },
        "vaccinator": {
            "name": "Sooraj Singh"
        },
        "facility": {
            "name": "ABCD Medical Center",
            "address": {
                "addressLine1": "123, Koramangala",
                "addressLine2": "",
                "district": "Bengaluru South",
                "state": "Karnataka",
                "pincode": "560033"
            }
        },
        "programId": "6ce74c0f-b1b5-4b20-9fa2-084acbbd857a",
        "meta": { //Meta section stored as an Object and it can contain information in    Key value pair
        }
    }
]\

• Refer to the /v3/certify service here for details.

• 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.

Key Functionalities

• Generate configured QR code

• Generate configured certificate template

Prerequisite: Get details on API request and field validations

a. Please refer to the existing service details in the ‘certification’ section (/v3/certify): https://egovernments.github.io/DIVOC/developer-docs/api/admin-api.html#../../india/interfaces/vaccination-api.yaml

b. The detailed field validations are mentioned here: https://github.com/egovernments/DIVOC/blob/4076e69cf152fd76dafa8a0565777895f55b1245/interfaces/vaccination-api.yaml

// /v3/certify:
    post:
      tags:
        - certification
      summary: Certify the one or more vaccination
      description: >-
        Certification happens asynchronously, this requires vaccinator
        authorization and vaccinator should be trained for the vaccination that
        is being certified. The payload for this API is compliant with DDCC core
        data set prescribed by WHO
      operationId: certifyV3
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/CertificationRequestV2' //Refer Line 722 in same file 
      responses:
        '200':
          description: OK
        '400':
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'

Making the changes

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

1. Create a certification generation request

2. Update the QR code content

3. Update the certificate template

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 .

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:

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.