Installation (local python)¶

This page explains how crandas can be installed locally. Note that 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.

Warning

The entire installation section only applies if you are working in an authorized mode or running crandas locally. In Jupyter environments provided by Roseman Labs, crandas is pre-installed – so skip ahead to the next section. To complete this manual you will need to download and install Python 3.9 or higher. If you are installing on Windows, don’t forget to tick the box that says Add python.exe to PATH to ensure you can run python from any directory.

1. Connecting to the engine¶

There are two different ways to connect to the engine: using the actual keys and certificates or using a connection file that contains all of this material in itself. From version 1.9, the connection file is the recommended mode to connect to the engine.

Overview of certificates and files involved¶

Before you begin this process, it is useful to understand what each of the files do.

Server public keys (.pk): 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.
Certificates: 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.
Analyst key (.sk): 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 that actually executes it (verified with the public key). This key should remain private.
Connection file: File that contains the URL and certificate for one of the servers, and public keys for the 3 servers to encrypt the uploads.

Start a connection¶

Log in into the platform and go to Settings >> Account. Click on ‘Download connection file’, and the file <your-environment>.vdlconn it will be automatically stored in your Downloads folder.

Open your home folder:
1. Press WIN+R, the Windows Run window should open
2. Enter %HOMEDRIVE%%HOMEPATH% and press enter.
3. A new Windows Explorer window should open that shows your Home folder.
In this home folder create a new folder called .config (unless it already exists)
Go inside your .config folder and create a new folder named crandas (unless it already exists)
Move the file <your-environment>.vdlconn to the crandas folder you just created.

Open your home folder in a Terminal window (cd ~)
Create a new crandas folder inside the .config folder (mkdir -p ~/.config/crandas). If the .config folder doesn’t exist then it will be created.
Move the file <your-environment>.vdlconn to the crandas folder you just created (mv ~/Downloads/<your-environment>.vdlconn ~/.config/crandas)

When the certificates are the means of authentication in the authorized mode, they will be provided out of band. You should have received an e-mail that contains a link to our secure filesharing system. The first step is storing these certificates in a sub-folder in your home directory.

In case you want to download the provided key material:

Download the ZIP or TAR file from the RL fileshare, and store it in your Downloads folder.
Extract the ZIP or TAR file. You can do this with a program such as 7-Zip.
Open your home folder:
1. Press WIN+R, the Windows Run window should open
2. Enter %HOMEDRIVE%%HOMEPATH% and press enter.
3. A new Windows Explorer window should open that shows your Home folder.
In this home folder create a new folder called vdl_certs
Move the contents of the ZIP/TAR file you unpacked to the vdl_certs folder you just created.

Download the ZIP or TAR from the RL fileshare, and store it in your Downloads folder.
Extract the ZIP or TAR file (go to the folder where the file is located. Right click on the file and then “Extract here” or “Extract to…”).
Open your home folder in a Terminal window (cd ~)
In this home folder create a new folder called vdl_certs (mkdir vdl_certs)
Move the contents of the ZIP or TAR file you unpacked to the vdl_certs folder you just created.

In case you want to generate the keys and certificates yourself, you can follow these steps:

After completing these steps, you will have successfully generated the key pairs and can proceed to use crandas in your Python scripts.

2. Installing crandas¶

To be able to use crandas in your Python scripts we are going to install it by using: pip install crandas --index-url=https://pypi.rosemancloud.com.

crandas is hosted on a private Roseman Labs server rather than pypi.org, so it is necessary to explicitly add the server url.

Install a specific version of crandas¶

To install a specific version of crandas we can run: pip install crandas==<version> --index-url=https://pypi.rosemancloud.com. You can replace <version> with the version of crandas you wish to install, e.g. v1.10.0. Pip will occasionally not properly install a different version, in that case you can do the following: ``pip install –force-reinstall -v “crandas==<version>”.

We recommend installing crandas in a virtual environment:

If we want to install crandas in a virtual environment using venv on Windows.

Open a Command Prompt window:
1. Press WIN+R, the Windows Run window should open
2. Enter cmd and press enter.
3. Navigate to the Home directory: cd %HOMEPATH% (or same as when saving the script above)
Create virtual environment by executing: python -m venv .crandas
Activate virtual environment by executing: .\.crandas\Scripts\activate.bat (you will know it has been activated as it will say (.crandas))
Install crandas: pip install crandas --index-url=https://pypi.rosemancloud.com

Note

When you exit your virtual environment, you can activate it again as follows:

Windows key + R, then type cmd.
.\.crandas\Scripts\activate.bat

If we want to install crandas in a virtual environment using venv on Linux.

Open a Terminal window and navigate to the home directory folder: cd ~
Create virtual environment: python3 -m venv .crandas
Activate virtual environment: source .crandas/bin/activate.
Install crandas: pip install crandas --index-url=https://pypi.rosemancloud.com

Note

When you exit your virtual environment, you can activate it again as follows:

Navigate to the home directory folder: cd ~
Activate virtual environment: source .crandas/bin/activate.

Now crandas has been installed, we can start creating a script in a python editor of our choice. In this case, we refer to Jupyter:

Note

On Debian/Ubuntu systems, you need to install the python3-venv package using the following command.

apt install python3.10-venv

You might need super user (sudo) privileges to execute this command.

For use with Jupyter notebooks¶

To install crandas for use with Jupyter, use pip install "crandas[notebook]" --index-url=https://pypi.rosemancloud.com. This also installs dependencies that are needed to let crandas function well with Jupyter, in particular to show the progress bar for long-running operations.

Note

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"

3. Start an analysis¶

We should still be in the virtual environment we created shown by (.crandas). Now we need to install a development environment such that we can work with crandas more easily, for example: pip install notebook will install jupyter notebook in the virtual environment (you will know it has been finished as it will say successfully installed...).

We can start creating our analysis by executing python -m jupyter notebook (or any python editor) and clicking new to start a new notebook.

Finally we need to tell crandas the endpoint of the engine and which certificates to use to connect to it. This depends on whether you used the connection file or the actual certificates and key material:

import crandas as cd

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

import crandas as cd
from crandas.base import session
from  pathlib  import  Path

# Update to provided endpoint https://**NODE_IP**:**NODE_PORT**/api/v1
# (e.g. https://vdl-1c-cr-node2.rosemancloud.com:32601/api/v1)
session.endpoint = '_____'

# Set the base path to the folder where we have stored the certificates
session.base_path = Path('./vdl_certs')

# connect your session to the engine
session.connect(mode="authorized") # authorized mode
session.connect(mode="design")     # design mode

# Set the path to the http certificate
# (provided by Roseman Labs)
session.certificate_path = Path("httpd0.crt")

# Set the path to the analyst key
# Note: The filename might have a different key, confirm by checking the vdl_certs directory
session.query_signing_key = Path.home()/ 'vdl_certs/analystsign0.sk'

# (Authorized only) Set path to recording which contains the authorized transactions
# The authorization is generated in the platform
session.authorization_file = 'signed-transactions.recording'

To confirm that the setup has been done correctly, just send any query to the server, for example cd.demo_table().

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