Kryptografische Funktionen in Jitterbit Studio

Kryptografische Funktionen werden verwendet, um grundlegende Verschlüsselung und Entschlüsselung mit Standard-Algorithmen und -Funktionen durchzuführen.

Um eine API-Anfragepayload mit einem gemeinsam genutzten Geheimnis mit HMAC-SHA256 zu signieren, siehe HMAC-SHA256-Signatur generieren.

Dateien mit Base64 lesen und schreiben

Die Base64-Funktionen können beim Lesen und Schreiben von Dateien in folgenden häufigen Szenarien verwendet werden:

Ein Szenario besteht darin, eine vorhandene Datei (z. B. ein PDF) mit der Funktion Base64EncodeFile zu lesen und den Inhalt dieser Datei dann in einen Endpunkt wie Salesforce zu schreiben.

Dazu erstellt man ein Skript, das die Datei aus einer Quelle liest und geeignete globale Variablen setzt. Anschließend würde man eine Transformation erstellen, die diese globalen Variablen verwendet und sie in einer Zuordnung zum Schreiben in Salesforce einsetzt:

// Read a PDF File
$docName = "Test.pdf";
$fileContents = Base64EncodeFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/FTP Files</TAG>", $docName);
$docLength = Length($fileContents);
$docType = "pdf";
$mimeType = "application/pdf";

Ein zweites Szenario besteht darin, aus einer Datei zu lesen, ihren Inhalt in eine Variable zu platzieren und dann die Funktion Base64Encode auf den Inhalt anzuwenden, bevor man diesen in einer neuen Textdatei speichert.

AESDecryption

Deklaration

string AESDecryption(string encryptedText, string passphrase[, string salt, int keyLength, int iterations])

Syntax

AESDecryption(<encryptedText>, <passphrase>[, <salt>, <keyLength>, <iterations>])

Erforderliche Parameter

• encryptedText: Ein Base64-codierter, AES-verschlüsselter Wert
• passphrase: Passwort, das zum Verschlüsseln der Zeichenkette mit der Funktion AESEncryption verwendet wird

Optionale Parameter

• salt: Hexadezimale String-Salt zum Verschlüsseln der Zeichenkette mit der Funktion AESEncryption
• keyLength: Schlüssellänge zum Verschlüsseln der Zeichenkette mit der Funktion AESEncryption
• iterations: Anzahl der Iterationen zum Verschlüsseln der Zeichenkette mit der Funktion AESEncryption

Beschreibung

Diese Funktion entschlüsselt eine Zeichenkette, die mit dem AES-Algorithmus der Funktion AESEncryption verschlüsselt wurde.

Die entschlüsselte Ausgabe wird als Zeichenkette zurückgegeben. Weitere Details finden Sie unter AESEncryption.

Informationen zur Fehlerbehebung finden Sie unter AESDecryption schlägt mit Daten fehl, die unter OpenSSL 3 verschlüsselt wurden im Leitfaden zur Fehlerbehebung bei Operationen.

Beispiele

// Encrypting a string
encrypted = AESEncryption("Hello world!", "password");
// Decrypted as "Hello world!"
decrypted = AESDecryption(encrypted, "password");

// Encrypting (and decrypting) a string using
// a passphrase and salt, 256-bit key, and 1024 iterations
encrypted = AESEncryption("Hello world!", "password", "00FFAE01", 256, 1024);
decrypted = AESDecryption(encrypted, "password", "00FFAE01", 256, 1024);

AESDecryptionEx

Deklaration

string AESDecryptionEx(string encryptedText, string key[, string iv, int keyLength>])

Syntax

AESDecryptionEx(<encryptedText>, <key>[, <iv>, <keyLength>])

Erforderliche Parameter

• encryptedText: Eine Base64-codierte, OpenSSL 3-unterstützte AES-verschlüsselte Zeichenkette
• key: Der Schlüssel, der zum Verschlüsseln von encryptedText verwendet wurde

Optionale Parameter

• iv: Der 16-Byte-Initialisierungsvektor (IV), der zum Verschlüsseln von encryptedText verwendet wurde
• keyLength: Die Schlüssellänge zum Verschlüsseln von encryptedText

Beschreibung

Diese Funktion entschlüsselt eine Zeichenkette, die mit einem AES-Algorithmus unter Verwendung von OpenSSL 3 verschlüsselt wurde. Dies umfasst Text, der außerhalb der Jitterbit Harmony-Plattform verschlüsselt wurde, und Text, der mit der Funktion AESEncryptionEx verschlüsselt wurde. Diese Funktion wird bei Verwendung von Agent-Versionen 11.42 oder später unterstützt.

Die entschlüsselte Ausgabe wird als String zurückgegeben. Siehe AESEncryptionEx für die Verschlüsselung.

Beispiele

// Encrypting (and decrypting) a string using a 128-bit key and 16-byte IV
encrypted = AESEncryptionEx("Hello world!", "123456ZYXWVUTSRQ", "12345XYZ12345XYZ", 128);
decrypted = AESDecryptionEx(encrypted, "123456ZYXWVUTSRQ", "12345XYZ12345XYZ", 128);

AESEncryption

Deklaration

string AESEncryption(string plainText, string passphrase[, string salt, int keyLength, int iterations])

Syntax

AESEncryption(<plainText>, <passphrase>[, <salt>, <keyLength>, <iterations>])

Erforderliche Parameter

• plainText: Ein String, der verschlüsselt werden soll
• passphrase: Passwort zum Verschlüsseln des Strings

Optionale Parameter

• salt: Hexadezimaler String Salt zur Verschlüsselung des Strings; falls angegeben, muss der Wert im Hexadezimalformat vorliegen (z. B. "A034DD")
• keyLength: Schlüssellänge zur Verschlüsselung des Strings, muss 128, 192 oder 256 sein; Standard ist 256
• iterations: Anzahl der Iterationen zum Generieren des Schlüssels; Standard ist 1

Beschreibung

Diese Funktion verschlüsselt einen String mit einem AES-Algorithmus, der mit der Funktion AESDecryption entschlüsselt werden kann. Der Schlüssel wird gemäß Password-Based Cryptography Specification Version 2.0 (PKCS5S2) generiert.

Die verschlüsselte Ausgabe ist ein Base64-codierter String. Die Ausgabe von AESEncryption kann direkt an die Funktion AESDecryption zur Entschlüsselung übergeben werden, wobei die gleichen Parameter wie bei der Verschlüsselung des Plaintexts verwendet werden.

Beispiele

// Encrypting a string
encrypted = AESEncryption("Hello world!", "password");
// Decrypted as "Hello world!"
decrypted = AESDecryption(encrypted, "password");

// Encrypting (and decrypting) a string using
// a passphrase and salt, 256-bit key, and 1024 iterations
encrypted = AESEncryption("Hello world!", "password", "00FFAE01", 256, 1024);
decrypted = AESDecryption(encrypted, "password", "00FFAE01", 256, 1024);

AESEncryptionEx

Deklaration

string AESEncryptionEx(string plainText, string key[, string iv, int keyLength])

Syntax

AESEncryptionEx(<plainText>, <key>[, <iv>, <keyLength>])

Erforderliche Parameter

• plainText: Der String, der verschlüsselt werden soll
• key: Der Schlüssel zur Verschlüsselung von plainText

Optionale Parameter

• iv: Der 16-Byte-Initialisierungsvektor (IV) zur Verschlüsselung von plainText; es wird ein Fehler geworfen, wenn der IV nicht 16 Bytes beträgt
• keyLength: Die Schlüssellänge zur Verschlüsselung von plainText, muss 128, 192 oder 256 sein; Standard ist 256

Beschreibung

Diese Funktion verschlüsselt einen String mit einem AES-Algorithmus mit OpenSSL 3. Diese Funktion wird unterstützt bei Verwendung von Agent-Versionen 11.42 oder später.

Die verschlüsselte Ausgabe ist ein OpenSSL 3-unterstützter, Base64-codierter String. Die Ausgabe von AESEncryptionEx kann direkt an die Funktion AESDecryptionEx oder außerhalb der Jitterbit Harmony-Plattform zur Entschlüsselung übergeben werden, wobei die gleichen Parameter wie bei der Verschlüsselung des Plaintexts verwendet werden.

Beispiele

// Encrypting (and decrypting) a string using a 128-bit key and 16-byte IV
encrypted = AESEncryptionEx("Hello world!", "123456ZYXWVUTSRQ", "12345XYZ12345XYZ", 128);
decrypted = AESDecryptionEx(encrypted, "123456ZYXWVUTSRQ", "12345XYZ12345XYZ", 128);

Base64Decode

Deklaration

binary Base64Decode(string encryptedText)

Syntax

Base64Decode(<encryptedText>)

Erforderliche Parameter

• encryptedText: Eine Base64-kodierte Zeichenkette

Beschreibung

Dekodiert eine Base64-kodierte Zeichenkette und gibt Binärdaten zurück. Siehe auch Base64Encode.

Beispiele

// Encrypting a string after first converting it to binary
binary = HexToBinary(StringToHex("Hello world!"));
encrypted = Base64Encode(binary);

decrypted = Base64Decode(encrypted);
result = HexToString(BinaryToHex(decrypted));
// Returns original string "Hello world!"

Base64Encode

Deklaration

string Base64Encode(type arg)

Syntax

Base64Encode(<arg>)

Erforderliche Parameter

• arg: Wert zur Kodierung

Beschreibung

Kodiert die Argumentdaten, wobei die Zeichen in einer Zeichenkette als Binärdaten behandelt werden, sofern die Eingabe nicht bereits binär ist. Falls der Argumenttyp nicht binär oder eine Zeichenkette ist, wird der Argumentwert zunächst in eine Zeichenkette konvertiert, bevor er verschlüsselt wird.

Nach jedem 64. Zeichen der kodierten Ergebniszeichenkette wird ein Zeilenumbruchzeichen (\n) hinzugefügt. Da viele Base64-Implementierungen Zeilenumbrüche enthalten, um die maximale Zeilenlänge des kodierten Ergebnisses zu begrenzen, sollte dies nur bei Bedarf explizit deaktiviert werden. Um dies zu deaktivieren, setzen Sie die Jitterbit-Variable jitterbit.base64.encoded.string.no.wrap auf true, bevor Sie diese Funktion aufrufen. Diese Variable wird bei Zeichenkettendaten mit Agenten der Version 10.49 und später und bei Binärdaten mit Agenten der Version 10.x 10.66 und später sowie 11.x 11.4 und später unterstützt.

Siehe auch Base64Decode.

Beispiele

// Encrypting a string after first converting it to binary
binary = HexToBinary(StringToHex("Hello world!"));
encrypted = Base64Encode(binary);

decrypted = Base64Decode(encrypted);
result = HexToString(BinaryToHex(decrypted));
// Returns original string "Hello world!"

encrypted = Base64Encode(Now());
decrypted = Base64Decode(encrypted);
result = HexToString(BinaryToHex(decrypted));
// Returns a date string such as "2017-12-14 01:25:31"

// Encrypting credentials for use in an HTTP header
Base64Encode("exampleuser"+":"+"examplepassword")

Base64EncodeFile

Deklaration

string Base64EncodeFile(string sourceId[, string filename])

Syntax

Base64EncodeFile(<sourceId>[, <filename>])

Erforderliche Parameter

• sourceId: Ein Zeichenketten-Referenzpfad zu einer Aktivität, die einem dateityp-basierten Endpunkt im aktuellen Projekt zugeordnet ist und eine Binärdatei zurückgibt. Wenn ein Array von Dateinamen zurückgegeben wird, wird der erste verwendet.

Optionale Parameter

• filename: Ein Dateiname als Zeichenkette, der den von der Quelle sourceId zurückgegebenen Wert überschreibt

Beschreibung

Liest eine Binärdatei aus der angegebenen Quellenaktivität und gibt den Inhalt als Base64-kodierte Zeichenkette zurück. Diese Methode wird in der Regel für Dateien verwendet, die binär sein könnten. Zum Lesen einer Textdatei verwenden Sie stattdessen die Funktion ReadFile.

Die in dieser Funktion verwendete Quelle muss als Aktivität definiert sein, die einem dateityp-basierten Endpunkt im aktuellen Projekt zugeordnet ist. Dazu gehören konfigurierte Aktivitäten für Dateifreigabe, FTP, HTTP, Lokale Speicherung und Temporäre Speicherung. Weitere Informationen finden Sie in den Anweisungen zum Einfügen von Endpunkten im Abschnitt Endpunkte in Jitterbit Script.

Diese Methode gibt den Inhalt der Datei zurück, auf die die angegebene Quelle verweist. Falls die Quellenfilter mehrere Dateien auswählen, wird die erste verwendet. Es wird empfohlen, eine Quelle anzugeben, die eine einzelne Datei eindeutig identifiziert.

Der zweite Parameter, filename, ist optional und kann verwendet werden, um den in der Aktivitätskonfiguration zurückgegebenen Dateinamen zu überschreiben. Alternativ kann eine globale Variable verwendet werden, um den Dateinamen in der Aktivitätskonfiguration zu überschreiben. Globale Variablen werden in der Aktivitätskonfiguration als [de_name] referenziert.

Wenn eine Datei nicht gefunden wird, wird ein Fehler ausgelöst.

Nach jedem 64. Zeichen der codierten Ergebniszeichenfolge wird ein Zeilenumbruchzeichen (\n) eingefügt. Da viele Base64-Implementierungen Zeilenumbrüche enthalten, um die maximale Zeilenlänge des codierten Ergebnisses zu begrenzen, sollte dies nur bei Bedarf explizit deaktiviert werden. Um dies zu deaktivieren, setzen Sie die Jitterbit-Variable jitterbit.base64.encoded.string.no.wrap auf true, bevor Sie diese Funktion aufrufen. Diese Variable wird mit Zeichenfolgendaten bei Verwendung von Agenten ab Version 10.49 und mit Binärdaten bei Verwendung von Agenten ab Version 10.66 und später sowie 11.x Agenten ab Version 11.4 und später unterstützt.

Siehe auch Base64Decode.

Beispiele

// Reads the first file found at the source
// "FTP Files" and returns it as a Base64-encoded string
fileContents1 = Base64EncodeFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/FTP Files</TAG>");

// Reads the binary file called
// "requirements.doc" from the FTP directory
// defined by the source "FTP Files"
fileContents2 = Base64EncodeFile("<TAG>activity:ftp/FTP Endpoint/ftp_read/FTP Files</TAG>", "requirements.doc");

// Decodes the file contents; they can now be
// re-written as a binary file to another target
fileContents2Decoded = Base64Decode(fileContents2);

MD5

Deklaration

string MD5(type arg)

Syntax

MD5(<arg>)

Erforderliche Parameter

• arg: Wert, der gehasht werden soll

Beschreibung

Wendet die MD5-Hash-Funktion auf das angegebene Argument an. Der Hash wird als Zeichenfolge von 32 Hexadezimalziffern zurückgegeben. Nicht-String-Daten werden zunächst in eine Zeichenfolge konvertiert.

Beispiele

MD5("hello world!");
// Returns "fc3ff98e8c6a0d3087d515c0473f8677"

MD5AsTwoNumbers

Deklaration

array MD5AsTwoNumbers(type arg)

Syntax

MD5AsTwoNumbers(<arg>)

Erforderliche Parameter

• arg: Wert, der gehasht werden soll

Beschreibung

Wendet die MD5-Hash-Funktion auf eine Eingabezeichenfolge an und gibt das Ergebnis als Array mit zwei 64-Bit-Zahlen zurück. Nicht-String-Daten werden zunächst in eine Zeichenfolge konvertiert.

Beispiele

MD5AsTwoNumbers("hello world!");
// Returns "{8612640914790536583, 3462540840444444668}"

SHA256

Deklaration

string SHA256(type arg)

Syntax

SHA256(<arg>)

Erforderliche Parameter

• arg: Wert, der gehasht werden soll

Beschreibung

Wendet die SHA-256-Hash-Funktion auf eine Eingabezeichenfolge an. Der zurückgegebene Hash ist eine Zeichenfolge von 64 Hexadezimalziffern.

Wenn die Eingabe eine Zeichenfolge ist, wird sie zunächst in die UTF-8-Byte-Darstellung konvertiert. Nicht-String-Daten werden zunächst in eine Zeichenfolge konvertiert.

Beispiele

SHA256("hello world!");
// Returns "7509e5bda0c762d2bac7f90d758b5b2263fa01ccbc542ab5e3df163be08e6ca9"

SHA512

Deklaration

string SHA512(type arg)

Syntax

SHA512(<arg>)

Erforderliche Parameter

• arg: Der zu hashende Wert

Beschreibung

Wendet die SHA-512-Hashfunktion auf eine Eingabezeichenkette an. Der zurückgegebene Hash ist eine Zeichenkette aus 128 Hexadezimalziffern. Diese Funktion wird ab Agent-Version 12.9 oder später unterstützt.

Wenn die Eingabe eine Zeichenkette ist, wird sie zuerst in die UTF-8-Bytedarstellung konvertiert. Nicht-String-Daten werden zuerst in eine Zeichenkette konvertiert.

Beispiele

SHA512("hello world!");
// Returns "db9b1cd3262dee37756a09b9064973589847caa8e53d31a9d142ea2701b1b28abd97838bb9a27068ba305dc8d04a45a1fcf079de54d607666996b3cc54f6b67c"