Package: uniquid
UniquID User GuideThe command line interface for UniquID system administration.  The UniquID IAM
(Identity and Access Management) system leverages blockchain technology so that
your organization can efficiently control access to large pools of IoT devices.WarningThe UniquID command line interface is currently in development and undergoing
test.  Please do not use the tool in production as information may be lost.
Contact UniquID about organizing an evaluation or demonstration of this
innovative technology.WarningThe UniquID command line interface is currently untested onWindowsplatforms.  Some functions, such asdeployare not currently
supported onWindows.The package currently supports Python 3.6 and later.  Please upgrade to the
latest version of Python if you are running an older version.Table of ContentsInstallation InstructionsGetting StartedViewing DevicesContractsSharing Access to DevicesGetting HelpContact UniquIDInstallation InstructionsVerify thatPython 3is installed on your system. You should have at leastversion 3.6of Python installed.  You can query the version installed using
the command:$ python --versionIf you do not have Python installed, please follow the instructions for your
operating system:Operating SystemDownload InstructionsWindowsPython3 for WindowsMacOSPython3 for MacLinuxPython3 for UnixOncePythonis installed, you can use thepip3orpiptool to install the
latest version of the CLI client.NoteThepippackaging tool forPython3may be calledpip3on your
system, depending on your operating system.  Please check your system
instructions on how to execute thepiptool forPython 3.$ sudo pip3 install uniquidor$ sudo pip install uniquidIf correctly installed with no errors, the CLI client application can
be executed from the command line.$ uniquid --versionGetting StartedThe user can access a list of the available commands, using thehelpoption.$ uniquid --helpEach command also provides more detailed help information. For example:$ uniquid login --helpSome commands have a shorter alias available.  You can view the list of
available command aliases using the command:$ uniquid list-aliasesIn order to login to the UniquID system, the user must provide:a credentials file which was downloaded during registration athttp://uniquid.com.or:their registered organization nametheir UniquID usernamethe secretAccess Keywhich was provided to them during registrationThelogincommand will keep an authenticated session open until the user uses
thelogoutcommand to close the session or their session expires.  For security
reasons, the session may expire after a period of time and the user will be
requested to use thelogincommand again.Login using the credentials fileDuring account registration, the user is given the option to download a
credentials file to their system. This file contains information such as
their uniqueAccess Keywhich enables them to connect to the UniquID
system.  This credentials file should be stored securely on their system with
read and write privileges only granted to the user.The user should save the credentials file to the following location:Operating SystemFile PathWindows%USERPROFILE%\.uniquid\credentials.jsonMacOs~/.uniquid/credentials.jsonLinux~/.uniquid/credentials.jsonOnce the credentials file is saved to the correct location, thelogincommand
will automatically detect the user's credentials.  Tologin, the user should
use the command:$ uniquid loginIf the user prefers not to save the credentials file to the default location
as described above, they can pass the location of the credentials file as
an option on the command line.  Therefore, the command tologinis:$ uniquid login --credentials-file <credentials file path>Login without a credentials fileFor the firstlogin, the user must specify the organization, their username
and theAccess Keywhich they were assigned.$ uniquid login <organization> --user <username> --access-key 'abcd5678'The organization name must always be specified for the initial login. After the
initiallogin, the user does not need to specify the organisation unless they
want tologinfor a different organization.  They need only specify their
username and the Access key.$ uniquid login --user <username> --access-key 'abcd5678'If the user prefers not to enter their username andAccess Keyevery time they
use thelogincommand, they can use environment variables to hold the values
of the username andAccess Key.In theBashshell, the environment variables can be set using the following
commands:$ export UNIQUID_USER=<username>
    $ export UNIQUID_ACCESS_KEY=<access key>Login status and logoutAt any point, the user can query the status of the tool's connection to the
UniquID servers. In order to query their login status, the user can use the
command:$ uniquid statusWhen the user is finished interacting with the UniquID system, they should then
use thelogoutcommand to close the open session.$ uniquid logoutViewing DevicesA list of connected devices can be viewed using the command:$ uniquid list-devicesThis command, by default, outputs the device list in text format.  If you would
prefer to view the device list in JSON format:$ uniquid list-devices --output jsonThe entries in the list of devices can be sorted by the values of one of
the fields of the device information. The device list is sorted using the command:$ uniquid list-devices --sort <key name>
    $ uniquid list-devices --sort-desc <key name>Detailed information on a specific device can be retrieved, using the device's
public key XPUB as an identifier.$ uniquid show-device <device xpub>
    $ uniquid show-device --output json <device xpub>An example of a command to view detailed information about a single IoT
device:$ uniquid show-device tpubDGDkliuherf34hSGSDG57652DSFDSFDksdfkjsdf434fgDContractsAccess contracts which permit interactions between devices can be created,
viewed and revoked using the client tool.$ uniquid list-contracts
    $ uniquid list-contracts --output jsonMore detailed information on the state of a contract can also be retrieved,
using the contract's transaction identifier to identify the contract.$ uniquid show-contract <transaction id>
    $ uniquid show-contract --output json <transaction id>An example of a command to view information about a single UniquID Access
Contract:$ uniquid show-contract ebaef8fdf1645032010e801fad010338d2048fa3e67154d660545b4eb9b01c58New contracts can be specified in JSON format and created by the tool. The
JSON contract specification can either be loaded from a file or passed directly
on the command line.$ uniquid create-contracts --input-json-file <json file name>
    $ uniquid create-contracts --input-json <json contract specification>The format of the JSON file to create a new contract is:[
    {
        "provider": "xpub_of_provider_device",
        "user": "xpub_of_user_device",
        "functions": [40, 41]
    }
]The identifier used to identify the devices, between which the contract is created,
is the Public Key XPUB of the devices.  The functions field is used to identify
the IDs of the functionality which is enabled by the contract.An example of the JSON file to request the creation of two new contracts:[
    {
        "provider": "tpubDGDkliuherf34hSGSDG57652DSFDSFDksdfkjsdf434fgD",
        "user": "tpubDAquqJlksdf342GFRG8p98sdfhjhk4FDFD434rsdfDSFan",
        "functions": [40, 41]
    },
    {
        "provider": "tpubGFSDF8485FDSSDSDF345345HGDDFHkdsfk49ihkfgDEODs",
        "user": "tpubDAquqJlksdf342GFRG8p98sdfhjhk4FDFD434rsdfDVZRN",
        "functions": [39, 42]
    }
]Existing contracts can be revoked by specifying the transaction identifiers
of the contracts in one of three ways:passing transaction identifiers as arguments.passing a JSON list of identifiers on the command line.passing the path of a file containing a list of identifiers in JSON format.$ uniquid delete-contracts <transaction id> <transaction id>
    $ uniquid delete-contracts --input-json <json list of ids>
    $ uniquid delete-contracts --input-json-file <json file name>An example of the JSON file used to define the transaction IDs of several
contracts which should be deleted.[
    "ebaef8fdf1645032010e801fad010338d2048fa3e67154d660545b4eb9b01c58",
    "eb99d374aa8f620878d86e987ed1943329280668c60ec0d87de3e7182a87a659"
]An example of a command to delete a UniquID contract between two IoT devices.
The transaction Ids can be passed as arguments on the command line.$ uniquid delete-contracts ebaef8fdf1645032010e801fad010338d2048fa3e67154d660545b4eb9b01c58Log FileAll commands append their output to a log file in the user's current working
directory.  Each day a new log file is created which includes the current
date in the filename.  The prefix of the log file's name isuniquid_cli_.Realtime LogThelogcommand allows you to view the actions within the system in real-time.
The command displays information on when blocks are mined, when devices are
imprinted and orchestrated and when contracts are created or revoked.  Use the
[Control + C] key combination to exit thelogcommand.$ uniquid logGenerate a Device Configuration FileIoT devices which are integrated with the UniquID libraries require some
configuration information so that they can connect to the UniquID infrastructure.
This configuration information can be generated and saved in a device
configuration file by the UniquID CLI.
When no third-party IoT hub integration is required i.e. no AWS IoT integration,
then thedeploycommand provides thebasicoption to produce a minimal
device configuration file.$ uniquid deploy basicThis will create a file calleddevice_cfg.jsonwhich contains the necessary
configuration information.Integration with AWS IoTThe UniquID system allows you to integrate your IoT devices into both the
UniquID and Amazon AWS IoT systems.  UniquID contracts can then be used
to securely enable and disable interactions between IoT devices and the
AWS IoT Hub.
The user is guided through this integration process by thedeploycommand.
Before starting with the AWS integration, the user should verify that they are
registered with AWS and that they can connect to AWS using Amazon's AWS CLI
tool (awscli).The command to start the deployment of the UniquID Agent to the user's
Amazon AWS account is:$ uniquid deploy awsEach integration, which is performed, creates new resources in the user's
AWS account.  Each of these resources is identified by a unique name which
includes a timestamp.  The timestamp value is printed to the console
at the end of thedeploycommand and it is also added to the
log file.  This timestamp is useful later if the user would like to identify
and remove or update any of the resources.If the user would ever like to remove the components which were created in
AWS by thedeploycommand, they can use theundeploycommand.$ uniquid undeploy aws <timestamp values>Theundeploycommand accepts a space-separated list of timestamp values, each
of which identifies the resources created by a previous execution of thedeploycommand.Getting HelpCome over and join in the UniquID community atGitter.Contact UniquIDIf you would like to learn more about our innovative technology, please contact
us athello@uniquid.com.