Dokumentation

Ziel

BinaryConverter ist fuer Umgebungen gedacht, in denen eine binaere Datei nicht direkt uebertragen werden kann, Text per Copy & Paste aber moeglich ist. Die Anwendung erzeugt deshalb eine robuste Textdarstellung und prueft beim Rueckweg, ob die rekonstruierte Datei bytegenau passt.

Dateiformat

Das Transferfile besteht aus Kommentar-Metadaten, einem Beginn-Marker, Base64-Nutzdaten und einem Ende-Marker.

# BinaryConverter-Format: 1
# Encoding: Base64
# SourceFileNameBase64: <UTF-8-Dateiname als Base64>
# SourceLength: <Bytes>
# SHA256: <Hex-Hash>
# CreatedUtc: <ISO-8601>
# LineLength: 76
-----BEGIN BINARYCONVERTER BASE64-----
<Base64-Daten>
-----END BINARYCONVERTER BASE64-----

Die Base64-Nutzdaten werden mit 76 Zeichen pro Zeile geschrieben. Das ist bewusst konservativ, damit Zeilenumbrueche in vielen Editoren, Konsolen und Remote-Sessions gut handhabbar bleiben.

Integritaet

Beim Encode wird die Eingabedatei zuerst einmal gelesen, um SHA-256 zu berechnen. Danach wird sie in einem zweiten Durchlauf als Base64 geschrieben. Der zweite Durchlauf vermeidet, dass grosse Dateien komplett in den Speicher geladen werden.

Bei Encode und Decode wird zuerst in eine temporaere Datei geschrieben. Erst nach erfolgreicher Verarbeitung wird diese temporaere Datei auf den finalen Ausgabepfad verschoben beziehungsweise ersetzt. Beim Decode passiert das erst nach erfolgreicher Laengen- und SHA-256-Pruefung. Bei Fehlern wird die temporaere Datei geloescht.

Speicherverhalten

Die Anwendung arbeitet streaming-basiert:

Eingabe wird blockweise gelesen.
Base64 wird blockweise geschrieben beziehungsweise dekodiert.
Es wird nicht die komplette Eingabe- oder Ausgabedatei in den Arbeitsspeicher geladen.

Beim Decode wird ein kleiner Base64-Puffer verwendet, um auch unguenstig umgebrochene Base64-Zeilen verarbeiten zu koennen.

Fehlerverhalten

Typische Fehler werden mit Exitcode 1 beendet:

Eingabedatei fehlt.
Ausgabedatei existiert bereits und -Force wurde nicht gesetzt.
Transferfile ist unvollstaendig, zum Beispiel fehlender Ende-Marker.
Base64-Inhalt ist ungueltig.
Dekodierte Laenge passt nicht zur Metadatenlaenge.
SHA-256 passt nicht zum Metadatenhash.

Argumentfehler werden mit Exitcode 2 beendet. Erfolgreiche Ausfuehrung endet mit Exitcode 0.

Logging

Standardmaessig schreibt BinaryConverter auf die Konsole:

Version und Operation
Eingabe- und Ausgabepfad
Fortschritt und Durchsatz
berechnete beziehungsweise gepruefte SHA-256-Summe
finale Dateigroessen

Mit -Log <Datei> werden dieselben Informationen zusaetzlich in eine Logdatei geschrieben.

Beispiele

Datei fuer Transfer vorbereiten:

.\BinaryConverter.exe -Encode C:\temp\PowerShell.exe -Output C:\temp\Out.txt -Log C:\temp\encode.log

Auf dem Zielhost zurueckwandeln:

.\BinaryConverter.exe -Decode C:\temp\Out.txt C:\temp\PowerShell.exe -Log C:\temp\decode.log

Bereits vorhandene Zieldatei ersetzen:

.\BinaryConverter.exe -Decode C:\temp\Out.txt C:\temp\PowerShell.exe -Force

Repository-Struktur

BinaryConverter/
  BinaryConverter.sln
  BinaryConverter/
    BinaryConverter.csproj
    App.config
    Program.cs
    Properties/
      AssemblyInfo.cs
  native/
    Makefile
    README.md
    src/
      binaryconverter.cpp
  .editorconfig
  .gitattributes
  .gitignore
  Dokumentation.md
  Readme.md

Native Linux-Version

Unter native/ liegt eine C++17-Implementierung fuer Linux. Sie erzeugt eine native Arch-Linux-Binary und verwendet OpenSSL/libcrypto fuer SHA-256. Das Transferformat ist identisch zur C#-Version, sodass Dateien auf Windows encoded und auf Linux decoded werden koennen oder umgekehrt.

Build:

cd native
make

Die Binary liegt danach unter native/build/binaryconverter.

Gitea-Hinweise

Das Repository enthaelt keine Build-Artefakte. bin/, obj/, native/build/, Visual-Studio-Userdateien, Logs und temporaere Dateien sind ueber .gitignore ausgeschlossen.

4.0 KiB Raw Permalink Blame History