Travel Draw

Table of Contents

click to expand


Introduction

This page describes the authentication workflow used by the Myshop Travel Draw demo.

General Authentication

In general, the following authentication mechanism is used:

general authentication workflow

A user (the client) requests authentication information from a service provider (the server) to authenticate with. The service provider creates and signs the requested data and makes it available to the user. The user then verifies the authenticity of this data by checking the signature and the service provider-related identity data stored on the Blockchain.

If the user accepts the authentication request information, the user creates and signs an authentication request that contains the request data as payload and sends it back to the service provider. The service provider in turn verifies the authenticity of the received information by checking the signature and the entity related Blockchain data.

The difference here is the way in which the user provides identity-related data. In contrast to the service provider, who has stored his identity data publicly accessible on the Blockchain, the user only reveals the necessary (requested) data by creating a verifiable claim.

Data Schema

The following data schema for exchanging authentication related data is used.

Since multiple peer verification mechanisms are thinkable, two types of authentication requests are specified to meet the requirements of the travel draw demo.

Static Request

interface StaticRequest {
    type: string;               // authentication type
    title: string;              // title shown to user
    authItemNames?: string[];   // authentication item names (see itemNames)
    reqItemNames?: string[];    // request item names (see itemNames)
    urls?: {label: string, url: string}[];  // additional urls shown to the user
    api: string;                // endpoint where to request authentication
}

The StaticRequest type is the response to an authentication request information request. It should tell the user which data a service provider expects and how the user can transfer this data to the provider. It also provides the user with additional information about the service to which he or she wants to authenticate.

Static Response

interface StaticResponse {
    type: string;               // authentication type
    authItems?: ClaimObject;    // user claim
    reqItems?: {name: string, vale: string}[];   // request items
}

The StaticResponse type describes the payload of the user authentication request. It provides the service provider with verifiable data created with the claim module and additional, non-verifiable, requested data.

Data Items

To standardize requestable information, so-called data items are used, which consist of a name and a value property.

type Item {
    name: ItemNames;        // requestable information type
    value: string;          // information value
}

The name property shows the type of information being requested and must be one of the following elements:

enum ItemNames {
    ADDRESS_CITY                = "address:city",
    ADDRESS_COUNTRY             = "address:country",
    ADDRESS_NUMBER              = "address:number",
    ADDRESS_STREET              = "address:street",
    ADDRESS_ZIP                 = "address:zip",
    COMPANY_LEGAL_FORM          = "company:legalForm",
    COMPANY_MANAGING_DIRECTOR   = "company:manDir",
    COMPANY_NAME                = "company:name",
    COMMERCIAL_REGISTER_NAME    = "comReg:name",
    COMMERCIAL_REGISTER_NUMBER  = "comReg:number",
    CONTACT_EMAIL               = "contact:email",
    ENTITY_NAME                 = "entity:name",
    LEGAL_TERMS_AND_CONDITIONS  = "legal:tac",
    PERSON_FIRST_NAME           = "person:firstName",
    PERSON_SURNAME              = "person:surName",
    PERSON_BIRTHDAY             = "person:birthDay",
    TAX_VATID                   = "tax:vatId"
}

Blockchain Payload Parsing

There are three different ways in which data elements are stored on the Blockchain.

Direct

Data items can be stored directly in the payload field of the authentication protocol. In this case, the data items are stored within a JSON object in the following way:

payload = {
    data: [
        {
            name: <data name>,
            value: <data value>
        },
        ...
    ]
}

You can find an example here.

Claim Root Hash

In case data items within a verifiable claim need to be verified, the root hash of the claim can be found in the payload field of the attestation protocol:

payload = {
    rootHash: <claim root hash>
}

You can find an example here.

Referenced Transaction

To bypass the 120 character limitation of an attestation protocol payload field, a transaction hash is stored in this field that points to a data cloud transaction.

payload = {
    txHash: <transaction full hash>
}

You can find an example here.

the referenced transaction then stores the data items in a JSON object:

object = {
    data: [
        {
            name: <data name>,
            value: <data value>
        },
        ...
    ]
}

You can find an example here.

Travel Draw Participants

The travel draw demo uses the following participants to create two authentication paths for entity verification:

travel draw attestation paths

It uses different attestation contexts for each attestation a paths.

  • server authentication (service provider)
    • serverAuthentication
  • client authentication (user)
    • claimAuthentication

Root (ARDOR-47NS-P7AU-HZNN-84PW6)

The root account acts as the trust anchor for both attestation paths.
It has the following data items stored on Blockchain:

  • entity:name -> Blobaa Root
  • contact:email -> hi.blobaa@gmail.com

Server CA (ARDOR-AEZV-YQDZ-8X2L-7V6G6)

The server CA guarantees the authenticity of the service provider.
It has the following data items stored on Blockchain:

  • entity:name -> Blobaa Server CA

Server (ARDOR-G42Z-9WLH-Z6JW-3M4VK)

The server entity represents the MyShop Server and has the following data items stored on Blockchain:

CAUTION: It's just a fictive company.

  • address:city -> Cologne
  • address:country -> Germany
  • address:number -> 11
  • address:street -> Ostermann Straße
  • address:zip -> 42411
  • company:legalForm -> GmbH
  • company:manDir -> Willhelm Ostermann
  • company:name -> MyShop GmbH
  • comReg:name -> Amtsgericht Köln
  • comReg:number -> HRB 14711
  • contact:email -> info@myshop.de
  • tax:vatId -> DE242114211

Client CA (ARDOR-3ZKF-US3F-KGL7-GUEZE)

The client CA guarantees the authenticity of the user.
It has the following data items stored on Blockchain:

CAUTION: It's just a fictive company.

  • address:city -> Berlin
  • address:country -> Germany
  • address:number -> 42
  • address:street -> Kennedich Allee
  • address:zip -> 24242
  • company:legalForm -> GmbH
  • company:manDir -> Mohammed Müller
  • company:name -> KayWhySee GmbH
  • comReg:name -> Amtsgericht Charlottenburg
  • comReg:number -> HRB 42424
  • contact:email -> hi@kyc.de
  • tax:vatId -> DE114211421

Client (ARDOR-LM9A-MD56-AYVM-G7DX4)

The client entity represents the user. It has no data items stored on Blockchain. It has previously received a claim from its authority with the following data items:

CAUTION: It's just a fictive person.

  • address:city -> Berlin
  • address:country -> Germany
  • address:number -> 3
  • address:street -> Berliner Weg
  • address:zip -> 24211
  • person:firstName -> Max
  • person:surName -> Mustermann
  • person:birthDay -> 11.11.1987

Travel Draw Workflow

Authentication

The authentication mechanism used by the travel draw demo differs slightly from the general authentication workflow. Since the draw announcement is static and therefore the signature time of the announcement is not validated on user side (represented as Blobaa App), the announcement data has been created beforehand and made available to the MyShop frontend. As an advantage, the travel draw information (the static request described above) can now be provided statically within a QR Code printed on a poster.

The user scans the code, verifies the request and checks the identity of MyShops. After a successful verification the static response will be created and sent to the MyShop backend.

The backend then verifies the authenticity of the user data and response with a submission status.

travel draw authentication workflow

Static Request Data

The following request data is used for authentication.

StaticRequest = {
    type: "request:static",
    desc: "MyShop Travel Draw",
    authItemNames: [
        "address:city",
        "address:country",
        "address:number",
        "address:street",
        "address:zip",
        "person:firstName",
        "person:surName",
        "person:birthDay"
    ],
    urls: [
        { label: "Draw", url: "https://www.blobaa.dev/demo/myshop/draw" },
        { label: "Terms and Conditions", url: "https://www.blobaa.dev/demo/myshop/draw/tac" }
    ],
    reqItemNames: [
        "legal:tac",
        "contact:email"
    ],
    api: "https://api.blobaa.dev/v1/myshop/draw/authResponse"
}

StaticResponse = {
    type: "request:static",
    authItems: ClaimObject      // user claim
    reqItems: [
        { name: "legal:tac", vale: "true"},
        { name: "contact:email", vale: "max.mustermann@gmail.com"},
    ]
}

© 2020 Attila Aldemir. All rights reserved.

hosted with