Class Directory

Package: keychain.util.directory

Inheritance: Directory

Description

The Directory class (called pair_helper in the C++ library) is a built-in utility class to enable fast prototyping with a connection to a Keychain-hosted bare-bones Trusted Directory implementation.

A Trusted Directory is often deployed for the following reasons:

To be a source of contacts that are unable to be physically paired
To be a source of additional information about contacts, such as group membership

Keychain has implemented a very simplistic Trusted Directory on our server that this class can connect to in order to do basic functionality. Users can upload their persona, download all URIs for a given domain, and delete all URIs in a domain.

The class has a thread that performs get and upload actions (see below) at a user-specified frequency. The user can start and stop this thread, but at present there is no other interaction with it or hooks exposed to the user.

This class is for development only. It also requires coordination with Keychain to set up a domain on the Trusted Directory and does not provide any security guarantees that a full-fledged Trusted Directory would.

Since: v2.0

Public Constructors

Constructor

Constructor
Directory(settings: `Settings, domain: str`, gateway: `Gateway`, refresh_time: `int`)` Creates a new `Directory` from the Trusted Directory settings in `settings` for the provided domain string. It will refresh itself every `refresh_time` seconds (min 5s) by reaching out to the Keychain TD. The `gateway` is used to get/set personas and contacts for sending and receiving to the TD.

Directory(settings: `Settings, domain: str`, gateway: Gateway, refresh_time: int)`

Creates a new Directory from the Trusted Directory settings in settings for the provided domain string. It will refresh itself every refresh_time seconds (min 5s) by reaching out to the Keychain TD. The gateway is used to get/set personas and contacts for sending and receiving to the TD.

Public Member Functions

Return type Method and Description

Return type	Method and Description
`int`	`clear_all_uri()` Deletes all URIs for the domain
`int`	`upload_uri(uri: Uri)` Uploads the given URI to the server under the domain
`list[tuple[Uri, str]]`	`get_all_uri()` Retrieves all URIs under the domain as a `list` of `tuple` of the `Uri` and its subname.
`None`	`on_start()` Tells the update thread to start
`None`	`on_stop()` Tells the update thread to stop, then waits for it to finish before exiting.

int

clear_all_uri()

Deletes all URIs for the domain

int

upload_uri(uri: Uri)

Uploads the given URI to the server under the domain

list[tuple[Uri, str]]

get_all_uri()

Retrieves all URIs under the domain as a list of tuple of the Uri and its subname.

None

on_start()

Tells the update thread to start

None

on_stop()

Tells the update thread to stop, then waits for it to finish before exiting.

Public Member Functions Detail

clear_all_uri

clear_all_uri() → int

Delete all URIs for the domain and return the library error code. Note that this is a local operation and deletes the URIs from your own Gateway, not the remote TD.

Returns:

The Keychain error code, where 0 is success.

upload_uri

upload_uri(uri: Uri) → int

Upload the given URI to the server under the domain and returns the library error code. Upload will succeed even if the server has the Uri already. Use this to upload your persona to the remote TD (uploading a contact of yours is possible but should be reserved for more complicated workflows and security architectures)

Returns:

The Keychain error code, where 0 is success.

get_all_uri

get_all_uri() → list[tuple[Uri, str]]

Retrieves all URIs under the domain as a collection of pairs of the Uri and its subname (as registered on the directory).

Returns:

The list of URIs and subnames that the directory is aware of for the domain it was created under

Raises:

KeychainError - if the Keychain library ran into an error preventing success

on_start

on_start() → None

Tells the update thread to start. The update thread is responsible for reaching out to the remote directory and periodically executing both an upload of the active persona and retrieving contacts for that persona.

on_stop

on_stop() → None

Tells the update thread to stop, then waits for it to finish before exiting. This action is synchronous and may take up to refresh_time seconds to complete if the Directory is currently sleeping.