SendCrypt CLI (Command Line Interface) for SendCrypt is a wrapper around third-party libraries that allows you to send encrypted data through SFTP in the same manner as SendCrypt Desktop Application.

If you want to integrate SendCrypt in your bioinformatics pipeline, it’s the perfect solution.

Pre-requisites

Contrary to SendCrypt Desktop Application, SendCrypt CLI is a set of bash scripts which act as wrappers around different third-party libraries. Therefore, you need to make sure that those libraries are properly installed.

You will need to have the following libraries installed:

• Bash

• Git

• GnuPG

• SSH

MacOS specific pre-requisites:

• gtar

• shasum

Linux specific pre-requisites:

• tar

• sha256sum

Installation

SendCrypt CLI is installed by running one of the following commands in your terminal. You can install this via the command-line with either curl, wget or another similar tool.

Now that the CLI is installed, you will need to modify your PATH variable, so that the command sendcrypt will be available in your terminal.

To make the sendcrypt command available in your terminal, you need to add the following line to your ~/.bashrc file:

export PATH="$HOME/.sendcrypt:$PATH"

If you are using zsh, you need to add the following line to your ~/.zshrc file:

export PATH="$HOME/.sendcrypt:$PATH"

Then, run the following command:

source ~/.bashrc

or

source ~/.zshrc

Configuration

To be able to send data, the CLI needs to have access to some configurations, such as the SFTP host, the GPG recipient etc. All those values are stored in a profile (similar to a project in SendCrypt Desktop Application).

When installing SendCrypt, a default profile is created. To modify it, open the default.env file located in the $HOME/.sendcrypt/profiles directory and modify the following parameters:

• SENDCRYPT_SFTP_USER is the username used to connect to the SFTP server.

• SENDCRYPT_SFTP_HOST is the hostname of the SFTP server.

• SENDCRYPT_SFTP_PORT is the port used to connect to the SFTP server (22 by default).

• SENDCRYPT_SFTP_REMOTE_PATH is the path to the remote directory where the files will be uploaded.

• SENDCRYPT_SSH_KEY is the path to the SSH key used to connect to the SFTP server.

• SENDCRYPT_GPG_SENDER is the email address of the GPG key used to sign the metadata file.

• SENDCRYPT_GPG_RECIPIENT is the email address of the GPG key used to encrypt the files.

• SENDCRYPT_GPG_PASSPHRASE is the passphrase of the GPG key used to sign the metadata file.

• SENDCRYPT_PROJECT is the name of the project.

• SENDCRYPT_API_URL is the URL to use to send the notification upon a successful transfer (optional).

Authentication

The CLI provides an authentication module to send notifications to https://sendcrypt.sib.swiss upon successful transfers. It is highly recommended to configure it as it will allow the receiver to be notified whenever you send data. Make sure that you have an active account on https://sendcrypt.sib.swiss before proceeding further.

Signing in with your credentials (without 2FA)

Start by running the following command:

sendcrypt login

You will be prompted with questions asking you to fill the required values (the email and password that you used to register on https://sendcrypt.sib.swiss).

If everything went well you should see the message Login successful. If not, make sure to check the error output.

Signing in with a token (with 2FA)

Start by heading to your SendCrypt account. You should see the following section:

Then, run the following command:

sendcrypt login

You will be prompted with questions asking you to fill the required values. Use the email that you used to register on https://sencrypt.sib.swiss and use the previously generated token as your password.

If everything went well you should see the message Login successful. If not, make sure to check the error output.

Signing out

If required, you can easily sign out by using the following command:

sendcrypt logout

Configuring SSH access

The CLI uses the SFTP protocol to transfer data but is only configured to authenticate by using a SSH key pair.

Generating a SSH key pair

To generate a new SSH key pair, use the following command:

ssh-keygen -t rsa -b 4096 -C [your-email]

Register your SSH public key

Once the keys have been generated you will need to share your public key directly with your recipient or register your public key on https://sendcrypt.sib.swiss (recommended way).

Start by copying your SSH public key.

For macOS:

cat ~/.ssh/your_key.pub | pbcopy

For Linux (using xclip):

cat ~/.ssh/your_key.pub | xclip -sel clip

Then, head to your SendCrypt account where you should see your current SSH and GPG keys.

You can define a title if you want and then paste your copied SSH public key in the Key form. Finally, click on Add SSH key.

If everything went well, you should see a banner confirming that you have successfully added your key and your key should now appear under Authentication keys.

Configuring your GPG keys

The CLI uses the recpient GPG key to encrypt the data and your own GPG private key to sign the metadata file. This process ensures that your data is well protected against any malicious actor.

First, you will need to import your recipient GPG public key.

Importing the project GPG key

When registering a profile, it is important to also add the GPG key that will be used to encrypt the files (the key belonging to the project). If you don’t have the key, ask your project administrator to share it with you. To add the key, run the following command:

gpg --import <path-to-key>

Once the key has been imported, you can check that it has been added by running the following command:

gpg --list-keys

For the CLI to work properly, the trust level of the key must be set to ultimate. To do so, run the following command:

gpg --edit-key <key-id> trust

Type 5 to set the trust level to ultimate and press Enter. Then confirm by typing y and pressing Enter. Finally, exit by typing quit and pressing Enter.

Generating a GPG key pair

When sending files, the CLI sign the metadata file with a GPG key on your behalf so that the recipient can verify the sender's identity. You will therefore need to generate a GPG key with your email address. To generate a GPG key, run the following command:

gpg --full-generate-key

• At the prompt, specify the kind of key you want (we recommend using RSA and RSA).

• Then, specify the key size (we recommend using 4096).

• Then, specify the length of time the key should be valid (we recommend using 0, which means that the key will never expire).

• Finally, verify that your selections are correct.

• At the prompt, type your email address, which will be used to identify your key.

• At the prompt, type a passphrase, which will be used to encrypt your private key. Make sure to store it in a safe place.

Register your GPG public key

Once your GPG keys are set up, you will need to transmit your public key to either your recipient, if you don’t have a SendCrypt account, or register it under your account.

Start by copying your GPG public key.

For macOS:

gpg --armor --export your_email@example.com | pbcopy

For Linux (using xclip):

gpg --armor --export your_email@example.com | xclip -sel clip

Then, head to your SendCrypt account where you should see your current SSH and GPG keys.

You can define a title if you want and then paste your copied GPG public key in the Key form. Finally, click on Add GPG key.

If everything went well, you should see a banner confirming that you have successfully added your key and your key should now appear under Authentication keys.

Your key will be automatically shared with any project that you are part of.

Adding a new profile

If you will need to send data to multiple projects (different host, different project name, or different recipient), you can use multiple profiles. To add a new profile, you can run the following command:

sendcrypt profile create

You will be prompted with several questions asking you to fill the required values.

Configure the temporary directory

When a batch is sent, some data preparation is required such as generating the metadata, compressing, encrypting etc. By default, the CLI will use /tmp. If you need to override this setting, simply set the TMPDIR env variable before calling the script.

Using the CLI

If everything has been properly configured as explained above, you are ready to send your first batch of data.

To send files, run the following command:

sendcrypt send <path-to-directory>

If you would like to specify a different profile, use the -p or --profile option:

sendcrypt -p <profile-name> send <path-to-directory> 

The CLI also provides an additional command prepare that allows you to prepare the data according to the SendCrypt format without sending them. This covers scenarios such as preparing correctly the data and sending them manually yourself.

To prepare files, run the following command:

sendcrypt prepare <path-to-directory>

If you would like to specify a different profile, use the -p or --profile option:

sendcrypt -p <profile-name> prepare <path-to-directory> 

Running diagnostics

To run diagnostics, run the following command:

sendcrypt doctor

This will check the following:

• Required libraries are installed

• Required commands are available

• Internet connection is available

• Connection to the SFTP server is possible

• Profile files are correctly encoded

Getting updates

To get updates, run the following command:

sendcrypt update

Uninstalling the CLI

If you would like to uninstall SendCrypt, run the following command:

bash ~/.sendcrypt/tools/uninstall.sh