CSJCurrent de:Dateitransfer: Unterschied zwischen den Versionen

Aus Cryptshare Documentation
Wechseln zu:Navigation, Suche
(Imported from text file)
 
Keine Bearbeitungszusammenfassung
 
(4 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
 
-----
= Allgemeines =
= 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.
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 '[[#Dateitransfer-Transfervorbereiten|Transfer vorbereiten]]' beschrieben, vorbereitet werden. Anschließend kann der Transfer entweder [[#Dateitransfer-Synchron|synchron]] oder [[#Dateitransfer-Asynchron|asynchron]] durchgeführt werden.
Bevor ein Transfer durchgeführt werden kann, muss dieser, wie im Kapitel '[[#Transfer_vorbereiten|Transfer vorbereiten]]' beschrieben, vorbereitet werden. Anschließend kann der Transfer entweder [[#Synchron|synchron]] oder [[#Asynchron|asynchron]] durchgeführt werden.


= Transfer vorbereiten =
= Transfer vorbereiten =
Zeile 13: Zeile 9:
** Name
** Name
** Telefonnummer
** Telefonnummer
* Das zu verwendende [https://wiki.cryptshare.com/display/CSH/Passwortsicherheit Passwortverfahren] (optional)
* Das zu verwendende [[CSSCurrent_de:Passwortsicherheit|Passwortsicherheit]] (optional)
* Der Nachrichtentext für die Absenderbenachrichtigung (optional)
* Der Nachrichtentext für die Absenderbenachrichtigung (optional)
* Die Empfänger-E-Mail-Adressen
* Die Empfänger-E-Mail-Adressen
Zeile 44: Zeile 40:
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.
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'''
=== Cryptshare Transfer vorbereiten ===
// First create the Client instance
// Create a WebServiceUri for your Cryptshare Server
WebServiceUri serviceUri = new WebServiceUri("<nowiki>https://cryptshare.yourdomain.com</nowiki>");
   
   
  // URL zum Cryptshare Server
  // Create a CryptshareConnection instance for your WebServiceUri
  WebServiceUri uri = new WebServiceUri("https://cryptshare.yourdomain.com");
  CryptshareConnection connection = new CryptshareConnection(serviceUri);
   
   
  // Verbindungsinstanz zum Cryptshare Server
  // Create the Client instance with the sender's email address,
  CryptshareConnection connection = new CryptshareConnection(uri);
  // the CryptshareConnection, and the path to the verification store.
Client client = new Client("john.adams@yourdomain.com", connection, Paths.get("C:\\temp\\client.store"));
   
   
  // Client für das Absenden der Requests
  // Create a new Transfer object
Client client = new Client("john.adams@yourdomain.com", connection, Paths.get("C:\\\\temp\\\\client.store"));
// Erzeugen eine Transfer Instanz
  Transfer transfer = new Transfer();
  Transfer transfer = new Transfer();
   
   
  // Festlegen des Absendernamens
  // Set the name of the sender
  transfer.setSenderName("John Adams");
  transfer.setSenderName("John Adams");
   
   
  // Festlegen der Absender-Telefonnummer
  // Set the sender's phone number
  transfer.setSenderPhone("234 5467");
  transfer.setSenderPhone("234 5467");
   
   
  /**
  // Set the message text of the mail that is to be included in the transfer.
  * Festlegen des Benachrichtigungstextes für die Empfängerbenachrichtigung.
// The Transfer object's setMessage(..) method takes either an
  * Der Text kann direkt als UTF-8-codierter InputStream übergeben werden.
// actual text string containing the email message, or an InputStream
  **/
// which contains the email message text. If specifying an InputStream, the
  try (FileInputStream inputStream = new FileInputStream("C:\\\\temp\\\\message.txt")) {
// stream needs to be UTF-8 encoded, to ensure that the characters can be
    // Nachricht wird als InputStream übergeben. Der Stream wird automatisch
// read in and displayed correctly in the email message.
    // geschlossen.
  try (FileInputStream inputStream = new FileInputStream("C:\\temp\\message.txt")) {
    transfer.setMessage(inputStream);
// 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) {
  } catch (Exception ex) {
    // Anzeigen einer Fehlernachricht bei Auftreten eines Fehlers
// there was an error reading the text file, so show an error message
    System.err.println("Der Nachrichteninhalt konnte nicht gelesen werden!");
System.err.println("Error reading the message file!");
  }
  }
   
   
  // Festlegen des Betreffs für die Empfängerbenachrichtigung
  // Set the subject text of the mail that is to be included in the transfer.
  transfer.setSubject("Betreff für diesen Transfer");
  transfer.setSubject("Subject of the Transfer");
   
   
  // Festlegen der Empfänger
  // Define the recipients
  List<String> recipients = new ArrayList<>();
  List<String> recipients = new ArrayList<String>();
  recipients.add("jane.doe@abc.com");
  recipients.add("jane.doe@abc.com");
  recipients.add("jack.smith@xyz.com");
  recipients.add("jack.smith@xyz.com");
   
   
  // Abrufen der Policy für diese Absender/Empfänger-Kombination,
  // Get the policy rule from the server for the given recipients, so we can
  // um sicherzustellen, dass diese auch zugelassen sind.
  // check to make sure they are allowed
  Policy policy = client.requestPolicy(recipients);
  Policy policy = client.requestPolicy(recipients);
   
   
  // Nur zulässige Empfänger zum Transfer hinzufügen
  // 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()) {
  if (policy.getFailedEmailAddresses() != null && !policy.getFailedEmailAddresses().isEmpty()) {
    for (String recipient : recipients) {
for (String recipient : recipients) {
      if (!policy.getFailedEmailAddresses().contains(recipient)) {
if (!policy.getFailedEmailAddresses().contains(recipient)) {
          transfer.addRecipient(new Recipient(recipient));
transfer.addRecipient(new Recipient(recipient));
      } else {
} else {
          System.out.println("Der Empfänger ist unzulässig: " + recipient);
System.out.println("The recipient is invalid: " + recipient);
      }
}
    }
}
  } else {
  } else {
    // Alle Empfänger sind zugelassen.
// all recipients are valid
    List<Recipient> recipientList = recipients.stream().map(Recipient::new).collect(Collectors.toList());  
List<Recipient> recipientList = recipients.stream().map(Recipient::new).collect(Collectors.toList());
    transfer.addRecipients(recipientList);
transfer.addRecipients(recipientList);
  }
  }
   
   
  // Sofern durch die Policy erlaubt, senden wir außerdem eine Vertrauliche
  // If allowed by the policy, we can also send a confidential message to the
  // Nachricht
  // recipients
  if (policy.isAllowConfidentialMessage()) {
  if (policy.isAllowConfidentialMessage()) {
    transfer.setConfidentialSubject("Betreff der vertraulichen Nachricht");
transfer.setConfidentialSubject("Subject of the confidential message");
    transfer.setConfidentialMessage("Vertraulicher Nachrichtentext");
transfer.setConfidentialMessage("This is the text of the confidential message.");
  }
  }
   
   
  // Fahre nur dann fort, wenn mindestens ein gültiger Empfänger vorhanden ist
  // Only continue if we have at least one valid recipient for the transfer
  if (transfer.getRecipients() == null {{!}}{{!}} transfer.getRecipients().isEmpty())
  if (transfer.getRecipients() == null || transfer.getRecipients().isEmpty()) {
    throw new IllegalStateException("Keine gültigen Empfänger gefunden. Der Transfer wird abgebrochen.");
throw new Exception("No valid recipients defined, aborting transfer.");
}
   
   
  // Festlegen des Passwortverfahrens. In diesem Falle wird der als am
  // Set the password mode that will be used for this transfer.
  // sichersten geltende Modus verwendet.
  // 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;
  PasswordMode passwordMode;
  Set<PasswordMode> allowedPasswordModes = policy.getAllowedStandardPasswordModes();
  Set<PasswordMode> allowedPasswordModes = policy.getAllowedStandardPasswordModes();
  if (allowedPasswordModes.contains(PasswordMode.GENERATED))
  if (allowedPasswordModes.contains(PasswordMode.GENERATED)) {
    passwordMode = PasswordMode.GENERATED;
passwordMode = PasswordMode.GENERATED;
  else if (allowedPasswordModes.contains(PasswordMode.MANUAL))
  } else if (allowedPasswordModes.contains(PasswordMode.MANUAL)) {
    passwordMode = PasswordMode.MANUAL;
passwordMode = PasswordMode.MANUAL;
  else
  } else {
    passwordMode = PasswordMode.NONE;
passwordMode = PasswordMode.NONE;
}
  transfer.setPasswordMode(passwordMode);
  transfer.setPasswordMode(passwordMode);
   
   
  // Für den manuellen Passwortmodus muss ein Passwort angegeben werden.
  // If password mode is MANUAL, we have to set a password
  if (passwordMode.equals(PasswordMode.MANUAL)) {
  if (passwordMode.equals(PasswordMode.MANUAL)) {
    // Angeben eines manuellen Passwortes
// we have to manually set a password for this transfer
    transfer.setPassword("p4$$w0rd");
transfer.setPassword("p4$$w0rd");
  }
  }
   
   
  // Dateinamen sollen in E-Mail-Benachrichtigungen erwähnt werden
  // Define if the file names should be shown in the recipient's
// notification email
  transfer.setShowFilenames(true);
  transfer.setShowFilenames(true);
   
   
  // Der Empfänger soll benachrichtigt werden, wenn Dateien heruntergeladen
  // Define if the sender should be notified when the recipients
  // werden.
  // download the files
  transfer.setInformAboutDownload(true);
  transfer.setInformAboutDownload(true);
   
   
  // Die Empfängerbenachrichtigung soll auf Englisch versendet werden.
  // Set the language for the recipient notification email
  transfer.setRecipientLanguage(Locale.ENGLISH);
  transfer.setRecipientLanguage(Locale.ENGLISH);
   
   
  // Die Absenderbenachrichtigung soll auf Englisch versendet werden.
  // Set the language for the sender notification email
  client.setUserLanguage(Locale.ENGLISH);
  client.setUserLanguage(Locale.ENGLISH);
   
   
  // Festlegen des Datums, an dem der Transfer abläuft.
  // Set the expiration date of the files
  // In diesem Falle wird das erlaubte Maximum verwendet.
  // (how long the files will be available for download)
// We'll just set it to the maximum allowed storage duration
  int storageDuration = policy.getStorageDuration();
  int storageDuration = policy.getStorageDuration();
  Calendar cal = Calendar.getInstance();
  Calendar cal = Calendar.getInstance();
Zeile 155: Zeile 162:
  transfer.setExpirationDate(cal.getTime().toInstant().atZone(ZoneId.systemDefault()).toLocalDate());
  transfer.setExpirationDate(cal.getTime().toInstant().atZone(ZoneId.systemDefault()).toLocalDate());
   
   
  // Hinzufügen der Dateien zum Transfer. Für jede Datei muss eine TransferFile-Instanz
  // Add the files for this transfer
  // erzeugt werden.
// A TransferFile object has to be created for each file you would like to add to the transfer
  transfer.addFile(new TransferFile(Paths.get("C:\\\\temp\\\\transfer_file_01.txt")));
  // 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")));
   
   
  // Hinzufügen einer Datei als Stream, der von einer anderen Anwendung kommen kann.
  // Add a stream that contains the data for a file.
  // In diesem Falle wird der Stream aus einer vorhandenen Datei erzeugt.
// 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 {
  try {
    File inputFile = new File("C:\\\\temp\\\\transfer_file_02.txt");
File inputFile = new File("C:\\temp\\transfer_file_02.txt");
    FileInputStream inputStream = new FileInputStream(inputFile);
FileInputStream inputStream = new FileInputStream(inputFile);
    long streamSize = inputFile.length();
long streamSize = inputFile.length();
   
   
    // Erzeugen der TransferFile-Instanz mit Dateiname und Dateigröße
// Create the TransferFile object for this stream. You also need to specify
    TransferFile streamFile = new TransferFile("MyAttachment.txt", inputStream, streamSize);
// a name for the file that will be created from the data of this stream, including
    transfer.addFile(streamFile);
// 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) {
  } catch (Exception ex) {
    ex.printStackTrace();
ex.printStackTrace();
  }
  }
  // Hinzufügen einer weiteren Datei.
  // Add another file from the file system
  transfer.addFile(new TransferFile(Paths.get("C:\\\\temp\\\\transfer_file_03.txt")));
  transfer.addFile(new TransferFile(Paths.get("C:\\temp\\transfer_file_03.txt")));
   
   
  /**
  // Now we can use this transfer object to perform the transfer
  * Nun ist das Transfer-Objekt für den synchronen oder asynchronen Versand
// either synchronously or asynchronously
   * vorbereitet.
   ...
  **/
 
-----
-----
= Transfer durchführen =
= Transfer durchführen =
Zeile 189: Zeile 200:
Da dies eine synchrone Operation ist, wird die Methode so lange 'blockieren', bis alle Dateien hochgeladen und der Transfer abgeschlossen ist.
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'''
=== Durchführen eines synchronen Transfers ===
  private static void performTransferSynchronous() {
private static void performTransferSynchronous() {
  // First create the Client instance
// Schritt 1: Erzeugen einer Client-Instanz
  // Create a WebServiceUri for your Cryptshare Server
  WebServiceUri serviceUri = new WebServiceUri("<nowiki>https://cryptshare.server.com</nowiki>");
 
  // 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!");
  }
  }
    
    
// Anlegen der URL zu Ihrem Cryptshare Server
  public class UploadInterruptedHandler implements IUploadInterruptedHandler {
WebServiceUri serviceUri = new WebServiceUri("https://cryptshare.server.com");
  @Override
     
  public void uploadInterrupted(CryptshareException cryptshareException) {
// Erzeugen der Verbindung zum Cryptshare Server
  // this method is called when an exception occurs during the file upload
CryptshareConnection connection = new CryptshareConnection(serviceUri);
      System.out.println("An exception occurred during the upload: " + cryptshareException);
     
  }
// 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.
  public class UploadCancelledHandler implements IUploadCancelledHandler {
// Die Methode blockiert so lange, bis der Transfer abgeschlossen ist.
  @Override
client.performTransfer(transfer,
  public void cancelled() {
  new UploadProgressChangedHandler(),
  // this method is called when the transfer has been cancelled
  new UploadCompleteHandler(),
  // using the cancelTransfer() method
  new UploadInterruptedHandler(),
  System.out.println("The transfer has been canceled!");
  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 ==
== Asynchron ==
Zeile 261: Zeile 270:
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".
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'''
=== Durchführen eines asynchronen Transfers ===
  private static void performTransferSynchronous() {
private static void performTransferSynchronous() {
  // First create the Client instance
// Schritt 1: Erzeugen einer Client-Instanz
  // Create a WebServiceUri for your Cryptshare Server
  WebServiceUri serviceUri = new WebServiceUri("<nowiki>https://cryptshare.server.com</nowiki>");
 
  // 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!");
  }
  }
    
    
// Anlegen der URL zu Ihrem Cryptshare Server
  public class UploadInterruptedHandler implements IUploadInterruptedHandler {
WebServiceUri serviceUri = new WebServiceUri("https://cryptshare.server.com");
  @Override
     
  public void uploadInterrupted(CryptshareException cryptshareException) {
// Erzeugen der Verbindung zum Cryptshare Server
  // this method is called when an exception occurs during the file upload
CryptshareConnection connection = new CryptshareConnection(serviceUri);
      System.out.println("An exception occurred during the upload: " + cryptshareException);
     
  }
// 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.
  public class UploadCancelledHandler implements IUploadCancelledHandler {
// Die Methode wird unmittelbar nach Aufruf beendet.
  @Override
client.beginTransfer(transfer,
  public void cancelled() {
  new UploadProgressChangedHandler(),
  // this method is called when the transfer has been cancelled
  new UploadCompleteHandler(),
  // using the cancelTransfer() method
  new UploadInterruptedHandler(),
  System.out.println("The transfer has been canceled!");
  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!");
}
}
 
-----

Aktuelle Version vom 3. Januar 2023, 08:28 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 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!");
 	}
 }