SecureFiles auf der Kommandozeile

Das Werkzeug securefiles-cli bringt SecureFiles auf die Kommandozeile, für Skripte und Abläufe ohne Browser. Gestartet wird die Datei securefiles-cli.mjs mit Node.

Wofür es da ist

• Übertragungen über die Schnittstelle senden, auch Ende-zu-Ende verschlüsselt.
• Übertragungen über ihren Link abholen, auch verschlüsselte.
• Eigene verschlüsselte Übertragungen und verschlüsselte Posteingänge abholen.
• Dateien im Format des Browsers verschlüsseln und wieder entschlüsseln.

Dateien aus Pools holt das Werkzeug nicht ab, auch nicht verschlüsselte. Unverschlüsselte Posteingänge holt es ebenfalls nicht ab.

Voraussetzungen

• Node ab Version 20. Weitere Software braucht das Werkzeug nicht.
• Für send und own ein Schlüssel der Schnittstelle, der unter Einstellungen, Anbindungen entsteht. Siehe Schnittstelle.
• Die Adresse des Servers beginnt mit https://. Nur der eigene Rechner, also 127.0.0.1 oder localhost, geht ohne https.

Schlüssel der Schnittstelle

Der Schlüssel kommt aus --key-file oder aus der Umgebungsvariablen SECUREFILES_API_KEY. Beim Befehl send handelt er im Namen der Person, die ihn angelegt hat. Es gelten deren Regeln und Kontingent. Mehr dazu auf der Seite Eigener Schlüssel.

Kennwörter

• Kennwort einer Übertragung: aus --password-file oder SECUREFILES_PASSWORD. Gebraucht bei receive und bei send an Empfänger mit Ende-zu-Ende.
• Schlüsselkennwort aus Mein Schlüssel: bei own über --password-file oder SECUREFILES_KEY_PASSWORD.
• Wiederherstellungsschlüssel: bei own über --recovery-file oder SECUREFILES_RECOVERY_KEY. Ist ein Schlüsselkennwort angegeben, gilt es, und der Wiederherstellungsschlüssel wird nicht gelesen.

Für das Kennwort gibt es keine Option auf der Befehlszeile. Dort stünde es in der Prozessliste und im Verlauf der Shell. Kennwort und Wiederherstellungsschlüssel verlassen den Rechner nie.

Befehle

receive: Übertragung abholen

node securefiles-cli.mjs receive "<link>" --out <ordner> --email <empfaenger@example.com> --password-file <kennwortdatei>

Der Link steht in Anführungszeichen, weil ein Schlüssel hinter der Raute dazugehört. --email und --password-file braucht man nur, wenn der Transfer sie verlangt.

• Vorhandene Dateien werden nicht überschrieben. Ist eine Prüfsumme falsch, bleibt keine halbe Datei zurück.
• Abrufe mit Bestätigungscode per E-Mail oder mit Konto und zweitem Faktor kann das Werkzeug nicht. Bei Nur-Ansicht bricht es beim Laden ab. Dafür ist der Browser nötig.
• Lehnt der Server einen Abruf ab, nennt das Werkzeug den Grund in einem Satz und sagt, ob der Weg über den Browser führt: etwa bei einem Bestätigungscode, einer abgelaufenen oder widerrufenen Übertragung, einer laufenden Prüfung auf Schadsoftware oder genutzten Abrufen.

send: Übertragung senden

node securefiles-cli.mjs send "<datei>" --server https://<portal> --key-file <schluesseldatei> --to <empfaenger@example.com> --subject "<betreff>" --retention 7d

Ohne --to entsteht ein öffentlicher Link, dann etwa mit --retention 30d. Die Frist nimmt die Werte des Portals, etwa 7d, 30d oder forever. Liegt sie über dem, was Mandant oder Regel erlauben, kürzt der Server sie. Unbegrenzt lehnt er ab, wenn es nicht erlaubt ist.

• --message-file <textdatei> legt den Begleittext fest.
• --watermark verlangt das Wasserzeichen, --view-only die Nur-Ansicht. Beide schließen --e2ee aus. Ist die Funktion auf dem Server nicht eingerichtet, weist der Server den Aufruf ab.
• --e2ee verschlüsselt auf dem eigenen Rechner. An Empfänger geht das nur mit einem Kennwort:

node securefiles-cli.mjs send "<datei>" --server https://<portal> --key-file <schluesseldatei> --to <empfaenger@example.com> --e2ee --password-file <kennwortdatei>

Ohne --to und ohne Kennwort steht der Schlüssel hinter der Raute im Link. Diesen Link gibt das Werkzeug nur einmal aus, der Server kennt den Schlüssel nicht. Hat die Person einen eigenen Schlüssel im Portal und der Schlüssel der Schnittstelle den Zugang mit Inhalten, legt --e2ee zusätzlich einen Umschlag dafür an.

Nach dem Senden nennt das Werkzeug die Kennung der Übertragung, den Link und das Datum, bis zu dem er gilt. Scheitert ein Upload, wird die Übertragung widerrufen.

own: eigene verschlüsselte Einträge abholen

node securefiles-cli.mjs own "<kennung>" --server https://<portal> --key-file <schluesseldatei> --out <ordner> --password-file <schluesselkennwortdatei>

Die Kennung steht in der Adresse des Eintrags im Portal und in der Ausgabe von send. Statt des Kennworts geht auch --recovery-file <wiederherstellungsdatei>.

• Abgeholt werden eigene Übertragungen mit Umschlag für den eigenen Schlüssel und verschlüsselte Posteingänge samt Einreichungen.
• Der Server liefert nur den versiegelten Schlüssel, geöffnet wird auf dem Rechner. Jede Ausgabe des Schlüssels steht im Protokoll. Nicht freigegebene Dateien zählt das Werkzeug gesondert.

encrypt und decrypt: Datei verschlüsseln

node securefiles-cli.mjs encrypt "<quelle>" "<ziel>" --key-file <transferschluesseldatei>
node securefiles-cli.mjs decrypt "<verschluesselt>" "<klartext>" --key-file <transferschluesseldatei> --salt <salz>

Hier ist --key-file nicht der Schlüssel der Schnittstelle, sondern eine Datei, die encrypt anlegt. Die Schlüsseldatei und das Ziel dürfen noch nicht bestehen, und die Schlüsseldatei ist nur für den Eigentümer lesbar. encrypt nennt das Salz auf der Standardausgabe, decrypt verlangt es zusammen mit der Schlüsseldatei.

Rückgabewerte

Fehler erscheinen als Meldung auf der Fehlerausgabe. Schlüssel und Kennwort stehen in keiner Meldung. Das Werkzeug endet dann mit dem Rückgabewert 1. Fehlt der Befehl oder ist er unbekannt, endet es mit dem Rückgabewert 2 und nennt die Befehle. Bei Erfolg endet es ohne Fehler.

Die Zugänge und Fehlercodes der Schnittstelle stehen auf der Seite Schnittstelle. Bei verschlüsselten Übertragungen braucht der Empfänger das Kennwort der Übertragung, siehe Ende-zu-Ende-Verschlüsselung. Welche Einträge zu Abrufen und Übertragungen im Protokoll stehen, zeigt die Seite Protokoll. Zurück zur SecureFiles-Übersicht.