Version vom 7. März 2022, 10:26 Uhr

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 Passwortverfahren (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

// URL zum Cryptshare Server
WebServiceUri uri = new WebServiceUri("https://cryptshare.yourdomain.com");

// Verbindungsinstanz zum Cryptshare Server
CryptshareConnection connection = new CryptshareConnection(uri);

// Client für das Absenden der Requests
Client client = new Client("john.adams@yourdomain.com", connection, Paths.get("C:\\temp\\client.store"));

// Erzeugen eine Transfer Instanz
Transfer transfer = new Transfer();

// Festlegen des Absendernamens
transfer.setSenderName("John Adams");

// Festlegen der Absender-Telefonnummer
transfer.setSenderPhone("234 5467");

/**
 * Festlegen des Benachrichtigungstextes für die Empfängerbenachrichtigung.
 * Der Text kann direkt als UTF-8-codierter InputStream übergeben werden.
 **/
try (FileInputStream inputStream = new FileInputStream("C:\\temp\\message.txt")) {
   // Nachricht wird als InputStream übergeben. Der Stream wird automatisch
   // geschlossen.
   transfer.setMessage(inputStream);
} catch (Exception ex) {
   // Anzeigen einer Fehlernachricht bei Auftreten eines Fehlers
   System.err.println("Der Nachrichteninhalt konnte nicht gelesen werden!");
}

// Festlegen des Betreffs für die Empfängerbenachrichtigung
transfer.setSubject("Betreff für diesen Transfer");

// Festlegen der Empfänger
List<String> recipients = new ArrayList<>();
recipients.add("jane.doe@abc.com");
recipients.add("jack.smith@xyz.com");

// Abrufen der Policy für diese Absender/Empfänger-Kombination,
// um sicherzustellen, dass diese auch zugelassen sind.
Policy policy = client.requestPolicy(recipients);

// Nur zulässige Empfänger zum Transfer hinzufügen
if (policy.getFailedEmailAddresses()�!= null && !policy.getFailedEmailAddresses().isEmpty()) {
   for (String recipients: recipients) {
      if (!policy.getFailedEmailAddresses().contains(recipient)) {
         transfer.addRecipient(new Recipient(recipient));
      } else {
         System.out.println("Der Empfänger ist unzulässig: " + recipient);
      }
   }
} else {
   // Alle Empfänger sind zugelassen.
   List<Recipient> recipientList = recipients.stream().map(Recipient::new).collect(Collectors.toList()); 
   transfer.addRecipients(recipientList);
}

// Sofern durch die Policy erlaubt, senden wir außerdem eine Vertrauliche
// Nachricht
if (policy.isAllowConfidentialMessage()) {
   transfer.setConfidentialSubject("Betreff der vertraulichen Nachricht");
   transfer.setConfidentialMessage("Vertraulicher Nachrichtentext");
}

// Fahre nur dann fort, wenn mindestens ein gültiger Empfänger vorhanden ist
if (transfer.getRecipients() == null || transfer.getRecipients().isEmpty())
   throw new IllegalStateException("Keine gültigen Empfänger gefunden. Der Transfer wird abgebrochen.");

// Festlegen des Passwortverfahrens. In diesem Falle wird der als am
// sichersten geltende Modus verwendet.
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);

// Für den manuellen Passwortmodus muss ein Passwort angegeben werden.
if (passwordMode.equals(PasswordMode.MANUAL)) {
   // Angeben eines manuellen Passwortes
   transfer.setPassword("p4$$w0rd");
}

// Dateinamen sollen in E-Mail-Benachrichtigungen erwähnt werden
transfer.setShowFilenames(true);

// Der Empfänger soll benachrichtigt werden, wenn Dateien heruntergeladen
// werden.
transfer.setInformAboutDownload(true);

// Die Empfängerbenachrichtigung soll auf Englisch versendet werden.
transfer.setRecipientLanguage(Locale.ENGLISH);

// Die Absenderbenachrichtigung soll auf Englisch versendet werden.
client.setUserLanguage(Locale.ENGLISH);

// Festlegen des Datums, an dem der Transfer abläuft.
// In diesem Falle wird das erlaubte Maximum verwendet.
int storageDuration = policy.getStorageDuration();
Calendar cal = Calendar.getInstance();
cal.add(Calendar.DAY_OF_MONTH, storageDuration);
transfer.setExpirationDate(cal.getTime().toInstant().atZone(ZoneId.systemDefault()).toLocalDate());

// Hinzufügen der Dateien zum Transfer. Für jede Datei muss eine TransferFile-Instanz
// erzeugt werden.
transfer.addFile(new TransferFile(Paths.get("C:\\temp\\transfer_file_01.txt")));

// Hinzufügen einer Datei als Stream, der von einer anderen Anwendung kommen kann.
// In diesem Falle wird der Stream aus einer vorhandenen Datei erzeugt.
try {
   File inputFile = new File("C:\\temp\\transfer_file_02.txt");
   FileInputStream inputStream = new FileInputStream(inputFile);
   long streamSize = inputFile.length();

   // Erzeugen der TransferFile-Instanz mit Dateiname und Dateigröße
   TransferFile streamFile = new TransferFile("MyAttachment.txt", inputStream, streamSize);
   transfer.addFile(streamFile);
} catch (Exception ex) {
   ex.printStackTrace();
}
// Hinzufügen einer weiteren Datei.
transfer.addFile(new TransferFile(Paths.get("C:\\temp\\transfer_file_03.txt")));

/**
 * Nun ist das Transfer-Objekt für den synchronen oder asynchronen Versand
 * vorbereitet.
 **/

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() {
	// Schritt 1: Erzeugen einer Client-Instanz
 
	// Anlegen der URL zu Ihrem Cryptshare Server
	WebServiceUri serviceUri = new WebServiceUri("https://cryptshare.server.com");
      
	// Erzeugen der Verbindung zum Cryptshare Server
	CryptshareConnection connection = new CryptshareConnection(serviceUri);
      
	// Erzeugen der Client-Instanz unter Verwendung der Absenderadresse,
	// der Verbindung zum Server und des Pfades für denn lokalen Verifizierungsspeicher.
	Client client = new Client("sender_email@server.com", connection, Paths.get("C:\\temp"));

	// Vorbereiten des Transferobjektes wie in vorigem Kapitel beschrieben.
	Transfer transfer = ...
 
	// Durchführen eines synchronen Transfers mit vier EventHandlern.
	// Die Methode blockiert so lange, bis der Transfer abgeschlossen ist.
	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) {
		// Diese Methode wird während des Uploads wiederholt aufgerufen und gibt
		// den Transferfortschritt auf der Kommandozeile aus.
		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) {
		// Diese Methode wird aufgerufen wenn alle Dateien auf den Server hochgeladen wurden.
		System.out.println("Upload completed!");
	}
}

public class UploadInterruptedHandler implements IUploadInterruptedHandler {
	@Override
	public void uploadInterrupted(CryptshareException cryptshareException) {
		// Diese Methode wird aufgerufen, wenn ein Fehler während des Uploads auftritt
		System.out.println("An exception occurred during the upload: " + cryptshareException);
	}
}

public class UploadCancelledHandler implements IUploadCancelledHandler {
	@Override
	public void cancelled() {
		// Diese Methode wird aufgerufen, wenn der Transfer
		// mittels cancelTransfer() abgebrochen wurde.
		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() {
	// Schritt 1: Erzeugen einer Client-Instanz
 
	// Anlegen der URL zu Ihrem Cryptshare Server
	WebServiceUri serviceUri = new WebServiceUri("https://cryptshare.server.com");
      
	// Erzeugen der Verbindung zum Cryptshare Server
	CryptshareConnection connection = new CryptshareConnection(serviceUri);
      
	// Erzeugen der Client-Instanz unter Verwendung der Absenderadresse,
	// der Verbindung zum Server und des Pfades für denn lokalen Verifizierungsspeicher.
	Client client = new Client("sender_email@server.com", connection, Paths.get("C:\\temp"));

	// Vorbereiten des Transferobjektes wie in vorigem Kapitel beschrieben.
	Transfer transfer = ...
 
	// Starten eines asynchronen Transfers mit vier EventHandlern.
	// Die Methode wird unmittelbar nach Aufruf beendet.
	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) {
		// Diese Methode wird während des Uploads wiederholt aufgerufen und gibt
		// den Transferfortschritt auf der Kommandozeile aus.
		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) {
		// Diese Methode wird aufgerufen wenn alle Dateien auf den Server hochgeladen wurden.
		System.out.println("Upload completed!");
	}
}

public class UploadInterruptedHandler implements IUploadInterruptedHandler {
	@Override
	public void uploadInterrupted(CryptshareException cryptshareException) {
		// Diese Methode wird aufgerufen, wenn ein Fehler während des Uploads auftritt
		System.out.println("An exception occurred during the upload: " + cryptshareException);
	}
}

public class UploadCancelledHandler implements IUploadCancelledHandler {
	@Override
	public void cancelled() {
		// Diese Methode wird aufgerufen, wenn der Transfer
		// mittels cancelTransfer() abgebrochen wurde.
		System.out.println("The transfer has been canceled!");
	}
}

CSJCurrent de:Dateitransfer: Unterschied zwischen den Versionen