JavaScript-Bibliothek common/pgp

Diese JavaScript-Bibliothek bietet Funktionen zum Ver- und Entschlüsseln von Dateien mithilfe von PGP (Pretty Good Privacy). Außerdem können verschlüsselte E-Mails entschlüsselt werden.

Verwendung

Die Bibliothek ermöglicht die Arbeit mit öffentlichen und privaten PGP-Schlüsseln. Mithilfe dieser Bibliothek können Sie Dokumente mit dem öffentlichen Schlüssel eines Dokumentempfängers verschlüsseln. Der Empfänger kann das Dokument lesen, weil er es mit dem nur ihm bekannten privaten Schlüssel entschlüsseln kann.

Für die Verschlüsselung können auch mehrere öffentliche Schlüssel verwendet werden (Multi-Recipient). Bei der Verschlüsselung mit mehreren öffentlichen Schlüsseln kann jeder Empfänger die Datei mit seinem eigenen privaten Schlüssel entschlüsseln. Dies ist ideal für Team-Szenarien, in denen mehrere Personen Zugriff auf dieselbe verschlüsselte Datei benötigen.

Intern wird die BouncyCastle-Kryptographie-Bibliothek (org.bouncycastle.*) verwendet. Es werden sowohl binäre (.gpg) als auch ASCII-Armor-Formate (.asc) unterstützt. Bei der Entschlüsselung werden automatisch signierte Nachrichten (PGPOnePassSignatureList) und komprimierte Daten (PGPCompressedData) verarbeitet. Der Integritätscheck (withIntegrityCheck) ist standardmäßig aktiviert und erhöht die Sicherheit. Alle Operationen werden in einer Transaktion ausgeführt.

Unterschied zwischen binärem und ASCII-Armor-Format

Binärformat (.gpg)	ASCII-Armor-Format (.asc)
Kompaktere Dateigröße	Größere Dateigröße (ca. 33 % größer durch Base64-Kodierung)
NIcht per E-Mail oder in Textfeldern übertragbar	Per E-Mail und in Textfeldern sicher übertragbar
Für Dateiverschlüsselung optimal	Für E-Mail-Verschlüsselung und Textübertragung optimal
Parameter: armor = false (Standard)	Parameter: armor = true

Einbinden der Bibliothek

Binden Sie die Bibliothek stets am Anfang eines Skripts ein:

let pgp = require('common/pgp');

Funktionen

encryptFile

Verschlüsselt eine Datei mit einem oder mehreren öffentlichen PGP-Schlüsseln. Die verschlüsselte Datei kann nur mit dem zugehörigen privaten Schlüssel wieder entschlüsselt werden.

Syntax

pgp.encryptFile(object, outputObject, publicKeys, withIntegrityCheck, armor);

Parameter

Parameter	Beschreibung	Pflicht	Standard
object	Zu verschlüsselndes Objekt (agorum.InputStream oder agorum.Object)	ja	–
outputObject	Zielobjekt für die verschlüsselte Datei (agorum.Object). Wenn nicht angegeben, wird eine temporäre Datei erstellt	nein	null (temporäre Datei)
publicKeys	Einzelner öffentlicher Schlüssel oder Array von öffentlichen Schlüsseln (agorum.InputStream, agorum.Object, direkt oder als Array)	ja	-
withIntegrityCheck	Fügt einen Integritätscheck hinzu (boolean)	nein	true
armor	Verwendet ASCII-Armor-Format (boolean)	nein	false

Beispiele

Eine Datei mit einem öffentlichen Schlüssel verschlüsseln

let pgp = require('common/pgp');
let objects = require('common/objects');

let target = objects.find('/Home/roi/MyFiles/pgp/out');
let pubKey = objects.find('/Home/roi/MyFiles/pgp/Example_public.asc');
let unencrypted = objects.find('/Home/roi/MyFiles/pgp/unencrypted.pdf');

// Encrypt a file with a public key
let outFile = objects.create('file', {
  name: 'encrypted.pdf.gpg',
  target: target,
});
pgp.encryptFile(unencrypted, outFile, pubKey);

Eine Datei mit mehreren öffentlichen Schlüsseln verschlüsseln

let pgp = require('common/pgp');
let objects = require('common/objects');

let target = objects.find('/Home/roi/MyFiles/pgp/out');
let pubKey = objects.find('/Home/roi/MyFiles/pgp/Example_public.asc');
let pubKey2 = objects.find('/Home/roi/MyFiles/pgp/Example2_public.asc');
let unencrypted = objects.find('/Home/roi/MyFiles/pgp/unencrypted.pdf');

// Encrypt a file with multiple public keys
let outFile = objects.create('file', {
  name: 'encryptedMulti.pdf.gpg',
  target: target,
});
pgp.encryptFile(unencrypted, outFile, [pubKey, pubKey2]);

 

Verschlüsselung mit ASCII-Armor-Format 

let pgp = require('common/pgp');
let objects = require('common/objects');

let target = objects.find('/Home/roi/MyFiles/pgp/out');
let pubKey = objects.find('/Home/roi/MyFiles/pgp/Example_public.asc');
let unencrypted = objects.find('/Home/roi/MyFiles/pgp/unencrypted.pdf');

// Encrypt a file with ASCII armor format
let armoredFile = objects.create('file', {
  name: 'encrypted-armored.asc',
  target: target,
});
pgp.encryptFile(unencrypted, armoredFile, pubKey, true, true);

 

Rückgabewerte

Das verschlüsselte agorum.Object. Wenn kein outputObject angegeben wurde, wird ein temporäres Objekt zurückgegeben.

Es wird eine Fehlermeldung ausgegeben, wenn der öffentliche Schlüssel nicht gefunden wird.

decryptFile

Entschlüsselt eine PGP-verschlüsselte Datei mit dem zugehörigen privaten Schlüssel.

 

Syntax

pgp.decryptFile(object, outputObject, secretKey, pass);

Parameter

Parameter	Beschreibung	Pflicht	Standard
object	Zu entschlüsselndes verschlüsseltes Objekt (agorum.InputStream oder agorum.Object)	ja	–
outputObject	Zielobjekt für die entschlüsselte Datei (agorum.Object). Wenn nicht angegeben, wird eine temporäre Datei erstellt	nein	null (temporäre Datei)
secretKey	Privater Schlüssel zum Entschlüsseln (agorum.InputStream oder agorum.Object)	ja	–
pass	Passwort des privaten Schlüssels (String oder char[]). Kann null sein, wenn der Schlüssel nicht passwortgeschützt ist	nein	null

 

Beispiele

Eine verschlüsselte Datei mit Secret Key (nicht passwortgeschützt) entschlüsseln

let pgp = require('common/pgp');
let objects = require('common/objects');

let privKey = objects.find('/Home/roi/MyFiles/pgp/Example_SECRET.asc');
let encrypted = objects.find('/Home/roi/MyFiles/pgp/out/encrypted.pdf.gpg');
let target = objects.find('/Home/roi/MyFiles/pgp/outDecrypted');

// Decrypt a file without password
let decryptedFile = objects.create('file', {
  name: 'decrypted.pdf',
  target: target,
});
pgp.decryptFile(encrypted, decryptedFile, privKey, null);

 

Eine verschlüsselte Datei mit Secret Key (passwortgeschützt) entschlüsseln

Wenn der private Schlüssel zusätzlich passwortgeschützt ist, müssen Sie auch das Passwort angeben, um den privaten Schlüssel für das Entschlüsseln zu verwenden.

let pgp = require('common/pgp');
let objects = require('common/objects');

let privKey = objects.find('/Home/roi/MyFiles/pgp/Example_SECRET.asc');
let encrypted = objects.find('/Home/roi/MyFiles/pgp/out/encrypted.pdf.gpg');
let target = objects.find('/Home/roi/MyFiles/pgp/outDecrypted');

// Decrypt a file with a password
let decryptedFile = objects.create('file', {
  name: 'decrypted.pdf',
  target: target,
});
pgp.decryptFile(encrypted, decryptedFile, privKey, '<password>');

 

Eine ASCII-Armor-Datei entschlüsseln

let pgp = require('common/pgp');
let objects = require('common/objects');

let privKey = objects.find('/Home/roi/MyFiles/pgp/Example_SECRET.asc');
let encrypted = objects.find('/Home/roi/MyFiles/pgp/out/encrypted-armored.asc');
let target = objects.find('/Home/roi/MyFiles/pgp/outDecrypted');

// Datei entschlüsseln ohne Passwort
let decryptedFile = objects.create('file', {
  name: 'ArmoredDecrypted.pdf',
  target: target,
});

pgp.decryptFile(encrypted, decryptedFile, privKey, '<password>');

 

Rückgabewerte

Das entschlüsselte agorum.Object. Wenn kein outputObject angegeben wurde, wird ein temporäres Objekt zurückgegeben.

decryptMail

Entschlüsselt eine verschlüsselte E-Mail mit dem zugehörigen privaten Schlüssel. Die Funktion durchsucht die E-Mail-Anhänge nach .asc-Dateien (PGP-verschlüsselte Nachrichten) und entschlüsselt diese.

 

Syntax

pgp.decryptMail(mail, secretKey, pass);

 

Parameter

Parameter	Beschreibung	Pflicht	Standard
mail	Zu entschlüsselndes E-Mail-Objekt (agorum.MailObject)	ja	–
secretKey	Privater Schlüssel zum Entschlüsseln (agorum.InputStream oder agorum.Object)	ja	–
pass	Passwort des privaten Schlüssels (String oder char[]). Kann null sein, wenn der Schlüssel nicht passwortgeschützt ist.	nein	null

 

Beispiele

let pgp = require('common/pgp');
let objects = require('common/objects');

let privKey = objects.find('/Home/roi/MyFiles/pgp/Example_SECRET.asc');

let encryptedMail = objects.find('/Home/roi/MyFiles/pgp/out/encoded-mail-object');
let decryptedMail = pgp.decryptMail(encryptedMail, privKey, null);

 

Rückgabewerte

Das entschlüsselte E-Mail-Objekt als temporäres agorum.MailObject oder null, wenn keine verschlüsselten Anhänge gefunden wurden.