Installing and configuring crandas

Crandas is a way to interact with the Roseman Labs engine. In order to use crandas, you must have access to an instance of Roseman Labs. The necessary configuration files must be downloaded from the Roseman Labs platform.

Installation

To install crandas, simply run

pip install crandas --index-url=https://pypi.rosemancloud.com

Note that crandas is not hosted on pypi.org, so it is necessary to add the server url.

The version of crandas must always match the engine version, if you already installed an older version of crandas, you might need to update to the current one:

pip install --upgrade crandas --index-url=https://pypi.rosemancloud.com

Using Jupyter

If you want to use crandas in a Jupyter notebook, you can install the additional packages by adding [notebook].

pip install crandas[notebook] --index-url=https://pypi.rosemancloud.com

We recommend using a virtual environment (venv) to run crandas. For more information about virtual environments, see here.

Working on Windows

Windows does not have python installed by default. In that case, you must first install Python 3.9 or higher. Don’t forget to tick the box that says Add python.exe to PATH to ensure you can run python from any directory.

Using Jupyter

When using Jupyter notebooks in Visual Studio Code, make sure to have the latest versions of packages, as earlier versions of VS Code did not correctly display the progress bar. More information about which package versions are needed can be found here.

• pip install --force-reinstall -v "ipywidgets >= 7.7.2"

• pip install --force-reinstall -v "jupyterlab_widgets >= 1.1.1"

Install a specific version of crandas

To install a specific version of crandas instead run:

pip install --force-reinstall -v crandas==<version> --index-url=https://pypi.rosemancloud.com

You can replace <version> with the version of crandas you wish to install, e.g. v1.15.3.

Installing the python package is not enough to start using crandas, you also need to configure the settings to connect to the Roseman Labs engine.

Configuring crandas

After installing crandas, you must configure the system to connect to the Roseman Labs engine. This step requires access to the Roseman Labs platform in order to download the necessary configuration file. First of all, you must check that you have the analyst role in the platform, this is necessary to perform any analysis.

Tip

A video version of these instructions can be found on the Roseman Labs YouTube channel.

Crandas can run in either in design mode or in authorized mode. More information about these modes and how they relate to each other can be found on the help center.

Downloading the connection file

Follow these instructions to download the connection file from the platform. The file <your-environment>.vdlconn will be downloaded and must be placed in a specific place, depending on your operating system.

LinuxWindows

1. Using the terminal, create a new crandas folder inside the .config folder (mkdir -p ~/.config/crandas).

2. Move the file <your-environment>.vdlconn to the crandas folder you just created (mv ~/Downloads/<your-environment>.vdlconn ~/.config/crandas)

Contents of the connection file

The connection file contains the URL and certificate for one of the servers, and public keys for the 3 servers to encrypt the uploads and downloads.

• Server public keys: We have a public key for each of the 3 servers. These keys are used to encrypt input data that is sent towards each server. The crandas client connects to one of the servers and sends the encrypted input data. The connected server, that can only decrypt 1 of the 3 encrypted streams, then forwards the encrypted data to the other two servers.

• Certificate: When the crandas client connects to the engine, the certificate authenticates the engine server for the client. This ensures that the client is connecting to the correct server.

Downloading the analyst key

The analyst key is a cryptographic key that will allow its holder to execute authorized computations. When an analysis is uploaded to the platform by the analyst, it is signed with their analyst key. When executing in authorized mode, this key will be needed to ensure that the analyst that uploaded the analysis is the one who actually executes it (verified with the public key). This key should remain private.

Follow these instructions to download the private key from the authorized platform. The key must be moved to the same folder as the connection file (~/.config/crandas) and renamed to analyst.sk. Alternatively, when using crandas you will need to specify the path to your key when using connect().

Warning

This key can only be downloaded once. If lost, it will not be possible to execute any analysis, even those that have been previously approved. If that occurs, contact your system administrator. Do not share it with anyone.

Using crandas

After installing and configuring crandas, it is just a matter of opening python and importing the package.

import crandas as cd

# Connect to the engine. The connection file specifies whether to
# connect in design or authorized mode
cd.connect("<your-environment>")

If you do not use the default name analyst.sk and location for the analyst key as described above (for example, when you have multiple keys from multiple environments), you can specifically choose which analyst key to use as follows:

cd.connect("<your-environment>", analyst_key="PATH_TO_ANALYST_KEY")

After this, crandas will be ready for us to use it to make secure computations.