admin-ch / covidcertificate-sdk-ios

CovidCertificate SDK for iOS

CovidCertificate-SDK-iOS

Introduction

This is the implementation of the Electronic Health Certificates (EHN) specification used to verify the validity of COVID Certificates in Switzerland.

It is partly based on the reference implementation of EHN's ValidationCore [2].

Contribution Guide

This project is truly open-source and we welcome any feedback on the code regarding both the implementation and security aspects.

Bugs or potential problems should be reported using Github issues. We welcome all pull requests that improve the quality of the source code.

Repositories

• iOS App: CovidCertificate-App-iOS
• Android App: CovidCertificate-App-Android
• Android SDK: CovidCertificate-SDK-Android
• For all others, see the Github organisation

Installation

Swift Package Manager

CovidCertificateSDK is available through Swift Package Manager

1. Add the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/admin-ch/CovidCertificate-SDK-iOS.git", .branch("main"))
]

This version points to the HEAD of the main branch and will always fetch the latest development status. Releases will be made available using semantic versioning to ensure stability for depending projects.

Cocoapods

CovidCertificateSDK is available through Cocoapods

1. Add the following to your Podfile:

pod 'CovidCertificateSDK', '~> 1.0'

This version points to the HEAD of the main branch and will always fetch the latest development status. Releases will be made available using semantic versioning to ensure stability for depending projects.

Summary: How the SDK works

The SDK provides the functionality of decoding a QR code into an electronic health certificate and verifying the validity of the decoded certificate. It also takes care of loading and storing the latest trust list information that is required for verification. The trust list is a data model that contains a list of trusted public signing keys, a list of revoked certificate identifiers and the currently active national rules.

Decoding

Decoding a QR code into a COVID certificate uses the following steps. For more information, refer to the EHN specification.

1. Check the prefix of the data. Only HC1: (EU Dcc Certificate) and LT1: (CH Certificate Light) are valid prefixes
2. Base45 decode the data ^[1]
3. ZLIB decompress the data
4. COSE decode the data ^[2]
5. CBOR decode the data and parse it into a CertificateHolder containing either a DCCCert or a LightCert

Verification

The verification process consists of three parts that need to be successful in order for a certificate to be considered valid.

1. The certificate signature is verified against a list of trusted public keys from issueing countries
2. The UVCI (unique vaccination certificate identifier) is compared to a list of revoked certificates to ensure the certificate has not been revoked
3. The certificate details are checked based on the Swiss national rules for certificate validity. (Is the number of vaccination doses sufficient, is the test recent enough, how long ago was the recovery?)

Usage: How to use the SDK

The SDK needs to be initialized with an environment and a API token. This allows for different verification rules per environment or other environment-specific settings.

If you intend to integrate the CovidCertificate-SDK-iOS into your app, please get in touch with the BAG to get a token assigned.

After initialization the following pipeline should be used:

1. Decode the base45 and prefixed string to retrieve a Digital Covid Certificate

2. Verify the Certificate by calling the .check method. Internally this verifies the signature, revocation status and national rules

All these checks check against verification properties that are loaded from a server. These returned properties use a property to specify how long they are valid (like max-age in general networking). With the parameter forceUpdate, these properties can be forced to update.

CovidCertificateSDK offers a Verifier and Wallet namespace. Methods in the Wallet namespace must only be used by the official COVID Certificate App.

Decoding

let result: Result<VerifierCertificateHolder, CovidCertError> = CovidCertificateSDK.Verifier.decode(encodedData: qrCodeString)

Verification

CovidCertificateSDK.Verifier.check(holder: certificateHolder, mode: checkMode) { result: CheckResults in
        result.signatureResult
        result.revocationStatus
        result.nationalRules
        result.modeResults                                                                        
}

Verification Modes

A verification mode collects together a set of verification rules. Examples of verification modes are "2G", "3G".

Unlike you might expect, the SDK does NOT hardcode the different verification modes into an enum. Instead, they are provided dynamically by the backend. This in order to integrate with the CertLogic rules that drive the verification process (which are also provided dynamically).

DO NOT hardcode the verification modes! If the backend changes the available modes, your app may crash!

To obtain a list of currently available verification modes:

var activeModes: [CheckMode] = CovidCertificateSDK.Verifier.activeModes

License

This project is licensed under the terms of the MPL 2 license. See the LICENSE file for details.

References

[1] Health Certificate Specification

[2] Validation Core

covidcertificate-sdk-ios's Issues

2G+

I have two questions/inputs regarding 2G+ from an integrator's point of view:

• Currently, no 2G+ test mode is provided by the backend api. Will this change in the future?

• If 2G+ certificate checks have to be implemented as they are currently presented in the official app (check of 1 or 2 certificates, with specific rules within the app), it will become much more complicated for existing integrations. Is this the final state of how it is going to work or will a simpler solution follow? I was hoping that vaccinated/recovered people who get tested would receive a specific 2G+ certficate so there will always be just one certificate to check.

Covid Certificate

Cocopod support or framework file

Hi, We just need to write some plugin in react native and cordova but use swift package manager is very hard to us. Can you support Framework file to import? Very thank if you can support it soon

Problem with expired certificates

We have successfully implemented the SDK in our app, and checking certificates works, but not in the case of expired certificates. They always show valid. This problem is only in iOS. We don't have a problem with the Android SDK.

Here is how we test:`

let result: Result<VerifierCertificateHolder, CovidCertError> = CovidCertificateSDK.Verifier.decode(encodedData: data);

switch result {
case .success(let certHolder):
        CovidCertificateSDK.Verifier.check(holder: certHolder, forceUpdate: false) {result in

        ... here, we check nationalRules, signature and revocationStatus and they are all valid

The "Covid check" app shows following:

How do we check if the certificate is expired?

Network parse error if fail to initialize SDK on launch

If on first app launch the SDK fails to initialize due to either no network or bad network the checking process then also fails even if the network is back. (Network parse error code 8)
Relaunching the app with correct network conditions works most of the time. However under some cricumstances, even when relaunching the app the check doesn't work and fails with a network parse error.

Steps to reproduce (sadly I couldn't reproduce the issue every time):

• turn on airplane mode
• didFinishLaunchingWithOptions -> init SDK
• try checking qr -> network error (as expected)
• force quit app
• turn off airplane mode
• didFinishLaunchingWithOptions -> init SDK
• try checking qr -> network error (not expected)

Maybe there is something that can be improved regarding the init of the SDK with bad / no network.

Add option to paste code / upload .pdf instead of scanning QR code with camera

Remove the need for a second device or paper printout to be able to add the certificate to the app.

Network Error

Hello , Can i know how to produce "No internet connection error" ? as , when i scanned every-time without internet. it verifies the certificate Valid or not. So, may i know when we get No internet connection error ?