CSJCurrent en:About API Functions

---

This section describes what methods the Cryptshare Java API provides, and how to use them to perform the desired operations. All methods are provided by the API's Client object, so in order to use any of the API's functionality, you will need to first create an instance of the Client class. The main purpose of the API is to provide you with a simple way to transfer files with the Cryptshare Server, so the creation of a Client instance always requires the sender's email address, the URL to the Cryptshare Server in the form of a CryptshareConnection instance and the verification data.

Creating the Client

The first step in creating the Client instance is to create a CryptshareConnection, initialized with your Cryptshare Server URL. The CryptshareConnection constructor requires a WebServiceUri object as its parameter, which is a class that takes your base server URL address and automatically creates the correct service URLs for the API to access the Cryptshare web services of your server. Once the CrptshareConnection instance is created, you can use it as a parameter to the Client's constructor. Besides the CryptshareConnection instance, the Client's constructor also requires the sender's email address, as well as either the path to a verification store file, or the encrypted verification store bytes directly. The verification store contains the verification data for your client or sender addresses, depending on the Verification Mode configured on the Cryptshare Server. The verification store data is encrypted with your Client Key (see   About API Functions). When specifying a store path, you can either write the full path of your verification store, including the file name, such as "C:\\temp\\client.store", or just the directory path, such as "C:\temp". If you only specify a directory path, the Client will look for a file named "client.store" in the specified directory. If the verification store file does not exist, it will be automatically created by the Client. If you pass in the encrypted store bytes directly to the Client's constructor, no file will be created by the Client. The data bytes will simply be decrypted with your Client Key and only available in memory. Here is an example of creating a Client instance by specifying a verification store file:

Example: Creating a Client with a Store Path

// Create a WebServiceUri for your Cryptshare Server 
WebServiceUri serviceUri = new WebServiceUri("https://cryptshare.server.com");

// Create a CryptshareConnection instance for your WebServiceUri
CryptshareConnection connection = new CryptshareConnection(serviceUri);

// Create the Client instance with the sender's email address, 
// the CryptshareConnection, and the path to the verification store.
Client client = new Client("sender_email@server.com", connection, Paths.get("C:\\temp"));

Once the Client instance is created, you can call its methods to perform the desired service operations, as described in the respective sections of this manual. Please note that most service operations require a verified Client or sender address. How to verify your Client or sender address is described in the section Verification.

Client ID and Client Key

The Client ID identifies a particular computer client used to run an application which uses the Cryptshare Java API. The Client ID contains data which uniquely identifies the computer instance, such as the computers MAC addresses. The Client ID is created when the application is started for the first time and stored in the verification store for subsequent uses. The Client ID is needed for the communication with the Cryptshare Server. If the verification mode on the Cryptshare Server is configured to be Client Verification, this Client ID will have to be used as the verified Client ID on the server. The Client Key is, like the Client ID, based on the unique computer MAC addresses and is used to encrypt the verification store data. So when the Client opens its verification store, it will create the Client Key and use it to decrypt the store data.

Warning

Since the Client Key is based on the computer's MAC addresses, exchanging the network adapters in your computer will result in a new and different Client Key. You would then not be able to access the verification store anymore, since it was encrypted with the old key, and any verification data you had previously saved in the store would be lost. The Cryptshare Server would see the Client again as unverified, and you would have to repeat the verification process again. To avoid that, you may want to consider changing the MAC address of the new network card to the old MAC address, if possible.

---