CSRCurrent en:Using the Program

---

Overview

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 read the chapter Options for detailed information about available options.

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. 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. 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. When using an options file, the files have to be listed under the parameter `transfer_files`, and they have to be separated by commas. 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: 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

Operating 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

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: Request Verification Status

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

Sender Verification Mode

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 mail box. 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:

1. The Verification Mode on the server has to be set to Sender Verification.
2. 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.
3. 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.
4. Once the user receives the email message, he can enter the verification code at the Cryptshare Robot's command line prompt.
5. The Cryptshare Robot then saves the code in its verification store (see 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, and will only allow the transfer if they match.

You can find information regarding the maximum number of verification codes to be entered here.

Example: Triggering a new Sender Verification

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

Client Verification Mode

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 and 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:

1. The Verification Mode on the server has to be set to Client Verification.
   
2. The Cryptshare Robot creates a unique Robot ID, saves it in its verification store (see Verification Store), and prints it out on the screen (option `-v`).
3. The generated ID is added in the Cryptshare Server settings using the Administration Interface (under Add-On Products).
   
4. 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: 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)

Hinweise zur 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: 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

Please read the chapter Options for detailed information about all available options.

---