...

He will enter the desired name of his owner pico which will also serve as his owner id, and then select an authentication method and, if applicable, an initial password.

Since John has chosen "code words" as his authentication method, he will be presented with this information, which he must save for future logins. He can right-click on the QR code image and select "Save Image As..." and put it in a safe place, perhaps even printing it. Or he may bookmark the link in his browser.

Image Added

Once having saved the URL which will provide code words, he will click the "Got it" link to complete the creation of his owner pico. Later on, when he logs in, he will visit this URL (perhaps by sanning the QR code) to receive the current code words.Image Removed

Changing a password

...

The reference account management ruleset takes advantage of this event to initialize its entity variable, and your ruleset may do the same. The ruleset must install an account ruleset into the same pico (the Root Pico functions as an Owner Pico), and may send it an event, such as the owner:admin event used in the reference rulesets, to initialize it. If this is done, it should secure the event by including a one-time value, such as the transaction ID used as done by the reference rulesets. Finally, the account management ruleset must record the information it will need later to respond to the owner:eci_requested event. Your rulesets should use a new ECI for the purpose of linking the Root Pico to owner picos.

...

This event serves two purposes. First, the UI sends it, with no attributes, to determine that there is an account management ruleset (if not, then the login feature is disabled, and everyone has access to all picos). The rule in this case must return a directive with at least a name. The directive itself is used by the UI to set options, and its presence signals that you do require owner login, and promises that your rulesets meet the other requirements described here. The available options are: immediateLogin which you may set to true if you prefer that the owner of a newly created owner pico be logged in after creation (otherwise the new owner will be required to log in at that point), and rid which you may set to the ruleset identifier of your account managment ruleset, which . The rid option is not currently used, but may be used by the UI in the future.

...

The second, and primary purpose of this event is that the UI causes the engine to send it to the Root Pico whenever someone presses the "Login" button from the Login form. This event will have a single attribute, owner_id, which is what the person entered into the Login form. Your ruleset must return a directive, whose name is ignored but should be the same whether the owner_id is known or not. If the owner_id is known, the directive options must include pico_id, eci, nonce, and method. They The directive options may include owner_id. If successful, your ruleset must send the event owner:eci_provided to the owner pico, which must include as attributes the nonce, and may include other items.

These two rules from the reference account management ruleset illustrate these requirements. Notice that these rules need to appear before the option-providing rule, and that they include the last statement in their fired clauses, so that only one of these three rules will fire when the owner:eci_requested event is recieved. These rules use an entity variable, ent:owners, to keep track of the owner picos. Your ruleset may also use this entity variable, but must somehow keep track of the owner picos, and may record other information, such as the last login attempt information, as stored here in the entity variable, ent:lastOne.

...

This event is sent by the engine, at the request of the UI, when a new owner clicks the "Submit" button on the account creation form. It includes the attributes owner_id (labelled "Pico name") and method. If the method is "password", then it also includes an attribute for the owner-supplied password.

Your account management ruleset must record this information in an entity variable. It must check for uniqueness of the owner_id. Your ruleset must create an a new owner pico as a direct child of the Root Pico. Upon successful creation, your ruleset must send a directive whose name may be "new owner pico" (but must not be "new owner pico code query channel") with options which must include pico_id and eci, and may include other values. Finally, if the owner selected the method "code words", your ruleset must send a directive whose name must be "new owner pico code query channel" with options which must include eci and may include other values. The eci provided should be one specially created for the purpose of providing the current code words to the user, as described below in the section entitled "Function code".

The account management reference ruleset fulfills these requirements as follows.

...

Event owner:admin

This event is may be sent by your account management ruleset during as part its initialization. It establishes the an initial password for the Root Pico, which you should manually change to secure your pico engine. The reference ruleset does this with a single rule.

...

This event is sent by your account management ruleset after it has created the new owner pico and installed in it your account ruleset in it. It must record the owner's initial password (if that is the authentication method chosen by the owner), and may do other things. The reference ruleset does this with one rule.

...

The event is sent by your account management ruleset after it has provided the UI with the ECI to be used to contact the (as yet unauthenticated) owner pico. Your ruleset must establish the current code words, if this owner uses that method. It must record should record the nonce used to securely connect the authentication form to the next ruleset. The reference ruleset does this with one rule.

...

This event is sent by the UI when the owner pushes the "Login" button on the password entry form, and has as attributes the nonce and the owner-supplied password. Your account ruleset should verify that the nonce attribute matches the saved value recorded when it reacted to the owner:eci_provided event. Your ruleset must send a directive, with a name of your choice, whose options must include pico_id and eci and may include other values. If the password or nonce are incorrect, your ruleset must not send a directive. The reference ruleset does this with one rule.

...

This event is sent by the UI when the owner pushes the "Login" button on the code words entry form, and has as attributes the nonce and the owner-supplied code words (code). Your account ruleset should verify that the nonce attribute matches the saved value recorded when it reacted to the owner:eci_provided event. Your If the code words are correct, your ruleset must send a directive, with a name of your choice, whose options must include pico_id and eci and may include other values. If the code words or nonce are incorrect, your ruleset must not send a directive. The reference ruleset does this with one rule.

...

This event is sent by the UI when the owner pushes the "New Password" button on the Change Password entry form in the owner pico's "About" tab, and has as attributes the password and the owner-supplied new_password. Your account ruleset should verify the current password. Your ruleset must record the new password. The reference ruleset does this with one rule.

...

    code = function() {
      ent:code || "code words expired"
    }

Technical notes

Still to be done: as soon as a suitable one-way hash is available in the engine, this must be used so that we never store the password as plain text, but always encrypted with a one-way hash.

Besides the reference rulesets shown on this page, there are official rulesets, named io.picolabs.account_management and io.picolabs.owner_authentication, located in GitHub. Because of their location, they will already be registered in your node pico engine. You may choose to use these rulesets instead of creating your own. You may find it instructive to compare them with the reference rulesets, which they will eventually replace.

Throughout this documentation page, we have used "must, must not, may, and should" in the same sense in which they are used in IETF documents, as explained in RFC2119.