EU Digital COVID Certificate Kit

A Swift Package to decode, verify and validate EU Digital COVID Certificates
for iOS, tvOS, watchOS and macOS.

Disclaimer

The EUDCCKit is not an offical implementation of the EU Digital COVID Certificate

Features

  • [x] Easily decode an EU Digital COVID Certificate ?
  • [x] Verify cryptographic signature ?
  • [x] Certificate validation ✅

Installation

Swift Package Manager

To integrate using Apple's Swift Package Manager, add the following as a dependency to your Package.swift:

dependencies: [
    .package(url: "https://github.com/SvenTiigi/EUDCCKit.git", from: "0.0.1")
]

Or navigate to your Xcode project then select Swift Packages, click the “+” icon and search for EUDCCKit.

Usage

The EUDCCKit Swift Package is made of four distinct libraries to decode, verify and validate an EU Digital COVID Certificate.

EUDCC

The EUDCC library contains the model definition of the EU Digital COVID Certificate

import EUDCC

// The EU Digital COVID Certificate model
let eudcc: EUDCC

// Access content of EUDCC
switch eudcc.content {
case .vaccination(let vaccination):
    print("Vaccination", vaccination)
case .test(let test):
    print("Test", test)
case .recovery(let recovery):
    print("Recovery", recovery)
}

Head over to the advanced section to learn more.

EUDDCDecoder

The EUDCCDecoder library provides an EUDCCDecoder object which is capabale of decoding a Base-45 string reperesentation of the EU Digital COVID Certificate which is mostly embedded in a QR-Code.

import EUDCCDecoder

// Initialize an EUDCCDecoder
let decoder = EUDCCDecoder()

// The Base-45 encoded EU Digital COVID Certificate from a QR-Code
let qrCodeContent = "HC1:..."

// Decode EUDCC from QR-Code
let decodingResult = decoder.decode(from: qrCodeContent)

// Switch on decoding result
switch decodingResult {
case .success(let eudcc):
    // Successfully decoded Digital COVID Certificate
    print("EU Digital COVID Certificate", eudcc)
case .failure(let decodingError):
    // Decoding failed with error
    print("Failed to decode EUDCC", decodingError)
}

Head over to the advanced section to learn more.

EUDCCVerifier

The EUDCCVerifier library provides an EUDCCVerifier object which can be used to verify the cryptographic signature of the EU Digital COVID Certificate.

import EUDCCVerifier

// Initialize an EUDDCCVerifier
let verifier = EUDCCVerifier(
    trustService: EUCentralEUDCCTrustService()
)

// Verify EU Digital COVID Certificate
verifier.verify(eudcc: eudcc) { verificationResult in
    // Switch on verification result
    switch verificationResult {
    case .success(let trustCertificate):
        print("Cryptographically valid", trustCertificate)
    case .invald:
        print("Invalid EUDCC")
    case .failure(let error):
        print("Error occured during verification", error)
    }
}

Head over to the advanced section to learn more.

EUDCCValidator

The EUDCCValidator library provides an EUDCCValidator object which can be used to validate the EU Digital COVID Certifiate based on given rules.

import EUDCCValidator

// Initialize an EUDCCValidator
let validator = EUDCCValidator()

// Validate EU Digital COVID Certificate
let validationResult = validator.validate(
    eudcc: eudcc,
    rule: .isFullyImmunized() && !.isVaccinationExpired()
)

// Switch on validation result
switch validationResult {
case .success:
    // Successfully validated EU Digital COVID Certificate
    print("Successfully validated")
case .failure(let validationError):
    // Validation failure
    print("Validation failed", validationError)
}

Head over to the advanced section to learn more.

Advanced

EUDCC

Content

Beside the content property of an EUDCC you can make use of the following convenience properties to check if the EUDCC contains a vaccination, test or recovery object.

import EUDCC

// Vaccination
let vaccination: EUDCC.Vaccination? = eudcc.vaccination

// Test
let test: EUDCC.Test? = eudcc.test

// Recovery
let recovery: EUDCC.Recovery? = eudcc.recovery

Well-Known-Value

Each of the following objects are exposing a WellKnownValue enumeration which can be used to retrieve more detailed information about a certain value:

  • EUDCC.DiseaseAgentTargeted
  • EUDCC.Test.TestResult
  • EUDCC.Test.TestType
  • EUDCC.Vaccination.VaccineMarketingAuthorizationHolder
  • EUDCC.Vaccination.VaccineMedicinalProduct
  • EUDCC.Vaccination.VaccineOrProphylaxis
import EUDCC

let vaccineMedicinalProduct: EUDCC.Vaccination.VaccineMedicinalProduct

// Switch on WellKnownValue of VaccineMedicinalProduct
switch vaccineMedicinalProduct.wellKnownValue {
    case .covid19VaccineModerna:
        break
    case .vaxzevria:
        break
    default:
        break
}

Encoding

The EUDCC contains two properties cryptographicSignature and base45Representation which are convenience objects that are not an offical part of the EU Digital COVID Certificate JSON Schema.

If you wish to skip those properties when encoding an EUDCC you can set the following userInfo configuration to a JSONEncoder.

import EUDCC

let encoder = JSONEncoder()

encoder.userInfo = [
    // Skip encoding CryptographicSignature
    EUDCC.EncoderUserInfoKeys.skipCryptographicSignature: true,
    // Skip encoding Base-45 representation
    EUDCC.EncoderUserInfoKeys.skipBase45Representation: true,
]

let jsonData = try encoder.encode(eudcc)

EUDDCDecoder

Decoding

The EUDCCDecoder supports decoding a Base-45 encoded String and Data object.

import EUDCCDecoder

let eudccDecoder = EUDCCDecoder()

// Decode from Base-45 encoded String
let eudccBase45EncodedString: String
let stringDecodingResult = eudccDecoder.decode(
    from: eudccBase45EncodedString
)

// Decode from Base-45 encoded Data
let eudccBase45EncodedData: Data
let dataDecodingResult = eudccDecoder.decode(
    from: eudccBase45EncodedData
)

Convenience decoding

By importing the EUDCCDecoder library the EUDCC object will be extended with a static decode function.

import EUDCCDecoder

let decodingResult = EUDCC.decode(from: "HC1:...")

EUDCCVerifier

EUDCCTrustService

In order to verify an EUDCC the EUDCCVerifier needs to be instantiated with an instance of an EUDCCTrustService which is used to retrieve the trust certificates.

import EUDCC
import EUDCCVerifier

struct SpecificEUDCCTrustService: EUDCCTrustService {
    
    /// Retrieve EUDCC TrustCertificates
    /// - Parameter completion: The completion closure
    func getTrustCertificates(
        completion: @escaping (Result<[EUDCC.TrustCertificate], Error>) -> Void
    ) {
        // TODO: Retrieve TrustCertificates and invoke completion handler
    }
    
}

let eudccVerifier = EUDCCVerifier(
    trustService: SpecificEUDCCTrustService()
)

The EUDCCKit comes along with two pre defined EUDCCTrustService implementations:

  • EUCentralEUDCCTrustService
  • RobertKochInstituteEUDCCTrustService

If you wish to retrieve certificates from multiple EUDCCTrustService implementation you can make use of the GroupableEUDCCTrustService:

let trustService = GroupableEUDCCTrustService(
    trustServices: [
        EUCentralEUDCCTrustService(),
        RobertKochInstituteEUDCCTrustService()
    ]
)

trustService.getTrustCertificates { certificates in
    // ...
}

Convenience verification

By importing the EUDCCVerifier library the EUDCC object will be extended with a verify function.

import EUDCC
import EUDCCVerifier

let eudcc: EUDCC

eudcc.verify(
    using: EUDCCVerifier(
        trustService: EUCentralEUDCCTrustService()
    )
) { verificationResult in
    switch verificationResult {
    case .success(let trustCertificate):
        break
    case .invald:
        break
    case .failure(let error):
        break
    }
}

EUDCCValidator

ValidationRule

An EUDCC can be validated by using an EUDCCValidator and a given EUDCC.ValidationRule. An EUDCC.ValidationRule can be initialized with a simple closure wich takes in an EUDCC and returns a Bool whether the validation succeed or failed.

import EUDCC
import EUDCCValidator

// Simple EUDCC ValidationRule instantiation
let validationRule = EUDCC.ValidationRule { eudcc in
    // Process EUDCC and return Bool result
}

// EUDCC ValidationRule with Tag in order to uniquely identify a ValidationRule
let isVaccinationComplete = EUDCC.ValidationRule(
    tag: "is-vaccination-complete"
) { eudcc in
    eudcc.vaccination?.doseNumber == eudcc.vaccination?.totalSeriesOfDoses
}

The EUDCCKit comes along with many pre defined EUDCC.ValidationRule like the following ones.

import EUDCC
import EUDCCValidator

let eudcc: EUDCC
let validator = EUDCCValidator()

// Is fully immunized
validator.validate(
    eudcc: eudcc, 
    rule: .isFullyImmunized(minimumDaysPast: 15)
)

// Is tested positive
validator.validate(
    eudcc: eudcc, 
    rule: .isTestedPositive
)

Logical/Conditional operators

In order to create more complex rules each EUDCC.ValidationRule can be chained together by applying standard operators.

import EUDCC
import EUDCCValidator

let defaultValidationRule: EUDCC.ValidationRule = .if(
    .isVaccination,
    then: .isFullyImmunized() && .isWellKnownVaccineMedicinalProduct && !.isVaccinationExpired(),
    else: .if(
        .isTest,
        then: .isTestedNegative && .isTestValid(),
        else: .if(
            .isRecovery,
            then: .isRecoveryValid,
            else: .constant(false)
        )
    )
)

Convenience validation

By importing the EUDCCValidator library the EUDCC object will be extended with a validate function.

import EUDCC
import EUDCCValidator

let eudcc: EUDCC

let validationRule = eudcc.validate(
    rule: .isWellKnownVaccineMedicinalProduct
)

GitHub

https://github.com/SvenTiigi/EUDCCKit