iotsc URI scheme

The iotsc URI schema defines a link to a smart contract, as defined by the IEEE XMPP Interfaces for IoT Harmonization working group. Smart Contracts are both human-readable and machine-readable, and can be used to automate processes across domain barriers, in a legally binding manner.

Creating a Smart Contract

The process of creating a legally binding smart contract follows the following steps (in a simplified overview):

1. First a Smart Contract Templates is proposed by someone, to a Trust Provider. If TAG technologies are used, the Trust Provider would host a TAG Neuron®, that receives the proposal. The template must include:
   • Duration and Archiving times.
   • Visibility settings.
   • Roles of parts.
   • Number of parts required, and allowed for each role.
   • If signatures can be revoked.
   • Parameters and validation rules.
   • Machine-readable content, that can be validated.
   • Localized human-readable texts and descriptions.
2. The operator of the Trust Provider reviews the template proposal, and approves it, if it is consistent and follows the rules and regulations the Trust Provider has defined. If not, the Trust Provider can also reject it, or ignore it.
3. Once a template has been approved, a client with access to the template can request to create a Smart Contract based on the template. This process can be fully automated, as the integrity of the template has been corroborated by the Trust Provider. When a Smart Contract is created from a template, only role assignments and parameter values can be set, and in accordance with definitions in the template. Human-readable sections, role definitions, validation rules, life-cycle parameters, etc., cannot be modified at this stage.
4. The client can then send proposals to sign the contract to different parties, for different roles. When the Smart Contract has received the necessary digital signatures, it becomes immutable (for the duration of the contract) and legally binding.

Both Smart Contract Templates and Smart Contracts receive an ID on the Trust provider of the following format: CONTRACT_ID@DOMAIN, for example: 2c3a9ca6-d8b4-812b-b42a-302f940120fc@legal.lab.tagroot.io.

You can use the LegalLab project to design and create Smart Contract Templates.

Use Cases for the iotsc URI scheme

The iotsc URI scheme can be used to:

• Provide a link to a Smart Contract Template.
• Invite someone to create a Smart Contract, based on a template, with prefilled parameter values the user can fill in.
• Provide a sharable link to a signed Smart Contract, for reference or for other purposes.
• Propose to a user to sign a Smart Contract, as a given Role.

Syntax

In its simples form, the iotsc URI scheme simply links to a Smart Contract or Smart Contract Template. In that case, the syntax is simply iotsc:CONTRACT_ID, as in the following example:

iotsc:2a746d98-27a9-951f-8816-5dce5960eb0d@legal.lab.tagroot.io

As a QR code, this would be encoded as:

You can add query parameters to the URI, using the same syntax as for HTTP-based URIs (including URI-encoding query parameter values), to suggest parameter values, roles and visibility for a new smart contract, or if you’re referring to a contract template.

Visibility

By adding a Visibility query-parameter to the URI, you can set a proposed visbility of a new smart contract based on a template. The following possible values can be used:

Visbility	Meaning
CreatorAndParts	The most restrictive visibility. Only the creator of the smart contract, and any parts signing the contract, can view the contract.
DomainAndParts	Anyone with a Legal ID on the same domain as the one hosting the contract, can view the contract. Any parts signing the contract, even if from other domains, can also view the contract.
Public	The contract is considered public, and can be viewed by anyone that has access to the contract ID. The contract is not searchable however.
PublicSearchable	The most visible option. Not only is the contract viewable by anyone, it is also indexed and can be searched for using a search engine for smart contracts.

Role

You can propose a Role when sending a contract proposal to someone, or publish the link, without having to know the Legal ID that will be used when signing the contract. You do this by appending the Role query parameter to the URI. The value of the Role parameter should be equal to the ID of the role in the smart contract that should be suggested or pre-selected to the user following the link.

Selecting Parts

If you already know who should sign the contract, and what roles they should have, you can specify the role ID as query parameter, with the Legal ID of the part you wish should sign under that role, as value.

Pre-filled values

You can pre-fill parameter entries, by appending query parameters with the corresponding parameter names and values to the URI. The syntax of the parameter value would depend on the data type of the parameter, but follows canonical string representations for the corresponding types.

Example

Following is a more complete example of a iotsc URI, that includes a reference to a contract, suggested visibility, role for the recipient, predefined part selection for automation, as well as some parameter values for parameters of different types. White-space has been added to the example, for readability. A real URI would be a one-line string without white-space.

iotsc:2a746d98-27a9-951f-8816-5dce5960eb0d@legal.lab.tagroot.io?
	Visibility=Public&
	Role=Creator&
	TrustProvider=27c79713-73c1-0f63-b409-429bb8ff83a2@legal.tagroot.io&
	ClientId=a04533fc-13f0-4ca5-8b76-ed1bc625715d&
	Title=Test&
	Description=Lorem%20Ipsum&
	Value=340&
	Currency=EUR&
	CommissionPercent=10&
	Expires=2022-09-01

The QR-code for this example would be:

#uri, #scheme, #iotsc

tagsign URI scheme

The tagsign URI scheme can be used to communicate a request to sign information. The simplest use case, is to gain access to a resource, or to quickly login to a resource on the Internet or on the World Wide Web. It is used by the Quick Login API, encoded into QR codes that clients can scan, initiate the signature process, and then sign binary information to gain access (login) to a resource.

Example

Following is an example of an obinfo URI:

tagsign:lab.tagroot.io,UaOKqiirTphtO6qDjVgPLp3LWixR1Gti8SM94naEw_0

As a QR code, it would look like:

Sections

The tagsign URI has three sections, The first two delimited by a colon (:), and the last two by a comma (,):

1. URI Scheme tagsign.
2. JID of remote party requesting you to sign something (can be a domain name, if it’s a server, or a Bare JID, if it’s a client, connected to an XMPP broker).
3. A base64-encoded Key, necessary to initiate the signature process.

Signature flow (XMPP)

To perform the client signature, indicated by the URI, the following steps need to be taken:

1. The client sends an IQ set XMPP stanza to the JID indicated in the URI, with the following XML:

   <ql xmlns='https://tagroot.io/schema/Signature'
       key='XML-ENCODED KEY FROM URI'
       legalId='ID OF APPROVED CLIENT LEGAL IDENTITY'/>
   

   The approved legal identity referenced in the XML above, is the identity the client will use to perform the signature.

2. The remote entity will now send a signature request over XMPP to the client, requesting the client sign some binary data. This request will come in the form of an XMPP message, with the following XML content:

   <petitionSignatureMsg xmlns='urn:ieee:iot:leg:id:1.0'
                         id='LEGAL ID'
                         pid='PETITION ID'
                         from='JID OF ENTITY REQUESTING THE SIGNATURE'
                         purpose='PURPOSE TO PRESENT TO USER FOR WHY SIGNATURE REQUEST IS MADE'
                         clientEp='ENDPOINT OF REQUESTOR'>
   	<content>BASE64-ENCODED CONTENT TO BE SIGNED</content>
   </petitionSignatureMsg>
   

3. The client signs the binary content data in the request (Base64-decoded first), and returns the signature to the remote entity, in the form of an IQ set XMPP stanza, to the Trust Provider (broker/server) hosting the Legal ID performing the signature. The broker will forward the signature to the requestor. The XMPP stanza must contain the following XML:

   <petitionSignatureResponse xmlns='urn:ieee:iot:leg:id:1.0'
                              id='LEGAL ID'
                              pid='PETITION ID'
                              jid='JID OF REQUESTOR'
                              response='BOOLEAN RESPONSE; true=accept to sign, false=decline to sign'>
   	<content>BASE64-ENCODED CONTENT BEING SIGNED</content>
   	<signature>BASE64-ENCODED SIGNATURE</signature>
   </petitionSignatureResponse>
   

   Note: If declining to sign, there are two options: Either the client can ignore the request, and not return a signature. Or the client can return a response, with the response attribute set to false, and the signature element empty, to let the requestor know the signature request has been declined.

4. If signature is valid, and matches the public keys of the legal identity used in the signature, and the identity is authorized to access the resource, access to the resource will be granted.

Signature flow (Agent API)

If using the Agent API to perform a signature or quick-login procedure, the sequence would be transformed into the following API calls:

1. To initiate the procedure, send the <ql> element in an IQ set stanza to the requestor, using the /Xmpp/InformationQuery resource.

2. To receive the asynchronous message containing the signature challenge (petitionSignatureMsg), call the /Xmpp/PopMessages resource. The response will contain messages for the client, the client has not yet processed. You can call this resource immediately after a successful IQ set operation, and thereafter, at most once a second, until the message is received. If the message is not received within ten seconds, the operation can be considered failed, and should be re-attempted.

3. The actual signature is created by calling the /Legal/SignData resource.

4. The signature is embedded into a signature response that is sent in an IQ set stanza containing an <petitionSignatureResponse> element, using the /Xmpp/InformationQuery resource.

Life-time of information

The life-time of the key in the QR code is typically counted in minutes, or fractions of minutes, depending on use-case.

#uri, #scheme, #tagsign, #api

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:

1. 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.
2. 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).
3. 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 (:):

1. URI Scheme obinfo.
2. Domain of server hosting the onboarding information.
3. A base64-encoded Code, necessary to access the onboarding information.
4. A base64-encoded Key, necessary to decrypt the onboarding information.
5. 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:

1. Create a resource URL, concatenating https:// with the domain in the obinfo URI, and the resource /Onboarding/GetInfo.

2. 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.

3. An encrypted BLOB will be returned, base64-encoded. Start by decode it into an octet-stream (binary byte array).

4. Decrypt the BLOB using AES-256, Cipher Block Chaining (CBC) and PKCS7 zero padding, using the Key and IV from the obinfo URI.

5. 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