Quick start guide

sett comes with 3 types of interfaces - please refer to the corresponding sections of this quick-start guide:

  • sett GUI: a graphical user interface.
  • sett CLI: a command-line interface.
  • sett TUI: a terminal user interface. An interactive user interface displayed in the terminal.

For a complete guide on how to use sett, please refer to Encrypting, transferring, and decrypting data and OpenPGP key management.

sett GUI (Graphical User Interface)

Initial setup

  1. Download sett-gui from the download page. If you downloaded an installer, install sett-gui by double-clicking on the installer file.
  2. Run sett-gui by double-clicking on the executable file or by launching the installed app.

Key management

  1. If you do not already have a private/public OpenPGP key pair, go to the Keys tab and create one by clicking on Add > Generate new key pair. See also the instructions given in the Generate a new public/private OpenPGP key pair section.

    You should now see your new key listed in the Keys tab, along with a “Private” label indicating that the private material for this key is present in the local keystore.

  2. If not already done, download the public OpenPGP key of the recipient(s) to whom you intend to send data (or from whom you will receive data).

    Go to the Keys tab and click on Add > Import from keyserver. For details, see Download public OpenPGP keys from the keyserver.

  3. After downloading a new OpenPGP key, verify it to make sure that it is genuine. This can be done by either:

    • If you are a BioMedIT user: verify that the recipient’s key is labelled with a green Approved label. You can also expand the details of the key by clicking on the key in the list or on the small down arrow button to the right and verify that the Approval status is set to “Key is approved on Portal”, and the Revocation status is set to “Valid”.
    • Alternatively, contact the key owner and verify the key fingerprint with them.

Authenticated mode

Authenticated mode refers to a mode where sett users authenticate with the BioMedIT Portal service. This mode is therefore only available to BioMedIT users.

Encrypting and transferring data

In the Encrypt and Transfer Data tab, proceed as follows:

  1. Data to encrypt and/or transfer: add one or more files and directories to encrypt by clicking the Files or Directories buttons.

  2. Sender: select your own OpenPGP key. This is the key that will be used to sign the encrypted data.

  3. Recipients: add one or more recipients by selecting them in the drop-down menu. These are the keys for which the data will be encrypted, i.e. only these recipients will be able to decrypt the data.

  4. Data Transfer ID: specifying a valid Data Transfer Request ID is mandatory when a data package is transferred into the BioMedIT network.

    For non-BioMedIT users, the Data Transfer ID field can be left empty (or set to an arbitrary value), and the Verify package checkbox must be disabled in the Settings tab.

  5. Destination: from the drop-down menu, select a location to where the data should be encrypted and transferred:

    • local: data is encrypted to your local file system.
    • s3: data is encrypted and transferred to an S3 objects store in a single step.
      • If you are in authenticated mode (recommended for BioMedIT users), all s3 argument values are automatically retrieved from the BioMedIT Portal - you have nothing to enter.
      • In non-authenticated mode, you will need to manually enter the S3 destination argument values.
    • sftp: data is encrypted and transferred to an SFTP server in a single step. You will need to enter the SFTP destination argument values.

  6. Click Encrypt data (local) or Encrypt and transfer data (s3 or sftp) to start the encryption workflow.

Transferring existing data packages

In the Encrypt and Transfer Data tab:

  1. Select a data package to transfer using the add sett Package button.
  2. Select the Destination to where the data should be sent: s3 or sftp.
    • If you are in authenticated mode (recommended for BioMedIT users), all s3 destination parameters are automatically retrieved from the BioMedIT Portal. There is nothing to enter.
    • If you are in non-authenticated mode or if you selected the sftp destination, you will need to enter manually all destination argument values.
  3. Click Transfer data to start transferring your data package.

Decrypting data

In the Decrypt tab:

  1. Select the Data package to decrypt:
    1. Select the source where the package is located from the drop-down menu: s3 (S3 object store) or local (local disk).
    2. Specify the data package to decrypt:
    • If the source is local, click on the Select Package button.
    • If the source is s3 and you are in authenticated mode (recommended for BioMedIT users), indicate the name of the data package to decrypt - it will be retrieved automatically from the S3 object store.
    • If the source is s3 and you are in non-authenticated mode, enter the package name as well as all other S3 destination argument values.
  2. Specify the desired Destination directory, where the decrypted data should be saved.
  3. Click on Decrypt package.

sett CLI (Command Line Interface)

The sett CLI mode uses subcommands to perform specific tasks.

Each subcommand includes a help message describing all available options. Use -h for a short description or --help for a detailed explanation.

# Display the overall sett help.
sett --help

# Help for a specific subcommand.
sett encrypt --help
sett decrypt --help
sett keys --help

# Help for a specific subcommand of the `sett encrypt` subcommand.
sett encrypt local -h
sett encrypt local --help

Below are some basic examples of the most used sett subcommands.

OpenPGP key management

# Generate a new OpenPGP key pair.
sett keys generate

# Import a public key from the keyserver.
sett keys import from-keyserver alice@example.com

Encrypt and transfer data

Examples commands to encrypt and transfer (in a single step) an existing sett data package.

# Encryption and transfer to an S3 object store, in authenticated mode.
#
# * Option 1: using interactive authentication (via a web-browser) with Portal.
sett encrypt s3-portal \
   --signer SIGNER_KEY --recipient RECIPIENT_KEY --dtr DATA_TRANSFER_ID  \
   FILES_OR_DIRECTORIES_TO_ENCRYPT
# * Option 2: using a personal access token (PAT) for authentication.
sett encrypt s3-portal \
   --signer SIGNER_KEY --recipient RECIPIENT_KEY \
   --dtr DATA_TRANSFER_ID \
   --pat pat-vy0TY_lQNT3Yg-kw6rka5FGea2rjXx7RToHDZ_xnKsw \
   FILES_OR_DIRECTORIES_TO_ENCRYPT

# Encryption and transfer to an S3 object store, in non-authenticated mode.
sett encrypt s3 \
   --signer SIGNER_KEY --recipient RECIPIENT_KEY \
   --endpoint ENDPOINT --bucket BUCKET \
   --access-key ACCESS_KEY --secret-key SECRET_KEY \
   FILES_OR_DIRECTORIES_TO_ENCRYPT

# Data encryption only, saving to local disk.
sett encrypt local \
   --signer alice@email.com --recipient bob@example.com \
   --output . \
   FILES_OR_DIRECTORIES_TO_ENCRYPT

Transfer a sett package

Examples commands to transfer an existing sett data package.

# Transfer to an S3 object store in authenticated mode.
#
# * Option 1: using interactive authentication (via a web-browser) with Portal.
sett transfer s3-portal SETT_PACKAGE_TO_TRANSFER
# * Option 2: using a personal access token (PAT) for authentication.
sett transfer s3-portal --pat pat-vy0TY_lQNT3Yg-kw6rka5FGea2rjXx7RToHDZ_xnKsw \
   SETT_PACKAGE_TO_TRANSFER

# Transfer to an S3 object store in non-authenticated mode.
sett transfer s3 \
   --endpoint ENDPOINT \
   --bucket BUCKET --access-key ACCESS_KEY --secret-key SECRET_KEY \
   SETT_PACKAGE_TO_TRANSFER

# Transfer to an SFTP server.
sett transfer sftp \
   --host HOST --username USERNAME --base-path DESTINATION_DIRECTORY \
   --key-path SSH_KEY_LOCATION --key-pwd SSH_KEY_PASSWORD \
   SETT_PACKAGE_TO_TRANSFER

Decrypt a sett package

Examples commands to decrypt an existing sett data package.

# Download and decrypt package from an S3 object store in authenticated mode.
#
# * Option 1: using interactive authentication (via a web-browser) with Portal.
sett decrypt s3-portal SETT_PACKAGE_TO_DECRYPT
# * Option 2: using a personal access token (PAT) for authentication.
sett decrypt s3-portal \
   --pat pat-vy0TY_lQNT3Yg-kw6rka5FGea2rjXx7RToHDZ_xnKsw \
   SETT_PACKAGE_TO_DECRYPT

# Download and decrypt package from S3 object store in non-authenticated mode.
sett decrypt s3 \
   --bucket BUCKET --access-key ACCESS_KEY --secret-key SECRET_KEY \
   SETT_PACKAGE_TO_DECRYPT

# Decrypt from the local file system.
sett decrypt local SETT_PACKAGE_TO_DECRYPT

sett TUI (Terminal User Interface)

The sett TUI (Terminal User Interface) provides an interactive interface to sett directly in your terminal. This mode is ideal if you wish to use sett interactively but do not have access to a graphical environment (e.g. because you are working on a remote server via SSH), or if you simply prefer this type of interface.

To launch the TUI, run the sett CLI executable without passing any arguments:

sett