Skip to content

Latest commit

 

History

History
155 lines (121 loc) · 7.86 KB

README.md

File metadata and controls

155 lines (121 loc) · 7.86 KB
Raw

Description

This package provides a streamlined API for the identity provider usable from non-Rust languages. The core of the library is src/lib.rs file which defines two functions, validate_request and create_identity_object. In addition to this we provide nodejs and C# exports (optionally) via src/nodejs_exports.rs and src/csharp_exports.rs, respectively. These can be enabled/disabled via the features nodejs and csharp, respectively.

If you need to use the identity issuer functionality from a Rust project this is not the library you want. In such a case it is much better to use the ../rust-src/id crate directly since it provides support for serialization of all the relevant values.

Outline of the identity issuance process.

The identity issuance consists of the following steps. The steps done by this library are marked with (*).

  1. The wallet makes the request to the identity provider.
  2. (*) The identity provider validates the request.
  3. The identity provider checks whether an account already exists on the chain.
  4. The identity provider does the identity verification process (e.g., taking photos, scans, etc). The output of this process should be whatever the identity issuer needs, and a list of attributes that go to the identity object.
  5. (*) Create the initial account object that is sent to the chain, the identity object that is returned to the user, and the anonymity revocation record that is kept by the identity provider.
  6. Try to create the initial account on the chain.
  7. If all the above are successful return the identity object to the user.

API

The exposed API consists of two functions validate_request and create_identity_object.

validate_request

This function is designed to be used when the initial request is made by the user to the identity provider. It will check cryptographic proofs in the request. All arguments are strings that contain JSON encodings of the relevant values.

The arguments are

  • global_context, the context of (public) cryptographic parameters specific to the chain the identity object is destined for
  • ip_info, the public keys of the identity provider. This data is also available on the chain the identity object is destined for.
  • ars_infos, public keys of anonymity revokers the identity provider cooperates with.
  • request, this is the request that the wallet sends which contains cryptographic values and proofs.

In case of success, the return value is

  • an account address encoded as a string. This is the address of the initial account that would be created based on the request. Otherwise, the return value is an error.

create_identity_object

This creates the identity object, the initial account data, and the anonymity revocation record.

The arguments are

  • ip_info, the public keys of the identity provider, same as for validate_request
  • request, the same request as for validate_request
  • alist, the attribute list obtained in step (4) of the identity issuance process (see above)
  • expiry, the expiry time of the account creation message sent to the chain. This is just a unix timestamp that should be set to, e.g., now + 5 min.
  • ip_private_key, the first part of the private key, used to sign the identity object sent back to the user
  • ip_cdi_private_key, the second part of the private key, used to sign the initial account creation message.

The return value is either an error if some of the values are malformed, or a struct containing

  • the identity object that is returned to the user
  • the anonymity revocation record
  • the initial account creation object that is sent to the chain
  • the address of the inital account

Note that the anonymity revocation record only contains the cryptographic parts, the encryptions of data that the anonymity revoker decrypts. It does not contain contact information for the user. It is the responsibility of the identity provider to maintain that data in addition to the anonymity revocation record.

Prerequisites

In order to build you need the following

  • the rust compiler, stable toolchain, a recent version. We've tested with 1.53.
  • clang development libraries. On ubuntu these can be installed with 
    apt install libclang-dev

Building

To build the nodejs exports, do

cargo build --release --features=nodejs
  • On linux this produces a shared library libidiss.so that needs to be loaded into a nodejs instance. To do this move/rename the generated shared library to libidiss.node (the extension is important, the name is not, it just has to match the import statement in javascript later on). On Windows it produces a idiss.dll that (similarly) should be moved and renamed to libidiss.node.

To build the csharp exports, do instead

cargo build --release --features=csharp
  • On Windows this will produce idiss.dll.

Both will build the library and produce artifacts in ./target/release/.

Javascript API

The library exposes two functions

  fn validate_request(global_context: string, ip_info: string, ars_infos: string, request: string): { accountAddress: string } | Error

which validates the given request and returns the account address of the initial account if the request is valid, or an Error otherwise.

  fn create_identity_object(ip_info: string, alist: string, request: string, ip_private_key: string, ip_cdi_private_key: string): {idObject: string; arRecord: string, initialAccount: string} | Error

which creates the identity object to be sent back to the user, as well as the anonymity revocation record, and information about the initial account that must be submitted to the chain. The Error case here can happen if the attribute list (the alist argument) or any other arguments are malformed.

Example

After following the build instructions you can try to run the script example.js as, e.g.,

nodejs example.js

It should print the output of each of the exposed calls.

The script also illustrates the input formats of the values and whether exceptions can or cannot be raised.

C# API

The library exposes two functions validate_request_cs and create_identity_object_cs that can be imported in C# by

[DllImport("idiss.dll")]
private static extern IntPtr validate_request_cs(
[MarshalAs(UnmanagedType.LPArray)] byte[] ctx, int ctx_len, 
[MarshalAs(UnmanagedType.LPArray)] byte[] ip_info, int ip_info_len, 
[MarshalAs(UnmanagedType.LPArray)] byte[] ars_infos, int ars_infos_len, 
[MarshalAs(UnmanagedType.LPArray)] byte[] request, int request_len, out int out_length, out int out_success);

which validates the given request and returns a pointer the account address of the initial account if the request is valid, or a pointer to a bytearray describing an error. It writes to a variable out_length the length of the output. If the request is valid, 1 is written to out_success, otherwise -1 is written to out_success.

[DllImport("idiss.dll")]
private static extern IntPtr create_identity_object_cs(
[MarshalAs(UnmanagedType.LPArray)] byte[] ip_info, int ip_info_len, 
[MarshalAs(UnmanagedType.LPArray)] byte[] request, int request_len, 
[MarshalAs(UnmanagedType.LPArray)] byte[] alist, int alist_len, 
UInt64 expiry,
[MarshalAs(UnmanagedType.LPArray)] byte[] ip_private_key, int ip_private_key_ptr_len,
[MarshalAs(UnmanagedType.LPArray)] byte[] ip_cdi_private_key, int ip_cdi_private_key_ptr_len,
out int out_length, out int out_success);

which returns a pointer to either the identity object to be sent back to the user, as well as the anonymity revocation record, and information about the initial account that must be submitted to the chain, or a pointer to a bytearray describing an error. It writes to a variable out_length the length of the output. If identity creation went well, 1 is written to out_success, otherwise -1 is written to out_success.