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