Installation and getting started

Requirements

Java Runtime Environment

Cryptshare Robot is a Java application and can run on almost any platform. It requires Java Runtime Environment (JRE) Version 1.8 or higher. To check which JRE version is installed on your system, execute the command java –version on your command line. JRE installation kits in multiple versions are available at https://adoptium.net/de/temurin/releases?version=11.

Cryptshare Server 4.4.0 or higher

The file exchange and email notification is handled by a Cryptshare Server. It must be licensed for the use of the Cryptshare Robot. Contact Cryptshare support for available licensing possibilities.

Installation

No installation is required. Just start the program file cryptshare-robot-<version>.jar to run Cryptshare Robot. The file must be available to the executing process or the respective user. You can obtain the latest version of the Robot in the login section on Cryptshare.com.

Starting the program

The application is distributed as a Java file package (.jar). To run the program with the Java Runtime Environment, enter the command as seen below:

java -jar <robot>.jar [-options] [files]

Please see Options for detailed information.

Using an Options file

Instead of entering the Robot options on the command line, you may also choose to write them in a file called robot_config.properties.

If no command line arguments are specified when starting the Robot application, the Robot will automatically try to read in the options from the configuration file in the current working directory of the Robot application.

The syntax of the robot_config.properties file is

<standard option name> = <option value>

The standard name of the option is the long form of the parameter name, which would be specified on the command line starting with --, for example --baseUrl.

Please note that the option names are case-sensitive, and have to be written exactly like they are described under Options. The expected encoding of the robot_config.properties file is ISO-8859-1.

When using an options file, the files have to be listed under the parameter transfer_files, and they have to be separated by commas.

When performing a transfer using the command line, the transfer files have to be written at the end of the command line, separated by spaces.

Command options that do not have a value when specifying them on the command line are of type Boolean, which means that they activate certain settings when they are specified on the command line. When using such an option in the option file, its value is set to true. Omitting it from the options file, or setting its value to false, deactivates the specific setting, just like omitting it from the command line. So, to activate the file transfer for instance, add the option sendMode=true to the options file.

On a Windows system: On a Windows system, where the file paths contain backslashes, these backslashes need to be written in escaped form in the options file, in order for the application to process the files correctly. So, for example, if you have a file you wish to include in a transfer that is located at C:\temp\file.txt, you would need to specify that file in the options file as transfer_files=C:\\temp\\file.txt, escaping the "\\" character with "\\\\".

Example 1. robot_config.properties file for a transfer

baseUrl=https://cryptshare.domain.de
sendMode=true
senderAddress=foo.bar@domain.de
senderName=Foo Bar
senderPhone=0761/555-123
recipientAddress = customer@comp.any,manager@domain.de
transfer_files = file1.exe, file2.dll, largefile.zip

Operation modes

The application can perform three types of tasks. You can apply a different set of options to each type.

Requesting information: Cryptshare Robot can be used to request information about the current Cryptshare Server, e.g. a list of supported languages or the maximum upload size.
Verification process: This operation is used to verify the sender or the client (depending on which verification mode is used) and give permissions. A successful verification is required to send files.
Sending files: This mode is used to send files. It requires all information about the sender and the email addresses of the recipients.

Verification process

The verification process allows validating the sender or, depending on which verification mode is used, the specific Robot installation. These modes differ significantly. The following paragraph will describe both of them in detail. The verification mode is defined in the settings of the Cryptshare Server > Add-On Products > Cryptshare Robot. Additional information to the mode that is currently set, can be found in the Cryptshare Administration Interface. Whether a new verification is required can be obtained by use of the parameter -q. For instance:

Example 2. Request verification status

java -jar cs-robot.jar -u https://cryptshare.domain.de -a foo.bar@domain.de -q

Sender verification

This mode works like it does in the Cryptshare web interface. Each sender requires a separate verification. This ensures that the sender is valid and has access to his respective mailbox. It is also important that the email address is verified, because the sender’s email address is used to determine the permissions and restrictions for the transfer. To verify a sender email address, the following steps have to be performed:

The Verification Mode on the server has to be set to Sender Verification.
Cryptshare Robot sends a verification request (option -v) containing the unique Robot ID (see Verification Store) and the sender’s email address to the Cryptshare Server. The robot then prompts the user to enter the verification code.
The Cryptshare Server meanwhile generates a random verification code, stores it in its Database, together with the Robot ID and the specified email address, and then sends the verification code to this email address.
Once the user receives the email message, he can enter the verification code at the Cryptshare Robot’s command line prompt.
The Cryptshare Robot then saves the code in its verification store and will use it for all new transfer operations. Every time a transfer is initiated, the Cryptshare server will then compare the verification code for the sender email address supplied by the Robot, with the code stored in its database. The transfer will only be allowed if the codes match.

See the Cryptshare Server guide for more information regarding the maximum number of verification codes to be entered.

Example 3. Triggering a new sender verification

java -jar <robot>.jar -u https://cryptshare.domain.de -a foo.bar@domain.de -v

Client verification

In this mode, the Robot instance is verified as a whole. You can then use any sender email address with such a verified Robot instance, without the need of individual sender verifications.

Since this procedure does not require separate verification of individual email addresses, this mode should only be used if the sender verification procedure is insufficient for your application purpose.

In the Client Verification Mode, a randomly generated, unique Robot ID (see Verification), is created for the Robot instance. That ID has to be added as a verified Robot Client ID in the Cryptshare Server Administration Interface. This will allow the use of any sender email address from this particular Robot instance.

For a client verification, the following steps have to be performed:

Go to Cryptshare Robot in the Cryptshare Server Administration Interface > Add-on products tab.
The Verification Mode on the server has to be set to Client Verification Mode.
The Cryptshare Robot creates a unique Robot ID, saves it in its verification store (see Verification Store), and prints it on the screen (option -v).
Copy the ID from the commandline and paste the ID into the Server Administration Interface > Add-on products > Cryptshare Robot > Client ID field.
Add a description and Save changes.

When performing a transfer, the Cryptshare Server will then compare the Robot ID with the ID stored in the settings to determine if the Robot instance is verified or not.

Example 4. Triggering a New Client Verification

java -jar <robot>.jar -u https://cryptshare.domain.de -a foo.bar@domain.de -v

Verification store

The Cryptshare Robot stores the Robot ID and any sender verification codes in a file (in the directory from where the Robot is launched). The file is encrypted using hardware information from the host, and usually has the name client.store, unless you specify a different name with the -f option.

Already existing verifications can be used in a transfer only if the same verification store file is specified (or detected) when launching the application. A unique Robot ID is created for each verification store to identify the current copy of the robot.

This means that a user will have access to all available verifications if he has access to the verification store. Therefore, access should be controlled by the respective file system permissions of the operating system to avoid unauthorized access.

Sending files

To perform a transfer, a successful verification of the current instance of the Cryptshare Robot or of the sender is required (see Verification). The option -s is used to send zero or more files to one or multiple recipients. The remaining options are basically the same as those available in the Cryptshare web interface. The following options are mandatory for a transfer:

-u	the URL of the Cryptshare Server
-a	the sender’s email address
-n	the sender’s name
-t	the sender’s phone number
-r	the recipient email address(es)

Syntax

All options used must precede the filename listing
Multiple recipients must be separated by commas.
Multiple file names must be separated by spaces.
File names containing a space must be enclosed in quotation marks.

Example 5. Sending Files with the Cryptshare Robot

java -jar <robot>.jar -s -u https://cryptshare.domain.de -a foo.bar@domain.de -n "Foo Bar" -t "0761/555-123" -r "customer@comp.any,manager@domain.de" file1.exe file2.dll largefile.zip