globalid-attestation-sdk v1.0.7

Attestation SDK for Node.js

The attestation SDK used to generate cryptography material and verify attestations from globaliD

How to use this SDK

Installation

This library is hosted on npm and can be installed with:

npm install globalid-attestation-sdk

Importing & configuration

In order to add the library to your node projects you can import it with:

import * as attestationSDK from 'globalid-attestation-sdk'

Generate a root hash

The key values to create data hash is the password and combined values of the attestation type and agencies UUID.

The password is created by the user when he creates an attestation request. The password is then used as a key when hashing the combined values of the attestation type and agencies UUID.

The result of this hashing is called root hash and it is then used on the attestation service as key for hashing attestation request uuid.

Example usage:

const attestationType: string = 'first-name'
const attestationAgencyUUID: string = 'globalid'
const password: string = 'password'

const rootHash = await attestationSDK.generateRootHash(
  attestationType,
  attestationAgencyUUID,
  password)

Generate a salt

Data hash on the attestations is used to validate that a specific personal information value is connected to this attestations and verified.

It is created from personal information value and salt. Salt that was created with the user's random password and the user is the only one who has access to this password. So the user has full control of his personal information.

Example usage:

const trackingUUID: string = 'd455e792-6af5-4093-9905-b069f9cd7253'
const rootHash: string = getRootHash()

const salt: string = await attestationSDK.generateSalt(trackingUUID, rootHash)

Generate and validate data hash

Data hash on the attestations is used to validate that a specific personal information value is connected to this attestations and verified.

It is created from personal information value and salt. Salt that was created with the user's random password and the user is the only one who has access to this password. So the user has full control of his personal information.

The key values to create data hash is the password and combined values of the attestation type and agencies UUID. The password is created by the user when he creates an attestation request.

Example usage:

const piiValue: string = 'john@doe.com'
const salt: string = await getSalt()
const dataHash: string = await attestationSDK.generateDataHash()

Validate signature

In order to validate any given attestation there are two signatures required - attestee_signature and attestor_signature. They represent that both sides that agree that the attested value is valid and correct.

They are simple to check, the public signing key of both sides (attestee, attestor) and the steps how to validate it.

To validate or check the signature, you need to go through the same steps attestor or attestee did to create the hash out of attestation values. When you have the hash, use the public signing key to validate the hash against the signature that is saved on the attestation.

const valid: boolean = await attestationSDK.validateSignature({
  attestationData,
  signature,
  signedAt,
  publicKey,
})

Types

Following types are available to import from the SDK:

AttestationSDK

interface AttestationSDK {
  generateRootHash (
    attestationType: string,
    attestationAgencyUuid: string,
    password: string
  ): Promise<string>;

  generateSalt (
    trackingUuid: string,
    rootHash: string,
  ): Promise<string>;

  generateDataHash (
    piiValue: string,
    salt: string,
  ): Promise<string>;

  validateSignature (
    validateSignatureParams: ValidateSignatureParams,
  ): Promise<boolean>;
}

AttestationData

type AttestationData {
  uuid: string
  tracking_id: string
  type: string
  attestee: string
  attestor: string
  related_attestations: string
  data_hash: string
  attestee_signature?: string
  attestee_signed_at?: string
  attestor_signed_at: string
  attestor_signature: string
  attestor_signature_private_only?: string
  salt_idx: number
  sig_version?: number
  public_data?: string
  public_attestor_note?: string
  attestee_uuid: string
}

ValidateSignatureParams

type ValidateSignatureParams {
  attestationData: AttestationData,
  signature: string,
  signedAt: string,
  publicKey: string,
}