`obinfo` URI scheme

The obinfo URI scheme can be used to communicate onboarding information to clients. Onboarding information is information required by the client before its configured. It would usually contain information about which service provider (i.e. server) to use, any keys necessary to access service, etc. Onboarding information uses the Internet for transfer of the information. For that reason, all information is encrypted, and only made available to the client that has access to the URI (which can be encoded as a QR code, or communicated by other means, such as near-field radio, etc.)

Onboarding information can come in three different types:

Partial onboarding information can be used, for instance to select a service provider (or server), but would require the client to create an account later, on that server.
Full onboarding information on the other hand will contain sufficient information for the client to become fully onboarded (i.e. it would contain information about the account to which to connect to).
Transfer onboarding information would contain all the information of a full onboarding URI, but would also contain additional private infomraiton to transfer an app from one client to another. After the transfer, the information can be removed from the first, and the app uninstalled there.

Example

Following is an example of an obinfo URI:

obinfo:id.tagroot.io:8deUo7/dmIE/KaJPf78yORVlkTb2aNRnSPhRAQxdpHw=:DhI/WaOpgeaHki4at7bRjg==:8FDstLQyV43wRNdPODEPKw==

As a QR code, it would look like:

Sections

The obinfo URI has five sections, all delimited by colons (:):

URI Scheme obinfo.
Domain of server hosting the onboarding information.
A base64-encoded Code, necessary to access the onboarding information.
A base64-encoded Key, necessary to decrypt the onboarding information.
A base64-encoded Initiation Vector (IV), necessary to decrypt the onboarding information.

All onboarding information is encrypted using AES-256, and decrypted information is only made available to those with access to the URI.

Accessing information

To access the onboarding information, follow these steps:

Create a resource URL, concatenating https:// with the domain in the obinfo URI, and the resource /Onboarding/GetInfo.
Perform an HTTP POST to the URL in (1).
- Send the base64-encoded Code from the obinfo URI, as text/plain content.
- Use Accept: text/plain header in the request.
An encrypted BLOB will be returned, base64-encoded. Start by decode it into an octet-stream (binary byte array).
Decrypt the BLOB using AES-256, Cipher Block Chaining (CBC) and PKCS7 zero padding, using the Key and IV from the obinfo URI.
In the resulting XML document, decode the information and proceed/complete the onboarding process.

For a reference for how to interpret the onbaording XML information, see the ScanQrCode() method here:
https://github.com/Trust-Anchor-Group/IdApp/blob/develop/IdApp/IdApp/Pages/Registration/ChooseAccount/ChooseAccountViewModel.cs

Life-time of information

Depending on what type of onboarding information is encoded, it will be available for different amounts of time:

For partial onboarding information, such as selection of service provider, the information will be available for longer periods of time (depending on service provider), and the information can be accessed multiple times.
For full onboarding information, such as getting access to an account, the information can only be access once, and will typically expire within a given number of days. Such a QR code can be generated by support, as a response to access requests to an existing account.
For transfer onboarding information, used to transfer information from one app to another, on another device, the information can also only be access once, by will typically expire much more rapidly, than a full URI would. Such a QR code is assumed to be created by the same person as will consume it, so life-time can be set to be much shorter.

XML document examples

The following subsections show some XML document examples of different onboarding information available. Attribute values would be replaced with actual values in the real case.

Selection of service provider

<ApiKey xmlns="http://waher.se/schema/Onboarding/v1.xsd"
        key="BASE64-ENCODED KEY"
        secret="BASE64-ENCODED SECRET"
        domain="DOMAIN NAME OF SERVICE PROVIDER" />

Information can be accessed multiple times, and has an expiry time that is configurable, by the service provider operator generating the information.

Account access

<Account xmlns="http://waher.se/schema/Onboarding/v1.xsd"
         userName="ACCOUNT USER NAME"
         password="ACCOUNT PASSWORD"
         domain="DOMAIN NAME OF SERVICE PROVIDER" />

Information can be accessed only once, and has an expiry time that is configurable, by the service provider operator generating the information.

Transfer account

<Transfer xmlns="http://waher.se/schema/Onboarding/v1.xsd">
   KEYINFO
   <Pin pin="PIN"/>
   <Account xmlns="http://waher.se/schema/Onboarding/v1.xsd"
            userName="ACCOUNT USER NAME"
            password="ACCOUNT PASSWORD"
            domain="DOMAIN NAME OF SERVICE PROVIDER"
            passwordMethod="NAME OF PASSWORD HASH METHOD" />
</Transfer>

The KEYINFO would contain the private key being transferred, and would depend on the algorithms used in signatures. Information can be accessed only once, and has an expiry time that is very short, typically one minute.

#uri, #scheme, #obinfo

obinfo URI scheme