dcc

README

GO-DCC

A simple library to View, Generate and Verify EU-DCC / Vaccine Passes
Explore the docs »

Report Bug · Request Feature

About This Package

This package offers simple API calls to Decode, Encode and Verify Vaccine Passes.
APIs are subject to changes as improvements are made.

Getting Started

Prerequisites

Go get the module to import it into your project

1. Download package

   go get -u github.com/reznik99/go-dcc
   

Usage

Below is some examples of how you can use this package, without explicit error handling for simplicity's sake

1. To generate a Vaccine Pass using data from data.json

   import (
       "github.com/reznik99/go-dcc"
   )
   
   func main() {
        // Base64 of first 8 bytes in Signer Certificate
        kid := "dy8HnMQYOrE="
   
        // Generate or load Signer Key
        privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
   
        // Generate/Sign Vaccine Pass and save as QR code
        dcc.GenerateQR(privKey, kid, "/path/to/data.json", "/path/to/new-pass.png")
   
        // Generate/Sign Vaccine Pass Raw string "HC1:..."
        dcc.Generate(privKey, kid, "/path/to/data.json")
   }
   

2. To validate/verify a Vaccine Pass

   import (
       "github.com/reznik99/go-dcc"
   )
   
   func main() {
        // Parse Raw Vaccine Pass
        _, rawMsg, _ := dcc.Parse("/path/to/mypass.txt")
        // Parse QR Code Vaccine Pass
        _, rawMsg, _ := dcc.ParseQR("/path/to/mypass.png")
   
        // Verify Vaccine Pass signature. note: currently slow! This will fetch the PEM Signer Certificates and KIDs
        valid, _ := dcc.Verify(rawMsg)
   
        fmt.Printf("Vaccine Pass Valid: %t\n", valid)
   }
   

3. To decode/read a Vaccine Pass

    import (
        "fmt"
        "github.com/reznik99/go-dcc"
        "github.com/ethereum/go-ethereum/common/hexutil"
    )
   
    func main() {
        // Parse Raw Vaccine Pass
        payload, _, _ := dcc.Parse("/path/to/mypass.txt")
        // Parse QR Code Vaccine Pass
        payload, _, _ := dcc.ParseQR("/path/to/mypass.png")
   
        // Print contents to STDOUT
        prettyDCC, _ := json.MarshalIndent(payload, "", "	")
        fmt.Printf("Headers:   %v\n", rawMsg.Headers)
        fmt.Printf("Payload:   %s\n", prettyDCC)
        fmt.Printf("Signature: %s\n", hexutil.Encode(rawMsg.Signature))
    }
   

Example JSON data file

    {
        "name": "JOHN",
        "surname": "DOE",
        "dob": "1996-06-06",
        "issuerCountry": "NZ",
        "issuer": "Ministry of Health, NZ",
        "vaccinationDate": "2021-10-21",
        "doses": 2
    }

For more examples, please refer to the Documentation

(back to top)

Roadmap

• Decode/Read EU DCC certs
• Encode/Generate EU DCC certs (Valid schema but not valid signature obviously)
• Verify/Validate EU DCC certs (This is not working quite yet)
• Improve KID and Signer Certificate fetching logic or allow user to specify values for performance.

See the open issues for a full list of proposed features (and known issues).

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Francesco Gorini - goras.francesco@gmail.com - https://francescogorini.com

Project Link: https://github.com/reznik99/go-dcc/

(back to top)

Documentation

Index

• Variables
• func Generate(key crypto.Signer, kid, dataPath string) (dccBase45 string, err error)
• func GenerateQR(key crypto.Signer, kid, dataPath, outputPath string) error
• func Verify(raw *cose.Sign1Message) (valid bool, err error)
• type Config
• type DCC
  • func Parse(path string) (payload *DCC, messageRaw *cose.Sign1Message, err error)
  • func ParseQR(path string) (payload *DCC, messageRaw *cose.Sign1Message, err error)
• type DCCPayload
• type HCert
• type Nam
• type V

Variables

var (
	GreenPassVersion       = "1.3.0"
	SNOMEDCovidCode        = "840539006"
	VaccineProduct         = "EU/1/20/1528"
	VaccineType            = "1119349007"    // SARS-CoV-2 mRNA vaccine
	MarketingAuthorisation = "ORG-100030215" // Biontech Manufacturing GmbH
)

var (
	API_BASE_URL = "https://get.dgc.gov.it/v1/dgc"
)

Functions

func Generate

func Generate(key crypto.Signer, kid, dataPath string) (dccBase45 string, err error)

Generates Vaccine Passport with json data read from 'dataPath' and returns raw Vaccine Pass string as `HC1:...`

func GenerateQR

func GenerateQR(key crypto.Signer, kid, dataPath, outputPath string) error

Generates Vaccine Passport with json data read from 'dataPath' and writes the Vaccine Pass as a QR code file at 'outputPath'

func Verify

func Verify(raw *cose.Sign1Message) (valid bool, err error)

Verify a Vaccine Passport's signature, it reads the *cose.Sign1Message parameter and returns the status and/or error. This function makes network requests (HTTP) to fetch the KIDs to verify the pass

Types

type Config

type Config struct {
	Name            string `json:"name"`
	Surname         string `json:"surname"`
	Dob             string `json:"dob"`
	IssuerCountry   string `json:"issuerCountry"`
	Issuer          string `json:"issuer"`
	VaccinationDate string `json:"vaccinationDate"`
	Doses           int    `json:"doses"`
}

DCC Payload data to be read from file

type DCC

type DCC struct {
	ExpirationTime    int    `cbor:"4,keyasint,omitempty" json:"4"`
	IssuedAt          int    `cbor:"6,keyasint,omitempty" json:"6"`
	Issuer            string `cbor:"1,keyasint,omitempty" json:"1"`
	HealthCertificate HCert  `cbor:"-260,keyasint,omitempty" json:"-260"`
}

DCC (Digital Covid Certificate) Top Level CBOR structure Section 3.3.1 at https://ec.europa.eu/health/sites/default/files/ehealth/docs/digital-green-certificates_v1_en.pdf

func Parse

func Parse(path string) (payload *DCC, messageRaw *cose.Sign1Message, err error)

Parse parses a Vaccine Passport, it reads the file at 'path' and returns the Pass Payload and Raw COSE message containing headers, payload and signatures

func ParseQR

func ParseQR(path string) (payload *DCC, messageRaw *cose.Sign1Message, err error)

ParseQR parses a Vaccine Passport, it reads the image file at 'path', decoding the QR code and returns the Pass Payload and Raw COSE message containing headers, payload and signatures

type DCCPayload

type DCCPayload struct {
	Nam Nam    `json:"nam"`
	Dob string `json:"dob"` // Date of birth in range of 1900-0-01 to 2099-12-31
	V   []V    `json:"v"`   // Vaccination group
	Ver string `json:"ver"`
}

type HCert

type HCert struct {
	DGC DCCPayload `cbor:"1,keyasint,omitempty" json:"1"`
}

type Nam

type Nam struct {
	Fn  string `json:"fn"`  // Surname
	Fnt string `json:"fnt"` // Standardised Surname
	Gn  string `json:"gn"`  // Forename
	Gnt string `json:"gnt"` // Standardised Forename
}

type V

type V struct {
	Dn int    `json:"dn"` // Number in a series of doses
	Sd int    `json:"sd"` // The overall number of doses
	Mp string `json:"mp"` // Vaccine Product
	Dt string `json:"dt"` // Date of vaccination
	Tg string `json:"tg"` // Disease or agent targeted
	Vp string `json:"vp"` // Vaccine or Prophylaxis
	Ma string `json:"ma"` // Vaccine marketing authorisation holder or manufacturer
	Co string `json:"co"` // Member state which administered the vaccine
	Is string `json:"is"` // Certificate Issuer
	Ci string `json:"ci"` // Unique certificate identifier
}

DCC Payload for Vaccination group type of HCERT