AOK SDK

This library provides a number of utilites to interact with the AOK certificate attestation system.

File structure

src/schemas.ts

Provides core schema definitions for AOK Certificates and AOK Certificate Standards as defined in the AOK Technical Whitepaper.

It uses Typebox to generate JSON-Schema documents and Typescript definitions.

Intended use is to validate the structure of AOK Certificates, and allow for compliant implementations in other programming languages.

src/certificates.ts

Provides utilities for creating unattested and attested AOK Certificates, as well as formatting them for QR code transmission and decoding.

Intended for use in web frontends or node-js based backends, where AOK passes may be generated.

Concepts

A FullCertificate is a certificate that contains all the data specified in the whitepaper, that has not yet been attested to.

A PublicCertificate is a certificate that has all its private data hashed into a merkle tree. This is used to generate the identifying hash.

An AttestedCertificate is a FullCertificate that has been attested to, and contains the neccessary information for verification

An AttestedPublicCertificate is an AttestedCertificate that has all its private data hashed into a merkle tree, and is what is transferred via QR to verifiers. This can be re-constructed into the identifying hash.

The process for creating, attesting and verifing certificates is as follows.

FullCertificate V PublicCertificate V Certificate Hash -> Attestation Server Attestation Data <- V AttestedCertificate V AttestedPublicCertificate V QR Data -> Verifier

SHA256 is used as our hash digest, you need to select a compatible cryptographic librabry to provide this functionality depending on your target platform.

Usage

Node

This library can be used as an npm module

yarn add @aokpass/aok-sdk OR npm install --save @aokpass/aok-sdk 

The general process for creating a pass in a node based backend would be (using typescript)

import { hashFullCertificate, generateQRText, decodeQRText } from '@aokpass/aok-sdk'
import * as crypto from "crypto";

// Our digest function has to be async
// this is an implementation using the nodejs crypto library
const digest = (b): Promise<Buffer> => {
  return new Promise(r =>
    r(
      crypto
        .createHash("sha256")
        .update(b)
        .digest()
    )
  );
};

// First create a FullCertificate according to schema
const fullCertificate: FullCertificate = { 
_schema_version: "0.1",
standard: "id of certificate standard that describes type of certificate",
publicData: ["will be shared via QR"],
privateData: ["secret"],
}

// Hash the full certificate so that it can be attested to
const certificateHash: string = await hashFullCertificate(fullCertificate, digest)

// Request for attestation from an attestation server
const attestationRequestResult = await fetch(config.endpoint + "/request-attest/", {
  method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: email,
      hash: certificateHash
    })
});

// At this point, the email recipient has to verify attestation, and a ~15 second processing time occurs

// once attested, fetch the attestation data
const proofRequestResult = await fetch(config.endpoint + "/request-proof/" + certificateHash);
const { proof, store } = await proofRequestResult.json();
const attestationData: AttestationData = {
  proof: proof,
  attestationStore: store,
  rootHash: proof.rootHash,
  id: certificateHash
};

// combine for an AttestedCertificate

const attestedCertificate: AttestedCertificate = { ...attestationData, ...fullCertificate };

// present as QR code (display via QR library of your choice)
const qrString: string = generateQRText(await makeAttestedPublicCertificate(attestedCertificate, digest))

// parse QR Text into an AttestedPublicCertificate (qrString should be result of QR reader library of your choice)
const decodedCertificate: AttestedPublicCertificate = decodeQRText(qrString, digest)

// Verify certificate via AWS Cache
const verificationRequestResult = await fetch(config.endpoint + "/verify/" + decodedCertificate.id);
const { success, err } = await verificationRequestResult.json()

if (success) {
// valid certificate
} else {
// invalid certificate
}

Browser

The SDK is also available as a bundled script that can be included via a script tag

<script src="https://cdn.jsdelivr.net/npm/@aokpass/[email protected]/bundle.js"></script>

This will add an aok object to your global scope, which will contain the methods shown in the nodejs example.