CSJCurrent de:Dateitransfer

Allgemeines

Transfers können synchron sowie asynchron über die API durchgeführt werden. Ein Transfer kann mehrere Dateien enthalten und wird anschließend auf den Cryptshare Server hochgeladen, verschlüsselt und den Empfängern zu Verfügung gestellt. Abhängig von den verwendeten Transfereinstellungen werden die Empfänger und der Absender nach der Bereitstellung des Transfers beanchrichtigt. Bevor ein Transfer durchgeführt werden kann, muss dieser, wie im Kapitel 'Transfer vorbereiten' beschrieben, vorbereitet werden. Anschließend kann der Transfer entweder synchron oder asynchron durchgeführt werden.

Transfer vorbereiten

Bevor ein Transfer abgesendet werden kann, muss dieser mit den folgenden Parametern vorbereitet werden:

• Kontaktdaten des Absenders
  • Name
  • Telefonnummer
• Das zu verwendende Passwortsicherheit (optional)
• Der Nachrichtentext für die Absenderbenachrichtigung (optional)
• Die Empfänger-E-Mail-Adressen
• Die Sprache der Benachrichtigung (optional)
• Die gewünschte Liegezeit für den Transfer (optional)
• Die zu übertragenden Dateien

Wird der Transfer nicht gestattet, da einige Empfänger dafür nicht zugelassen werden, so wird eine Exception geworfen. Um dies zu vermeiden, kann vor dem Transfer eine Policyüberprüfung durchgeführt werden.

Das Passwortverfahren

Bei dem für einen Transfer verwendeten Passwortverfahren muss es sich um ein erlaubtes Passwortverfahren handeln, das in der Policyregel definiert ist.

Manuelles Passwort - 'manual'

Beim Passwortverfahren PasswordMode.MANUAL müssen Sie explizit ein Passwort für den Transfer vergeben. Das Passwort kann mit den Funktionen aus dem Kapitel 'Passwortfunktionen' auf die aktuellen Sicherheitsanforderungen überprüft werden. Der Empfänger muss bei diesem Verfahren Kontakt mit dem Absender aufnehmen, um das Passwort zu erfahren.

Generiertes Passwort - 'generated'

Der Client fordert bei diesem Verfahren ein automatisch generiertes Passwort vom Server an, welches die geforderten Sicherheitsanforderungen erfüllt. Der Empfänger muss bei diesem Verfahren Kontakt mit dem Absender aufnehmen, um das Passwort zu erfahren.

Kein Passwort - 'none'

Bei diesem Verfahren muss keiner der Beteiligten ein Passwort für den Transfer angeben. Dies wird vom Server für den Anwender 'unsichtbar' gehandhabt.

Beachten Sie bitte, dass dieser Modus als der unsicherste Modus gilt und daher nur in ausgewählten Fällen verwendet werden sollte.

Die Benachrichtigungssprache

Die Benachrichtigungssprache kann für den Absender und die Empfänger separat über die entsprechende Locale angegeben werden. Sie können nur Sprachen angeben, welche auf dem Server auch als Sprachpaket installiert sind (siehe Kapitel 'Sprach-Ressourcen').

Der Benachrichtigungstext

Sie können für die Empfängerbenachrichtigung einen eigenen Betreff oder auch Inhalt verwenden. Das Transfer-Objekt stellt hierfür Setter für das message- und subject-Feld bereit, die jeweils mit einem String oder InputStream, der automatisch ausgelesen wird, gefüllt werden können. Der Text muss im UTF-8 Format angegeben werden. Der Nachrichteninhalt kann HTML-Markup enthalten, der Nachrichtenbetreff hingegen nicht.

Vertrauliche Nachricht

Sofern die Policyregel dies erlaubt, kann auf dieselbe Weise wie ein Benachrichtigungstext auch eine vertrauliche Nachricht zu dem Transfer hinzugefügt werden. Dies geschieht über die Setter für die Felder confidentialMessage und confidentialSubject, die wie die Benachrichtigung als String oder auch InputStream angegeben werden können. Für diese gelten dieselben Einschränkungen wie auch bei der Benachrichtigung. Die vertrauliche Nachricht wird zusammen mit den Transferdateien verschlüsselt und kann von den Empfängern beim Abruf des Transfers eingesehen werden.

Ablaufdatum

Wenn Sie ein Ablaufdatum für den Transfer angeben, stellen Sie sicher, dass dieses innerhalb der von der Policyregel maximal erlaubten Zeitspanne liegt. Der Transfer wird nur bis zum angegebenen Datum abrufbar sein.

Transfervorbereitungen abgeschlossen

Sobald ein Transfer Objekt wie im Beispiel vollständig vorbereitet wurde, so kann dieser Transfer entweder synchron oder asynchron verschickt werden. Mehr Informationen erhalten Sie in den nachfolgenden Kapiteln.

Cryptshare Transfer vorbereiten

// First create the Client instance
// Create a WebServiceUri for your Cryptshare Server
WebServiceUri serviceUri = new WebServiceUri("https://cryptshare.yourdomain.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("john.adams@yourdomain.com", connection, Paths.get("C:\\temp\\client.store"));

// Create a new Transfer object
Transfer transfer = new Transfer();

// Set the name of the sender
transfer.setSenderName("John Adams");

// Set the sender's phone number
transfer.setSenderPhone("234 5467");

// Set the message text of the mail that is to be included in the transfer.
// The Transfer object's setMessage(..) method takes either an
// actual text string containing the email message, or an InputStream
// which contains the email message text. If specifying an InputStream, the
// stream needs to be UTF-8 encoded, to ensure that the characters can be
// read in and displayed correctly in the email message.
try (FileInputStream inputStream = new FileInputStream("C:\\temp\\message.txt")) {
	// To illustrate, we'll use the message text from an input stream.
	// Your application may get this input stream from another process, for
	// instance, but in this example, we will just read it in from a file
	// Set the input stream as the message. The method will read in
	// the text from the stream and automatically close the stream when it's done.
	transfer.setMessage(inputStream);
} catch (Exception ex) {
	// there was an error reading the text file, so show an error message
	System.err.println("Error reading the message file!");
}

// Set the subject text of the mail that is to be included in the transfer.
transfer.setSubject("Subject of the Transfer");

// Define the recipients
List<String> recipients = new ArrayList<String>();
recipients.add("jane.doe@abc.com");
recipients.add("jack.smith@xyz.com");

// Get the policy rule from the server for the given recipients, so we can
// check to make sure they are allowed
Policy policy = client.requestPolicy(recipients);

// Check to make sure the recipients are allowed and only add them
// to the transfer, if they are
if (policy.getFailedEmailAddresses() != null && !policy.getFailedEmailAddresses().isEmpty()) {
	for (String recipient : recipients) {
		if (!policy.getFailedEmailAddresses().contains(recipient)) {
			transfer.addRecipient(new Recipient(recipient));
		} else {
			System.out.println("The recipient is invalid: " + recipient);
		}
	}
} else {
	// all recipients are valid
	List<Recipient> recipientList = recipients.stream().map(Recipient::new).collect(Collectors.toList());
	transfer.addRecipients(recipientList);
}

// If allowed by the policy, we can also send a confidential message to the
// recipients
if (policy.isAllowConfidentialMessage()) {
	transfer.setConfidentialSubject("Subject of the confidential message");
	transfer.setConfidentialMessage("This is the text of the confidential message.");
}

// Only continue if we have at least one valid recipient for the transfer
if (transfer.getRecipients() == null || transfer.getRecipients().isEmpty()) {
	throw new Exception("No valid recipients defined, aborting transfer.");
}

// Set the password mode that will be used for this transfer.
// Must be one of the password modes allowed by the policy.
// We will just pick the most secure mode allowed by the policy
PasswordMode passwordMode;
Set<PasswordMode> allowedPasswordModes = policy.getAllowedStandardPasswordModes();
if (allowedPasswordModes.contains(PasswordMode.GENERATED)) {
	passwordMode = PasswordMode.GENERATED;
} else if (allowedPasswordModes.contains(PasswordMode.MANUAL)) {
	passwordMode = PasswordMode.MANUAL;
} else {
	passwordMode = PasswordMode.NONE;
}
transfer.setPasswordMode(passwordMode);

// If password mode is MANUAL, we have to set a password
if (passwordMode.equals(PasswordMode.MANUAL)) {
	// we have to manually set a password for this transfer
	transfer.setPassword("p4$$w0rd");
}

// Define if the file names should be shown in the recipient's
// notification email
transfer.setShowFilenames(true);

// Define if the sender should be notified when the recipients
// download the files
transfer.setInformAboutDownload(true);

// Set the language for the recipient notification email
transfer.setRecipientLanguage(Locale.ENGLISH);

// Set the language for the sender notification email
client.setUserLanguage(Locale.ENGLISH);

// Set the expiration date of the files
// (how long the files will be available for download)
// We'll just set it to the maximum allowed storage duration
int storageDuration = policy.getStorageDuration();
Calendar cal = Calendar.getInstance();
cal.add(Calendar.DAY_OF_MONTH, storageDuration);
transfer.setExpirationDate(cal.getTime().toInstant().atZone(ZoneId.systemDefault()).toLocalDate());

// Add the files for this transfer
// A TransferFile object has to be created for each file you would like to add to the transfer
// Add a file from the file system, specified as a complete file path:
transfer.addFile(new TransferFile(Paths.get("C:\\temp\\transfer_file_01.txt")));

// Add a stream that contains the data for a file.
// Your application may have received this stream from another process, for instance,
// but for this example, we will just create an input stream from a file
try {
	File inputFile = new File("C:\\temp\\transfer_file_02.txt");
	FileInputStream inputStream = new FileInputStream(inputFile);
	long streamSize = inputFile.length();

	// Create the TransferFile object for this stream. You also need to specify
	// a name for the file that will be created from the data of this stream, including
	// a file extension, so that the recipient will be able to open it with the correct
	// application, as well as the size of the stream. The stream will be closed
	// automatically, once it has been uploaded to the server.
	TransferFile streamFile = new TransferFile("MyAttachment.txt", inputStream, streamSize);
	transfer.addFile(streamFile);
} catch (Exception ex) {
	ex.printStackTrace();
}
// Add another file from the file system
transfer.addFile(new TransferFile(Paths.get("C:\\temp\\transfer_file_03.txt")));

// Now we can use this transfer object to perform the transfer
// either synchronously or asynchronously
 ...

---

Transfer durchführen

Synchron

Ist der Transfer, wie im vorigen Kapitel beschrieben, vorbereitet, so kann dieser nun mittels der Methode #performTransfer(Transfer, ...diverse Callbacks) synchron bereitgestellt werden. Folgende Parameter müssen dabei angegeben werden:

• Der vorbereitete Transfer
• Diverse Callbacks zur Anzeige des Transferfortschritts

Da dies eine synchrone Operation ist, wird die Methode so lange 'blockieren', bis alle Dateien hochgeladen und der Transfer abgeschlossen ist.

Durchführen eines synchronen Transfers

 private static void performTransferSynchronous() {
 	// First create the Client instance
 	// 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"));
 
 	// Prepare the transfer object as described in the example above
 	Transfer transfer = ...
 
 	// Perform a synchronous transfer with four event handlers.
 	// Method will block until the transfer is completed.
 	client.performTransfer(transfer,
 					   new UploadProgressChangedHandler(),
 					   new UploadCompleteHandler(),
 					   new UploadInterruptedHandler(),
 					   new UploadCancelledHandler(),
 					   1000);
 }
 
 public class UploadProgressChangedHandler implements IUploadProgressChangedHandler {
 	@Override
 	public void progressChanged(String currentFileNo, String currentFileName, double bytesUploaded, double bytesTotal, long bytesPerSecond) {
 		// This method is called repeatedly with the current upload data
 		// Our upload listener will just output the current progress to the console
 		double percent = ((bytesUploaded / bytesTotal) * 100.0);
 		System.out.println("Transfer progress ... " + ((int)percent) + "%");
 	}
 }
 
 public class UploadCompleteHandler implements IUploadCompleteHandler {
 	@Override
 	public void uploadComplete(Map<String, String> urlMappings, Map<String, String> smtpMappings, String serverGenPassword, TransferError transferError,
 			String trackingId) {
 		// this method is called when all files of the transfer have been uploaded
 		System.out.println("Upload completed!");
 	}
 }
 
 public class UploadInterruptedHandler implements IUploadInterruptedHandler {
 	@Override
 	public void uploadInterrupted(CryptshareException cryptshareException) {
 		// this method is called when an exception occurs during the file upload
     	System.out.println("An exception occurred during the upload: " + cryptshareException);
 	}
 }
 
 public class UploadCancelledHandler implements IUploadCancelledHandler {
 	@Override
 	public void cancelled() {
 		// this method is called when the transfer has been cancelled 
 		// using the cancelTransfer() method
 		System.out.println("The transfer has been canceled!");
 	}
 }

Asynchron

Ist der Transfer, wie im vorigen Kapitel beschrieben, vorbereitet, so kann dieser nun mittels der Methode #beginTransfer(Transfer, ...diverse Callbacks) asynchron bereitgestellt werden. Folgende Parameter müssen dabei angegeben werden:

• Der vorbereitete Transfer
• Diverse Callbacks zur Anzeige des Transferfortschritts

Entgegen dem synchronen Upload wird diese Methode unmittelbar abgeschlossen, nachdem der Transfer in einem eigenen Thread gestartet wurde. Ist der Transfer abgeschlossen, so wird die Methode uploadComplete des übergebenen IUploadCompleteHandlers aufgerufen.

Einen Transfer abbrechen

Wenn ein bereits gestarteter Transfer abgebrochen werden soll, so können Sie die Methode cancelTransfer() des Clients verwenden. Diese Methode stoppt den aktuellen Dateiuploadprozess und bricht den Transfer ab. Ein Transfer kann nur dann abgebrochen werden, wenn sich dieser im Uploadprozess befindet. Sobald alle Dateien des Transfers auf den Server hochgeladen wurden, ist der Transfer vollständig und kann nicht mehr über die API abgebrochen werden. Möchten Sie den Transfer nicht mehr abrufbar machen, nutzen Sie die Funktion "Transfer zurückziehen".

Durchführen eines asynchronen Transfers

 private static void performTransferSynchronous() {
 	// First create the Client instance
 	// 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"));
 
 	// Prepare the transfer object as described in the example above
 	Transfer transfer = ...
 
 	// Perform an asynchronous transfer with a new anonymous TransferUploadListener instance
 	// Method will return immediately
 	client.beginTransfer(transfer,
 					   new UploadProgressChangedHandler(),
 					   new UploadCompleteHandler(),
 					   new UploadInterruptedHandler(),
 					   new UploadCancelledHandler(),
 					   1000);
 }
 
 public class UploadProgressChangedHandler implements IUploadProgressChangedHandler {
 	@Override
 	public void progressChanged(String currentFileNo, String currentFileName, double bytesUploaded, double bytesTotal, long bytesPerSecond) {
 		// This method is called repeatedly with the current upload data
 		// Our upload listener will just output the current progress to the console
 		double percent = ((bytesUploaded / bytesTotal) * 100.0);
 		System.out.println("Transfer progress ... " + ((int)percent) + "%");
 	}
 }
 
 public class UploadCompleteHandler implements IUploadCompleteHandler {
 	@Override
 	public void uploadComplete(Map<String, String> urlMappings, Map<String, String> smtpMappings, String serverGenPassword, TransferError transferError,
 			String trackingId) {
 		// this method is called when all files of the transfer have been uploaded
 		System.out.println("Upload completed!");
 	}
 }
 
 public class UploadInterruptedHandler implements IUploadInterruptedHandler {
 	@Override
 	public void uploadInterrupted(CryptshareException cryptshareException) {
 		// this method is called when an exception occurs during the file upload
     	System.out.println("An exception occurred during the upload: " + cryptshareException);
 	}
 }
 
 public class UploadCancelledHandler implements IUploadCancelledHandler {
 	@Override
 	public void cancelled() {
 		// this method is called when the transfer has been cancelled 
 		// using the cancelTransfer() method
 		System.out.println("The transfer has been canceled!");
 	}
 }