Creating a wallet using Agent API

The Agent API is a REST API that allows external services to act as agents in TAG Neuron® networks, and manage legal identities, wallets, smart contracts, Neuro-Feature tokens, etc., for their users. This article describes how this API can be used to allow such external services to create wallets. The flow is as follows:

• First you select a Neuron®
• Once a Neuron® is selected, you create an account on the Neuron®.
• You then create at least one cryptographic key, that you will use for signatures.
• You apply for a legal identity on the account, using the cryptographic key and meta-data about the person (natural or legal) that will receive the wallet.
• Once the application has been reviewed and approved, the wallet is automatically created and can be used.

Selecting Neuron

The Neuron® network is a federated network where independent Neurons operating on their own domains interoperate to create a globally scalable network. The first step is selecting which Neuron® to connect to. You have different options:

• You can use a predefined Neuron®. In this case, you would typically receive the domain name of the Neuron® directly from the operator. You might also receive an API key and secret (see below) associated with that Neuron®.

• You can use the TAG onboading process to select a Neuron®, depending on the client’s location and purpose for connecting. The process is documented in a separate repository (see previous link). The onboarding process validates the end-user’s e-mail address and phone number, and returns the domain name, and associated API key and secret, for creating an account on that Neuron®.

• You can use a custom onboarding process, where a provider has customized access to their own set of featured Neurons. Apart from the domain name used to initiate the onboarding process, the process is otherwise similar to the TAG onboarding process.

• You can scan an onboarding QR code, to receive the relevant onboarding information. Three variants of onboarding codes exist: One that allows you to create an account on a Neuron®, one that already contains access to an existing account, and one that corresponds to a transfer of an account, including legal identity and wallet. (See link for more information.)

Note: You can call the DomainInfo resource of the Agent API, to get localized information about the selected domain.

Note 2: Your operator might already have given you an account for use with the Agent API. In that case, proceed with Sessions and Login, below.

Creating Account

Once a Neuron® has been selected, you have two options for creating an account on the Neuron®:

• You can use the Create API resource to create an account. This method requires, apart from the domain name, username, password and associated e-mail address, also a corresponding API Key and secret. A nonce value is also required, to assure all signatures are unique. Make sure the nonce value is unique for every call.

  If you create an account using this resource, you will automatically get a session token (which is a JWT token that is used as a Bearer token in subsequent calls to Agent API).

• Optionally, the operator of the Neuron® can also choose to enable the CreateWebForm resource, that allows you to embed the account creation properties in a web form displayed to the user. This resource does not require an API Key and secret for the integration. Instead, the operators configures the Neuron® with an API key and secret for use with this resource, on the Neuron® itself. Instead, access to the resource is protected using reCAPTCHA.

  When creating an account using this resource, you do not get a session token automatically. Instead, you have to call the GetSessionToken afterwards, to get a session token for the newly created account.

Verifying e-Mail address

If the the Create or CreateWebForm resources return a successful result, an account is created, albeit in a suspended or disabled state. This protects the account name from being taken by other users for a while, but the account cannot yet be used, i.e you cannot login to the account. To enable the account, you need to verify the e-mail address provided in the account creation call. Part of the creation call is to send out a verification e-mail to the address provided. This e-mail contains a code. You verify the e-mail address by calling the VerifyEMail resource with the code provided in the e-mail.

Note: Calling the Create and verify e-mails too many times without successfully verifying the e-mail addresses provided will result in a temporary block at first, and a permanent block if errors persist.

Sessions and Login

Immediately after creating an account, you are given a session token that helps you maintain a session with the Agent API. You select the duration of this session token in the original call, but it cannot exceed 3600 s (i.e. 1 h). Before the token expires, you need to call the Refresh resource if you want to maintain the session, to get a new token for the session. If you use an API implementation, such token maintanence is probably implemented “under the hood”, meaning you do not have to worry about this refresh. If you implement the API yourself, you will have to make sure token refreshing is implemented as well. If you know you will no longer need the session, you can call the Logout resource, to obsolete the current token.

If you want to login again, and create a new session, you have two options:

• You can use the Login resource, that allows you to login if you have the credentials, using a relatively high level of security, even if underlying HTTP libraries lack strong authentication algorithms. (This option is the recommended resource to use.)

• There is also a WwwLogin resource available, for authentication using the WWW-Authenticate header. This resource requires Neuron® and clients agree on choice of (and support for) cryptographic algorithms to use for authentication. (This option should only be used if requirements dictate use of the WWW-Authenticate header.)

Cryptographic Keys

The Neuron® uses public key cryptography to create auditable digital signatures. Such signatures are used both in eDaler® transactions in the wallet, but also on digital signatures on smart contracts, which form the basis of operation of Neuro-Feature™ tokens. Since such algorithms evolve and change over time, the Agent API helps clients manage and use such keys by providing the following resources. The clients therefore, do not need to implement each algorithm by itself, and can rely on the Agent API to manage the specifics of each algorithm.

• The GetAlgorithms returns an array of cryptographic algorithms the Neuron® supports, together with security-related information about each algorithm, such as security strength, and if the algorithm is safe or not.

• You create keys using the CreateKey method. You can freely create keys. You associate a Key ID with a private key. The Agent API implementation encrypts the information using a salted hash digest, initiated using a key password. This key password is not transmitted itself and therefore not stored on the Neuron®. This permits the Agent API to perform signatures on the clients behalf, but only when the client signs the corresponding request accordingly. Information for generating the signature is not persisted, and the Neuron® cannot therefore generate such signatures on its own. This is also why the API requires all calls including a cryptographic key the client provide the key password in the call.

Note: It is the responsibility of the client that calls the API to securely store the key password. Do not store the password in a way that permits other users to easily extract it. Use secure key storage when available.

• To be able to validate server signatures, you need to get server public keys. You do this calling the GetPublicKey resource.

Applying for a Legal Identity

Once you have a cryptographic key with which you can create digital signatures, you can apply for a legal identity. A legal identity is a collection of information (or meta-data) that can be used to identify a person (natural or legal), associated with the account. This association is cryptographically secured, and its integrity validated and protected, by means of the following process:

• The user initiates an application for an identity, using the ApplyId resource. This call associates a cryptographyic key with the collection of personally identifying meta-data to include in the identity.

  • To validate personal numbers, you can use the ValidatePNr resource.

  • To learn what identity properties are required for the application to be accepted, you can call the GetApplicationAttributes resource.

• If the Neuron® requires photos to be associated with the legal identity, you append the application with such photos as attachments using the AddIdAttachment resource.

• Once the application is complete, you call the ReadyForApproval resource, to flag the application as ready for approval. There are different types of approval processes available, depending on the configuration of the Neuron®:

  • The operator can approve (or reject) the application manually.

  • The Neuron® can use an integrated service for KyC (Know your Customer) that processes the application automatically, to determine if the application should be approved or rejected.

  • You can request a peer to review your application, if the Neuron® accepts use of peer review. You might need muliple peers approving the application, for the application to be approved. (For more details, see below.)

• Changes to the application will always be sent to the client asynchronously, as they occur. While the underlying communication framework uses XMPP (which is bi-directional and full-duplex) and push notification (using Firebase), Agent API is strictly a Request/Response-API based on HTTP (which is only half-duplex). This means you must poll the application to detect changes to it. There are two ways to do this using Agent API:

  • By calling the PopMessages resource, you can receive asynchronous messages that has been sent to the account since last call. This will include updates to any legal identity application object you have. It will also include other types of messages, for other types of objects, such as those related to tokens, wallet, etc.

    • Note: You may receive asynchronous messages from the reviewer indicating reasons for rejecting an application.

  • You can also call the GetIdentity resource directly, to get the information about a given identity object, given its identifier (which you get when you send in the application in the first place).

• Monitor the state of the identity object to determine next steps. Possible values are: Created, Rejected, Approved, Obsoleted and Compromised. Once it is Approved, you can use it to sign contracts and perform transactions. Once it is still Created, you need to continue to wait (until you choose to abandon application). If you receive Rejected, Obsoleted pr Compromised, you need to re-apply.

Requesting Review

Once an identity application is in the Created state, you can request others to review your application. You can send such applications to others, if you have their identifiers. The Neuron® may also contain a list of featured reviewers. The following resources are available for requesting peer-review:

• To gain access (optional) to identity reviewers published by the Neuron®, perform these steps:

  • Call the GetServiceProvidersForIdReview resource, to get a list of service providers and services that can perform identity application reviews. These may include human users (i.e. peers), as well as internal and external services for KyC. Each service will have an associated legal identity identifier that you will use when requesting review.

  • When selecting a service and service provider for reviewing your application, you need to select it. This is done by calling the SelectReviewService resource.

• Before sending a review request, you need to explicitly grant access to your identity application information to the reviewer, for them to be able to get access to the personal information in your application. This is done by calling the AuthorizeAccessToId. (You can revoke this permission using the same resource.)

• To send a request for review, you call the PetitionPeerReview using the legal identity identifier of the reviewer to indicate to whom to send the request. If you have also provided access to your information to that identifier, they will be able to review the application and return their decision accordingly.

Note: Information about the result of the review will be sent to you as an asynchronous message. The review will also be attached to the identity object, together with the identity of the reviewer, and visible to anyone who gets access to the identity. This allows auditors to be able to determine the validity of an identity, by permitting them to validate who have reviewed the application as well.

Once the identity object state becomes Approved, the identity is ready to be used, and the wallet is automatically created.

#agent, #api, #edaler, #recipe, #wallet, #account

On Changing Passwords for Neuron® accounts

The TAG Neuron® hosts accounts for various types of users, and there are typically different interfaces to interact with the Neuron® and published services and connected peers for different kinds of users. This includes XMPP users, Web users, Mail users, Agent API users, etc.

XMPP

The main interface with the TAG Neuron® has been XMPP. Clients connect to a Neuron® using a XMPP Client-to-server (c2s) binding mechanism (TCP socket, HTTP, Web-socket, etc.). XMPP Brokers (other Neurons) connect other Neurons using XMPP Server-to-Server (s2s) binding mechanisms. Servers identify themselvs using X.509 certificates and mutual TLS-connections (mTLS). Clients, while able to use mutual TLS also, most often use user name and password credentials to authenticate themselves with the corresponding broker. All this process is defined in the IETF standards defining the XMPP protocol and bindings. Changing passwords is included in these standards, and is therefore an intrinsic part of XMPP.

Chat

The first interface for administrating a TAG Neuron®, has been via XMPP, more specifically, via XMPP chat. This is often called Chat Admin, which works like a terminal prompt. An administrator with chat admin privileges, can use the reset password command to reset the password of a user on the Neuron®. Passwords are automatically randomized, with no option to enter a password manually, to ensure sufficient entropy is provided.

Web

The TAG Neuron® also provides a web interface for administering the Neuron®. It is available via the /Admin.md resource. Access to this resource requires login, and available options are restricted to show only authorized options.

Session User

All users however, have access to the Change Password option under Session (on Neurons from build time 2023-07-12). Clicking this option opens a page where you can change the password of the currently logged in account.

When changing the password for the currently logged in account, you must provide the existing password again (to protect the account in case somebody else tries to change the password on an open page somebody has left open by mistake), as well as the new password twice. The new password must conform to the following rules:

• They must either be a sufficiently random BASE64-encoded binary string.
  • Press the Create Random Password below to generate such passwords.
  • Note: Copy password before pressing Change Password (unless you have an exceptional memory). The user will need it to login or change the password again.
• Or enter a password that:
  • Is at least 12 characters long.
  • Contains at least 3 letters.
    • Of which at least 1 is upper-case.
    • Of which at least 1 is lower-case.
  • Contains at least 3 digits.
  • Contains at least 3 of punctuations or symbols.
  • Contains no control characters, surrogates or white-space.

Users

With a User here, is referred to a user of the TAG Neuron® directly. This can be an operator, developer, service integrator, external service, etc., that needs to be able to perform actions on the Neuron® that requires authentication and authorization. Such users can be managed by commands available under the Security header in the Admin portal of the Neuron®. An administrator would first need to create Roles, which are a collection of positive and negative privilege references. Once suitable roles are defined, users can be defined. Each user has a reference to one or more roles, which define the privileges the user has in the system. Each user can log-in to the Neuron® and change their password, according to the preceding paragraph. An operator with sufficient privileges, can also go into the Users menu (under Security), select the User and change the password manually. It is recommended this password be randomized, to avoid simple passwords that can be easily broken. Chinging the password this way, may be necessary, if the credentials are lost, forgotten or compromized.

Broker Accounts

Users that only use the Neuron® indirectly, i.e. use it as a broker to interact with other entities, use Broker Accounts. These are not considered Users of the Neuron® directly. They cannot use the credentials to login or access administrative resources on the Neuron. These Broker accounts are also managed using a separate set of commands, available under the Broker header on the Admin page, as opposed to the Security header.

Access to the Broker Accounts are typically made using XMPP. Changing the password of an account in XMPP is done in accordance with the XMPP protocol standard. Some users may access such accounts via other means, for instance, when relaying or sending/receiving e-mail messages. Such interfaces do not have an intrinsic method to change the password. If such accounts require a change of password, an operator can do so from the Admin page.

There are two types of broker accounts: Those that are created manually (i.e. an operator on the Neuron® has created the account via the Admin page), and those that have been created by the users themselves, using an API Key. While standard XMPP allows for anyone to create an account on an XMPP broker, the TAG Neuron® is restricted in this regard, and requires an API Key and Secret, to be allowed to create an account. The operator creates API Keys, and secrets, and assigns a maximum number of accounts that can be created using that API Key (this amount can be changed by the operator at a later time). Clients with access to such a key and secret can create an account accordingly. The account that is created in this way, is linked to the API Key, and operators can in this way follow the usage of keys over time. (The process of getting the API Key and Secret, when creating an account, is part of what is called the onboarding process; The key and secret is selected by an onboarding server, based on the purpose the user has, and locality information or other preferences and/or invitations.)

An operator can change the password of a broker account (or enable or disable it) via the Admin page. Manually created accounts are managed under the option Manually created accounts. Accounts created using an API Key are accessed first, by selecting the API Keys option, and then opening the corresponding API Key. On the page listing details about the API Key, there’s a field called Number of accounts created, with a link in the form of a digit. Clicking on this digit opens a page listing the accounts that have been created using that API Key. Clicking on any of the accounts in this list, will open the corresponding account, allowing the operator to change the password or enabled/disable it.

SMTP

The broker bridges the XMPP and SMTP protocols, so that an XMPP client can send e-mails to a mail client by using its e-mail address, and a mail client can send chat messages to a XMPP client, by e-mailing its JID (XMPP address). Both a Bare JID and an e-mail address have the same format: account@domain, so they can be used interchangably. If you use an account for e-mail, the principal method to change the password is still via XMPP (or let an operator do it). There is no mechanism to change the password via SMTP.

Agent API

A user of an app or service that uses the Agent API to create an account on a TAG Neuron® is basically an XMPP client, except connection with the broker is done using a REST API instead of standardized XMPP. This REST API is easier to consume and interact with, for clients and environment who are limited to using HTTP as a protocol, and Javascript or JSON as main representation format. This is often the case when developing web applications or apps based on web technologies. Even though the connection to the Neuron® is done via a Web REST API, the client still has access to the features and possibilities XMPP provides. This includes interacting with other XMPP clients seamlessly, in the federated network. It also includes the ability to perform common XMPP-tasks, such as sending Information Queries (i.e. iq stanzas) and Asynchronous Messages (i.e. message stanzas) via the Web API.

Chaning the password of the currently connected account is done, by sending an iq stanza of type set, with the following content (white-space added for readability only). The to attribute in the iq stanza, should be empty (or contain the domain name of the server), as the stanza is sent to the server itself, and not a peer.

<query xmlns='jabber:iq:register'>
	<username>USERNAME</username>
	<password>PASSWORD</password>
</query>

The response will either be OK or not. If OK, the password has been changed. If not OK, the contents of the response will contain the reason. It may also contain a Data Form that can be presented to the user, in order to collect additional information.

ID Apps

In the TAG ID App, and derivatives, there’s difference between network password and local password. The local password, or PIN, is the password the user uses to unlock the app, or access protected functions. This password is too weak to be used in a meaningful way on the Internet, and therefore is never used in any communication with the TAG Neuron®. Instead, the app generates an invisible random password, with sufficient entropy, that is used in any communication when the server. This password is stored in the encrypted local database of the app, and accessible only if the user provides the correct PIN to unlock it.

The user can change its PIN in the app. When doing so, the app automatically creates a new network password also, and changes the password of the underlying XMPP connection seamlessly.

#neuron, #admin, #account