coronaqr

README

Go Corona QR Code Decoder

This repository contains a decoder and verifier for EU Digital COVID Certificate (EUDCC) QR code data, written in Go.

If you got vaccinated and want to know what is stored in the QR code, this package (and example program) can answer that question!

Example usage:

go install github.com/stapelberg/coronaqr/cmd/coronadecode@latest

apt install curl zbar-tools
curl -sL https://github.com/eu-digital-green-certificates/dgc-testdata/raw/main/CH/png/1.png | \
	zbarimg --quiet --raw - | \
	coronadecode

(With older Go versions before 1.16, use go get -u github.com/stapelberg/coronaqr/cmd/coronadecode instead.)

Verification

For cryptographic signature 🔐 verification to work, you need to obtain a trust list from somewhere, i.e. a list of certificates that you deem suitable for verification.

The trustlistmirror package implements loading the trust lists of the German, Austrian or French governments, which each include all the certificates that are accepted EU-wide.

This is how you would select which trust list to use:

curl -sL https://github.com/eu-digital-green-certificates/dgc-testdata/raw/main/CH/png/1.png | \
        zbarimg --quiet --raw - | \
        coronadecode -verify -trustlist=trustlistmirror/at

Compliance

This implementation passes the positive and negative interoperability tests ✅ of multiple countries provided in the https://github.com/eu-digital-green-certificates/dgc-testdata/ repository.

Documentation

Overview

Package coronaqr provides a decoder for EU Digital COVID Certificate (EUDCC) QR code data.

See https://github.com/eu-digital-green-certificates for the specs, testdata, etc.

Index

• Variables
• type CertificateProvider
• type CovidCert
• type Decoded
• type Decoder
  • func (d *Decoder) Decode(qrdata string) (*Unverified, error)
• type Name
• type PublicKeyProvider
• type RecoveryRecord
• type TestRecord
• type Unverified
  • func Decode(qrdata string) (*Unverified, error)
  • func (u *Unverified) SkipVerification() *Decoded
  • func (u *Unverified) Verify(certprov PublicKeyProvider) (*Decoded, error)
• type VaccineRecord

Variables

var DefaultDecoder = &Decoder{}

DefaultDecoder is a ready-to-use Decoder.

Types

type CertificateProvider

type CertificateProvider interface {
	// GetCertificate returns the public key of the certificate for the
	// specified country and key identifier, or an error if the certificate was
	// not found.
	//
	// Country is a ISO 3166 alpha-2 code, e.g. CH.
	//
	// kid are the first 8 bytes of the SHA256 digest of the certificate in DER
	// encoding.
	GetCertificate(country string, kid []byte) (*x509.Certificate, error)
}

CertificateProvider is typically implemented using a JSON Web Key Set, or by pinning a specific government certificate.

type CovidCert

type CovidCert struct {
	Version         string           `cbor:"ver" json:"version"`
	PersonalName    Name             `cbor:"nam" json:"name"`
	DateOfBirth     string           `cbor:"dob" json:"dateOfBirth"`
	VaccineRecords  []VaccineRecord  `cbor:"v" json:"vaccineRecords"`
	TestRecords     []TestRecord     `cbor:"t" json:"testRecords"`
	RecoveryRecords []RecoveryRecord `cbor:"r" json:"recoveryRecords"`
}

type Decoded

type Decoded struct {
	Cert       CovidCert
	IssuedAt   time.Time
	Expiration time.Time

	// SignedBy is the x509 certificate whose signature of the COVID Certificate
	// has been successfully verified, if Verify() was used and the trustlist
	// makes available certificates (as opposed to just public keys).
	SignedBy *x509.Certificate
}

Decoded is a EU Digital COVID Certificate (EUDCC) that has been decoded and possibly verified.

type Decoder

type Decoder struct {
	Expired func(time.Time) bool
}

Decoder is a EU Digital COVID Certificate (EUDCC) decoder.

func (*Decoder) Decode

func (d *Decoder) Decode(qrdata string) (*Unverified, error)

Decode decodes the specified EU Digital COVID Certificate (EUDCC) QR code data.

type Name

type Name struct {
	FamilyName    string `cbor:"fn" json:"familyName"`
	FamilyNameStd string `cbor:"fnt" json:"familyNameStd"`
	GivenName     string `cbor:"gn" json:"givenName"`
	GivenNameStd  string `cbor:"gnt" json:"givenNameStd"`
}

type PublicKeyProvider

type PublicKeyProvider interface {
	// GetPublicKey returns the public key of the certificate for the specified
	// key identifier (or country), or an error if the public key was not found.
	//
	// Country is a ISO 3166 alpha-2 code, e.g. CH.
	//
	// kid are the first 8 bytes of the SHA256 digest of the certificate in DER
	// encoding.
	GetPublicKey(country string, kid []byte) (crypto.PublicKey, error)
}

PublicKeyProvider is typically implemented using a JSON Web Key Set, or by pinning a specific government certificate.

type RecoveryRecord

type RecoveryRecord struct {
	Target string `cbor:"tg" json:"target"`

	// ISO 8601 complete date of first positive NAA test result
	FirstPositiveTestDate string `cbor:"fr" json:"firstPositiveTestDate"`
	ValidFromDate         string `cbor:"df" json:"validFromDate"`  // ISO 8601 complete date
	ValidUntilDate        string `cbor:"du" json:"validUntilDate"` // ISO 8601 complete date

	// Country of Test
	Country       string `cbor:"co" json:"country"`
	Issuer        string `cbor:"is" json:"issuer"`
	CertificateID string `cbor:"ci" json:"certificateID"`
}

type TestRecord

type TestRecord struct {
	Target   string `cbor:"tg" json:"target"`
	TestType string `cbor:"tt" json:"testType"`

	// Name is the NAA Test Name
	Name string `cbor:"nm" json:"name"`

	// Manufacturer is the RAT Test name and manufacturer.
	Manufacturer   string `cbor:"ma" json:"manufacturer"`
	SampleDatetime string `cbor:"sc" json:"sampleDatetime"`
	TestResult     string `cbor:"tr" json:"testResult"`
	TestingCentre  string `cbor:"tc" json:"testingCentre"`
	// Country of Test
	Country       string `cbor:"co" json:"country"`
	Issuer        string `cbor:"is" json:"issuer"`
	CertificateID string `cbor:"ci" json:"certificateID"`
}

type Unverified

type Unverified struct {
	// contains filtered or unexported fields
}

Unverified is a EU Digital COVID Certificate (EUDCC) that was decoded, but not yet verified.

func Decode

func Decode(qrdata string) (*Unverified, error)

Decode decodes the specified EU Digital COVID Certificate (EUDCC) QR code data.

func (*Unverified) SkipVerification

func (u *Unverified) SkipVerification() *Decoded

SkipVerification skips all cryptographic signature verification and returns the unverified certificate data.

func (*Unverified) Verify

func (u *Unverified) Verify(certprov PublicKeyProvider) (*Decoded, error)

Verify checks the cryptographic signature and returns the verified EU Digital COVID Certificate (EUDCC) or an error if verification fails.

certprov can optionally implement the CertificateProvider interface.

type VaccineRecord

type VaccineRecord struct {
	Target        string  `cbor:"tg" json:"target"`
	Vaccine       string  `cbor:"vp" json:"vaccine"`
	Product       string  `cbor:"mp" json:"product"`
	Manufacturer  string  `cbor:"ma" json:"manufacturer"`
	Doses         float64 `cbor:"dn" json:"doses"`      // int per the spec, but float64 e.g. in IE
	DoseSeries    float64 `cbor:"sd" json:"doseSeries"` // int per the spec, but float64 e.g. in IE
	Date          string  `cbor:"dt" json:"date"`
	Country       string  `cbor:"co" json:"country"`
	Issuer        string  `cbor:"is" json:"issuer"`
	CertificateID string  `cbor:"ci" json:"certificateID"`
}

see https://github.com/ehn-dcc-development/ehn-dcc-schema/blob/release/1.3.0/DCC.Types.schema.json