CSJCurrent de:QUICK Transfer versenden

Aus Cryptshare Documentation
Wechseln zu:Navigation, Suche


Einleitung

Allgemeine Informationen zu QUICK Technology
Für allgemeine Informationen zur Funktionsweise von QUICK Technology und für ein besseres Verständnis über die genutzte Terminologie empfehlen wir Ihnen den Artikel Einleitung zu QUICK.

In diesem Artikel erfahren Sie, wie Sie mithilfe der Cryptshare Java API einen mit QUICK gesicherten Transfer versenden. Alternativ können Sie im Abschnitt Zusammenfassung sofort den gesamten Quelltext betrachten.

Implementierung

Nachfolgend werden wir Schritt für Schritt den Code zusammenstellen, der für einen erfolgreichen, mit QUICK gesicherten Transfer benötigt wird.

Vorbereiten des Programms

Wir bereiten eine einfache Konsolenanwendung vor und definieren im Voraus Informationen, die im Laufe des Programms benötigt werden. Stellen Sie sicher das das Java API Package verfügbar ist, z.B. indem sie die Jar in das Maven Repository importieren. 

import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Scanner;
 
class Program {
    private static final String senderEmailAddress = "john.doe@example.com";
    private static final String senderName = "John Doe";
    private static final String senderPhoneNumber = "+49 (0) 1234 56789";
    private static final String serverUrl = "https://cryptshare.example.com";
    // New "client.store" file will be created if it doesn't already exist.
    private static final Path clientStoreLocation = Paths.get("C:\\\\temp");
    private static final String recipientEmailAddress = "jane.doe@example.com";
    private static final Path filePath = Paths.get("C:\\\\temp\\\\pdf-sample.pdf");
 
    public static void main(String[] args) {
        try {
            // All following code snippets are to be inserted here.
        } catch (Exception e) {
            System.err.println("An error has occurred: ");
            e.printStackTrace();
        } finally {
            System.out.println("Press any key to terminate the program.");
            new Scanner(System.in).next();
        }
    }
}

Erzeugen der `Client`-Instanz

Wie auch für reguläre Transfers ist es notwendig, eine Client-Instanz zu erzeugen, die den Absender des Transfers darstellt. Die hierfür benötigten Informationen sind:

  • E-Mail-Adresse des Absenders
  • URL des Cryptshare Servers
  • Pfad zum Ablegen des Verifizierungsspeichers
Client client = new Client(
    senderEmailAddress,
    new CryptshareConnection(new WebServiceUri(serverUrl)),
    clientStoreLocation
);

Erzeugen und Vorbereiten der Transfer-Instanz

Die Informationen über den Transfer sind, wie auch die oben beschriebenen Informationen über den Absender, integraler Bestandteil eines Cryptshare-Transfers. 

Transfer transfer = new Transfer();

Für einen erfolgreichen Transfer werden mindestens folgende Angaben benötigt:

  • Name des Absenders
transfer.setSenderName(senderName)
  • Telefonnummer des Absenders
transfer.setSenderPhone(senderPhoneNumber);
  • Mindestens ein Empfänger (der zweite Parameter definiert, ob für diesen Empfänger der Transfer mit QUICK gesichert werden soll)
// Activate QUICK for the given recipient.
transfer.addRecipient(new Recipient(recipientEmailAddress, true));
  • Der zu verwendende Passwortmodus
transfer.setPasswordMode(PasswordMode.MANUAL);
  • Mindestens eine zu versendende Datei
    • Bitte beachten Sie, dass immer eine Datei angegeben werden muss, auch wenn Sie nur eine vertrauliche Nachricht versenden möchten. Das Versenden von vertraulichen Nachrichten ohne Dateianhänge ist für eine spätere Version geplant.
transfer.addFile(new TransferFile(filePath));
  • Optional: Angabe, ob der Cryptshare Server den E-Mail Versand zum Benachrichtigen des Absenders und Empfängers übernehmen soll.
transfer.setSendMails(true);
transfer.setNotifySender(true);
transfer.setNotifyRecipients(true);
transfer.setInformAboutDownload(true);
  • Ablaufdatum des Transfers. Hinweis: Da wir zum Setzen des Ablaufdatums auf eine Policy-Abfrage angewiesen sind, ist für diesen Abschnitt eine gültige Verifizierung notwendig. Daher sollte die maximale Liegezeit erst dann abgefragt werden, wenn sichergestellt wurde, dass eine gültige Verifizierung vorhanden ist. Bitte beachten Sie die Reihenfolge der Aufrufe im Abschnitt Zusammenfassung.
// Query the maximum possible storage duration for the given sender-recipient policy.
Policy policy = client.requestPolicy(transfer.getRecipients().stream().map(Recipient::getEmailAddress).collect(Collectors.toList()));
final ZoneId serverTimezone = ZoneOffset.UTC; // Replace this with the timezone the Cryptshare server uses.
final ZonedDateTime expirationDate = ZonedDateTime.now(serverTimezone).plusDays(policy.getStorageDuration());
transfer.setExpirationDate(expirationDate.toLocalDate());

Weitere Voraussetzungen für einen erfolgreichen Transfer

Sowohl unsere Client- als auch Transfer-Instanzen erfüllen die Voraussetzungen für einen Transfer. Allerdings müssen weitere vom Cryptshare Server auferlegte Voraussetzungen beachtet und behandelt werden. Im Einzelnen wird vorausgesetzt, dass:

  • die Absender-E-Mail-Adresse verifiziert ist.
CheckVerificationResult checkVerificationResult = client.checkVerification();
if (!checkVerificationResult.isUserVerified()) {
    switch (checkVerificationResult.getVerificationMode()) {
        case SENDER:
            System.out.printf("Requesting a verification code for %s...%n", client.getUserEmailAddress());
            client.requestSenderVerification();
            System.out.println("Please enter the code below and confirm with [Enter]:");
            String code = new Scanner(System.in).next().trim();
            client.confirmSenderVerification(code);
            break;
        case CLIENT:
            if (checkVerificationResult.isClientVerificationAllowed()) {
                client.requestClientVerification();
            } else {
                throw new IllegalStateException(
                        "Your client ID is not whitelisted. Please whitelist the following client ID before proceeding: "
                                + client.getClientId());
            }
            break;
        default:
            break;
    }
}
  • keine Aktivierung von QUICK notwendig ist - eine Aktivierung ist z.B. dann notwendig, wenn für die angegebene Absender-E-Mail-Adresse bereits ein QUICK-Zugang auf dem Server existiert, falls QUICK bspw. zuvor auf einem anderen Gerät genutzt wurde.
    • Falls ja, wird der eigene QUICK-Zugang zurückgesetzt.
    • Hinweis: Setzen Sie den QUICK-Zugang nur dann zurück, wenn Sie sich den Konsequenzen bewusst sind. Grundsätzlich kann ein existierender QUICK Zugang auch programmatisch aktiviert werden. Dieser Vorgang ist in folgendem Artikel beschrieben.
if (checkVerificationResult.isActivationRequired()) {
    // WARNING: Only reset the QUICK state if you are aware of the consequences. When in doubt, please
    // consult the Wiki article about QUICK Technology: http://cryptshare.click/webapp-quick-activation-en
    client.resetQuickState();
}
  • die bestehende Verifizierung für die Nutzung von QUICK zugelassen ist.
if (!checkVerificationResult.isQuickEnabled()) {
    client.enableVerificationForQuick();
}
  • ein Passwort gesetzt wird, wenn mindestens ein Empfänger existiert, zu welchem noch keine QUICK-Verbindung besteht.
    • Für diesen Empfänger fungiert der Transfer gleichzeitig als Einladung für den Aufbau einer QUICK-Verbindung.
{
    // ...
        List<String> recipients = transfer.getRecipients().stream().map(Recipient::getEmailAddress).collect(Collectors.toList());
        Map<String, QuickConnectionState> quickConnectionStates = client.requestQuickConnectionStates(recipients);
        if (!isPureQuickTransfer(quickConnectionStates)) {
            // Not a pure QUICK transfer, password needs to be set.
            System.out.println("Not a pure QUICK transfer; generating a one-time-password... ");
            PasswordPolicy passwordPolicy = client.requestPasswordPolicy();
            transfer.setPassword(client.requestGeneratedPassword(passwordPolicy.getMinimumLength()));
            System.out.println(transfer.getPassword());
        }
    // ...
}
 
private static boolean isPureQuickTransfer(Map<String, QuickConnectionState> quickConnectionStates) {
    return quickConnectionStates.values()
            .stream()
            .allMatch(quickConnectionState -> quickConnectionState == QuickConnectionState.ESTABLISHED);
}

Wenn diese Voraussetzungen berücksichtigt werden, steht dem Transfer nichts mehr im Wege. 

{
    // ...
        client.performTransfer(transfer, null, Program::handleUploadComplete, null, null, 1000);
    // ...
}
 
private static void handleUploadComplete(Map<String, String> urlMappings, Map<String, String> smtpMappings, String serverGenPassword,
        TransferError transferError, String trackingId) {
    System.out.println("URL mappings:");
    urlMappings.forEach((key, value) -> System.out.printf("%s: %s%n", key, value));
    System.out.println("SMTP mappings:");
    smtpMappings.forEach((key, value) -> System.out.printf("%s: %s%n", key, value));
    System.out.printf("Tracking ID: %s%n", trackingId);
}

Zusammenfassung

Wenn Sie alle Punkte der Reihe nach berücksichtigt haben, sollte Ihr Programm wie nachfolgend abgebildet aussehen: 

import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Scanner;
 
class Program {
    private static final String senderEmailAddress = "john.doe@example.com";
    private static final String senderName = "John Doe";
    private static final String senderPhoneNumber = "+49 (0) 1234 56789";
    private static final String serverUrl = "https://cryptshare.example.com";
    // New "client.store" file will be created if it doesn't already exist.
    private static final Path clientStoreLocation = Paths.get("C:\\\\temp");
    private static final String recipientEmailAddress = "jane.doe@example.com";
    private static final Path filePath = Paths.get("C:\\\\temp\\\\pdf-sample.pdf");
 
    public static void main(String[] args) {
        try {
            // All following code snippets are to be inserted here.
            Client client = new Client(senderEmailAddress, new CryptshareConnection(new WebServiceUri(serverUrl)), clientStoreLocation);
 
            Transfer transfer = new Transfer();
            transfer.setSenderName(senderName);
            transfer.setSenderPhone(senderPhoneNumber);
            // Activate QUICK for the given recipient.
            transfer.addRecipient(new Recipient(recipientEmailAddress, true));
            transfer.setPasswordMode(PasswordMode.MANUAL);
            transfer.addFile(new TransferFile(filePath));
            transfer.setSendMails(true);
            transfer.setNotifySender(true);
            transfer.setNotifyRecipients(true);
            transfer.setInformAboutDownload(true);
 
            // Query the maximum possible storage duration for the given sender-recipient policy.
            Policy policy = client.requestPolicy(transfer.getRecipients().stream().map(Recipient::getEmailAddress).collect(Collectors.toList()));
            final ZoneId serverTimezone = ZoneOffset.UTC; // Replace this with the timezone the Cryptshare server uses.
            final ZonedDateTime expirationDate = ZonedDateTime.now(serverTimezone).plusDays(policy.getStorageDuration());
            transfer.setExpirationDate(expirationDate.toLocalDate());
 
            CheckVerificationResult checkVerificationResult = client.checkVerification();
            if (!checkVerificationResult.isUserVerified()) {
                switch (checkVerificationResult.getVerificationMode()) {
                    case SENDER:
                        System.out.printf("Requesting a verification code for %s...%n", client.getUserEmailAddress());
                        client.requestSenderVerification();
                        System.out.println("Please enter the code below and confirm with [Enter]:");
                        String code = new Scanner(System.in).next().trim();
                        client.confirmSenderVerification(code);
                        break;
                    case CLIENT:
                        if (checkVerificationResult.isClientVerificationAllowed()) {
                            client.requestClientVerification();
                        } else {
                            throw new IllegalStateException(
                                    "Your client ID is not whitelisted. Please whitelist the following client ID before proceeding: "
                                            + client.getClientId());
                        }
                        break;
                    default:
                        break;
                }
            }
 
            if (checkVerificationResult.isActivationRequired()) {
                // WARNING: Only reset the QUICK state if you are aware of the consequences. When in doubt, please
                // consult the Wiki article about QUICK Technology: http://cryptshare.click/webapp-quick-activation-en
                client.resetQuickState();
            }
            if (!checkVerificationResult.isQuickEnabled()) {
                client.enableVerificationForQuick();
            }
 
            List<String> recipients = transfer.getRecipients().stream().map(Recipient::getEmailAddress).collect(Collectors.toList());
            Map<String, QuickConnectionState> quickConnectionStates = client.requestQuickConnectionStates(recipients);
            if (!isPureQuickTransfer(quickConnectionStates)) {
                // Not a pure QUICK transfer, password needs to be set.
                System.out.println("Not a pure QUICK transfer; generating a one-time-password... ");
                PasswordPolicy passwordPolicy = client.requestPasswordPolicy();
                transfer.setPassword(client.requestGeneratedPassword(passwordPolicy.getMinimumLength()));
                System.out.println(transfer.getPassword());
            }
 
            client.performTransfer(transfer, null, Program::handleUploadComplete, null, null, 1000);
         
        } catch (Exception e) {
            System.err.println("An error has occurred: ");
            e.printStackTrace();
        } finally {
            System.out.println("Press any key to terminate the program.");
            new Scanner(System.in).next();
        }
    }
 
    private static void handleUploadComplete(Map<String, String> urlMappings, Map<String, String> smtpMappings, String serverGenPassword,
            TransferError transferError, String trackingId) {
        System.out.println("URL mappings:");
        urlMappings.forEach((key, value) -> System.out.printf("%s: %s%n", key, value));
        System.out.println("SMTP mappings:");
        smtpMappings.forEach((key, value) -> System.out.printf("%s: %s%n", key, value));
        System.out.printf("Tracking ID: %s%n", trackingId);
    }
 
    private static boolean isPureQuickTransfer(Map<String, QuickConnectionState> quickConnectionStates) {
        return quickConnectionStates.values()
                .stream()
                .allMatch(quickConnectionState -> quickConnectionState == QuickConnectionState.ESTABLISHED);
    }
}
Abgerufen von „https://documentation.cryptshare.com/w/index.php?title=CSJCurrent_de:QUICK_Transfer_versenden&oldid=29075“