docs/pws2004/freenet.mgp

%include "std.mgp"
%%default 1 bimage "gtk/gtk-window.jpg" 1024x768, center
%page
%%bimage "gtk/screenshot.jpg" 1600x1200

Freenet

"I worry about my child and the Internet all
 the time, even though she's too young to have
 logged on yet. Here's what I worry about. I
 worry that 10 or 15 years from now, she will
 come to me and say 'Daddy, where were you
 when they took freedom of the press away from
 the Internet?'"

   --Mike Godwin, Electronic Frontier Foundation 


%center
%%image "gtk/hello31.jpg" 0 200 200 1

%page

Ziele


        Projekt, Dokumentation und Implementation frei und für jeden zugänglich
%pause

        Informationsfreiheit ohne Zensur
%pause

                garantiert anonyme Veröffentlichung
%pause

                garantierter Zugang zur Information

%page

Implementation


        virtuelles Netzwerk
%pause
                Ausfall auch großer Teile des Netzes werden kompensiert

%pause
        einzelne Knoten
%pause
                kennen die gespeicherten Daten nicht
%pause
                können Datenverkehr andrere Knoten nicht lesen
%pause
                kennen Sender und Empfänger von Daten nicht


%page

Freenet aus Benutzersicht

%pause
        Alle Daten werden in Datenblöcken (keys) organisiert
%pause
        Keys werden in das Netzwerk "eingefügt"
%pause
        Maximale Größe eines Datenblocks: 1MB
%pause
        HTML-Seiten werden üblicherweise in einem Key gespeichert
%pause
        Große Dateien werden mit forward-error-correction in kleinere Blöcke geteilt
                Algorithm::FEC


%page

Freenet-URLs

Übliche Form eines Freenet-Links:

%font "t3"
 http://localhost:8888/
    CHK@pfAv9IejYPLQwaTLXDguEkUhiNUMAwI,blzDbhN~8Q28esq4JrfRWw
    //Suffix
%font "s"

%pause
        http://localhost:8888/ nur der Pfad zum HTTP-Proxy des Knotens
%pause
        CHK ist der Typ (hier: Content Hash Key)
%pause
        Dahinter Folgen Parameter (meist Schlüssel u.ä.), "base64"-codiert
%pause
        Suffix (nach //) werden von Freenet ignoriert

%page

Content Hash Keys

%font "t3"
CHK@pfAv9IejYPLQwaTLXDguEkUhiNUMAwI,blzDbhN~8Q28esq4JrfRWw
^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
Typ Routing-Key                     Crypto-Key
%font "s"

%pause
        Crypto-Key wird aus den Daten generiert
                verschlüsselt die Daten
%pause
        Routing-Key wird aus dem Crypto-Key generiert
                dient zum Indizieren und Suchen der Daten
%pause
        Daten können mehrfach eingefügt werden. Da gleiche Daten == gleicher Key wird das Netzwerk nicht belaste

%page

Freenet Live

%system "/opt/bin/links -g http://129.13.162.73:8888/"

%page

Abrufen eines Freenet-Keys (1)

Beispiel: ein Bild der Seite "Thought-Crime":

%font "t3"
CHK@pfAv9IejYPLQwaTLXDguEkUhiNUMAwI,blzDbhN~8Q28esq4JrfRWw
%font "s"

1. Suche nach CHK@pfAv9IejYPLQwaTLXDguEkUhiNUMAwI
%pause
(a5f02ff487a360f2d0c1a4cb5c382e12452188d50c0302)
%pause
        0c == 4k, 0302 == CHK + Twofish
%pause
        Skalierbarkeit durch lineare Suche
%pause
2. Entschlüsseln der Daten mit blzDbhN~8Q28esq4JrfRWw
(6e5cc36e137ef10dbc7acab826b7d15b)

%page

Abrufen eines Freenet-Keys (2)

Abgerufen Daten betsehen aus Metadaten + Daten

Metadaten:

%font "t3"
Revision=1
EndPart
Document
Info.Format=image/png
End
%font "s"

Daten:

%font "t3"
PNG^Z...
%font "s"

%page

Signed Subspace Key

%font "t3"
SSK@Sc6qV~D6iFhaYord6HtbjJ8MaEYPAgM,Jrd6HtbjJfw1UO1g/YoYo
^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
Typ Public Key                 PAgM Entropie + Daten
%font "s"

%pause
        Daten werden mit einem private Key signiert
%pause
        maximale Größe 32K
%pause
        mit einem Schüsselpaar können viele Keys eingefügt werden
                Unterscheidung über angehängte Daten

%page

Und nun: Perl


        Net::Freenet::FCP
                http://www.sf.net/projects/perlfcp
%pause
                stark bei Metadaten
%pause

        Net::FCP
                CPAN
%pause
                stark beim asynchronen Einfügen bzw. Abrufen
%pause
                ist von mir, daher wird nur dieses Modul angesprochen :)

%page

Einfache Abfragen

        Abfragen benutzen das Freenet Client Protocol (FCP)
%pause
                ein einziger Horror
%pause
                zum Glück gibt's Perl :)
%pause

%font "t5"
use Net::FCP;
my $fcp = new Net::FCP;
%pause
my ($meta, $data)
   = @{ $fcp->client_get (
      "freenet:SSK@0O....PAgM/fx/3//"
      15
   ) };

%font "s"

%page

Fehlerbehandlung

        Bei Nichtfinden: die
%pause
                Net::FCP::Exception<<data_not_found,>>
%pause
                einfach nochmal probieren
%pause
        Bei Netzwerkfehlern: die
%pause
                Net::FCP::Exception<<short_data,reason:unexpected eof or internal node error>>
%pause
                einfach nochmal probieren
%pause
        Bei Schluckauf: die
%pause
                einfach nochmal probieren
%pause

Daher: eval { } benutzen.

%page

Metadaten in Perl

%pause
        Metadaten in Perl: Net::FCP::Metadata-Objekte
%pause

Am besten einmal ausgeben lassen:

%font "t5"
use Data::Dumper;
print STDERR Dumper $meta;
print $data;
%font "s"

%pause
z.B. mit eg/fetch1:

%font "t4"
eg/fetch1 SSK@0OhV.......oPAgM/fx/3// >data
%font "s"

%page

Metadaten einer Freesite

Stark gekürzt:
%pause
%font "t4"
version => { 'revision' => '1' },
 document => [ {
  info    =>{format => 'image/png'},
  redirect=>{target => 'freenet:CHK@...'},
  name    =>'activelink.png'
 }, ],
 raw => 'Version
  Revision=1
  ...
  End
  '
};
%font "s"

%page

Manifest-Metadaten


Beispiele für Keys aus den Metadaten der Freesite:

%pause
%font "t3"
Hauptseite
SSK@0OhVDWutibbBMbXmbxNXW0M6YFoPAgM/fx/3//
%pause
Icon
SSK@0OhVDWutibbBMbXmbxNXW0M6YFoPAgM/fx/3//activelink.png
%font "s"


%pause
        client_get liefert immer dieselben Daten

%pause
        Freenet ignoriert alles hinter //

%page

Manifest-Metadaten

        Selbst nachschauen durch Lookup in Metadaten:
%pause

%font "t4"
$link = grep $_->{name} eq "activelink.png",
             @{ $metadata->{document} };
%pause
print $link->{redirect};
%font "s"

%pause
        kein Redirect => Daten sind angehängt

%page
%page
%page
%page
%page
%page
%page
%page
%page
%page
%page
%page
%page


=head3 Methoden des Freesite-Managements

Oder: ``Wenn man Inhalte nicht mehr verändern kann, wie verändert man
sie?''

Die offensichtliche Methode ist: ``Man macht sie veränderbar''. In
der Freenet-Gemeinde geistert seit langer Zeit der Mythos des
I<TUK>-Schlüssels, des I<Time Updatable Keys>. Diese Schlüssel tauchen
immer auf, wenn jemand über veränderbare Schlüssel spricht.  Leider
weiss niemand, wie man sie implementieren soll, und ganz persönlich
fürchte ich, es wird niemals veränderbare Keys geben.

=head4 ``Editions''

Die nächstliegende Methode nutzt die Eigenschaft von SSKs (genauer:
redirects) aus, das man den Namen sofort generieren kann, den Inhalt aber
erst später einfügt.

Dies nutzt man aus, indem man I<Editionen> herausgibt und
durchnummeriert. Jede Edition enthält einen Link auf die nächste. Bis
man die nächste Edition einfügt, wird der Link-Inhalt nicht gefunden.

Üblicherweise benutzt man in HTML ein C<IMG>-Element mit Link auf ein
Bild aus der nächsten Edition. Sieht man das Bild, weiss man, die
nächste Edition existiert und kann sich hinklicken.

I<Freenet Explained> benutzt diese Methode. Der Link auf Edition 4 lautet:

   SSK@0OhVDWutibbBMbXmbxNXW0M6YFoPAgM/fx/4//               # Link-Ziel
   SSK@0OhVDWutibbBMbXmbxNXW0M6YFoPAgM/fx/4//activelink.png # IMG-SRC

Beides existierte nicht, als ich diesen Artikel schrieb (bzw. Freenet
konnte es nicht finden :). Wenn eine neue Edition herausgegeben werden
soll, fügt der Autor einfach einen neuen Datenblock mit vielen Redirects
unter obigem SSK-Key ein.

Ein C<.next>-Eintrag ist ebenfalls vorhanden: manche Spider folgen diesem
und können auf diese Weise immer die aktuelle Edition anzeigen, sofern
sie häufig genug scannen.

Editionen sind einfach für den Autor einer Freesite und erfordern
keine spezielle Unterstützung. In der Benutzung sind sie allerdings
umständlich und häufige Updates sind auch nicht effizient.

Daher hat sich eine zweite Methode entwickelt, die gerade bei häufig
geänderten Inhalten besser funktioniert:

=head4 ``Date Based Redirects''

Freesites, die ``Date Based Redirects'' benutzen (kurz ``DBR-Sites'')
funktionieren ähnlich wie Editionen-basierte Freesites, nur wird statt
einer fortlaufenden Nummer die aktuelle Zeit benutzt.

=for latex
 \begin{sloppypar}

Die Freesite I<The Freenet Help Index>
(C<SSK@rjYFfgPHfolmcStiaoxESFfBXz8PAgM/ FreenetHelp//>) benutzt diese
Methode. Folgende Metadaten wurden dazu hinterlegt:

=for latex
 \end{sloppypar}

   'version' => { 'revision' => '1' },
   'document' => [
       { 'date_redirect' => {
            'increment' => '15180',
            'target' => 'SSK@rjYFfgPHfolmcStiaoxESFfBXz8PAgM/FreenetHelp'
          }
       }
    ],

Statt einem einfachen C<redirect> gibt es jetzt einen
C<date_redirect>-Eintrag, und darin ein C<target> (dürfte bekannt sein)
und den Key C<increment>. Letzterer darf wie üblich fehlen, man sollte
dann C<86400> annehmen (ein Tag hat 86400 Sekunden). In diesem Beispiel
wird 86400 genommen (Hexadezimal 15180).

Habe ich eigentlich schon erwähnt, daß jede Zahl im FCP-Protokoll oder
im Freenet hexadezimal kodiert wird? Also, praktisch immer, außer wenn
es mal nicht so ist. Und wozu man einen Offset addiert, ist mir auch
schleierhaft. In der freien Wildbahn habe ich sowieso noch keinen gesehen.

Der Link in C<target> ist nicht vollständig (unter anderem fehlt
hinten ein C<//>). Der komplette Link wird generiert, ``indem die
aktuelle Zeit (POSIX-Zeit, üblicherweise das, was C<time> liefert),
auf C<increment>-Schritte gerundet und C<offset> addiert, als
Big-Endian-Hexadezimalzahl nach dem ersten Slash mit folgendem
Minuszeichen eingefügt wird.''

Und jetzt in Perl - zum Verstehen:

   my $doc = $metadata->{document][0]; # Oder [1] oder ...

   my $increment = (hex $doc->{increment}) || 86400;
   my $offset    = (hex $doc->{offset})    || 0;
   my $target    = $doc->{target}          || die;

   my ($head, $tail) = split /\//, $target, 2;

   my $NOW  = time;
   my $time = $NOW - $NOW % $increment + $offset;

   my $result = sprintf "%s/%x-%s", $head, $time, $tail;

Für ``jetzt'' (C<time() == 1084388445>) liefert der Algorithmus folgenden Link:

   SSK@rjYFfgPHfolmcStiaoxESFfBXz8PAgM/40a16900-FreenetHelp

Und tatsächlich, unter diesem Key findet man wieder ein Dokument mit
vielen Redirects.

DBRs haben den Vorteil, ``automatisch'' aktuell zu sein. Solange man nur
Redirects einfügt, ist die Belastung durch neue das Einfügen vieler
neuer Daten gering, Freenet kommt damit zurecht und löscht alte DBRs
bei Bedarf automatisch (ohne natürlich zu wissen, das sich in den
Datenblöcken DBRs befinden, denn die kann ja niemand dekodieren, der
nicht den Schlüssel besitzt).

Der Nachteil ist, das man eine aktuelle Uhrzeit braucht um die Site zu
finden. Schlimmer noch: die Freesite muss regelmäßig neu eingefügt
werden, eben alle C<increment> Sekunden.

DBR-Freesites, die nicht mehr maintained werden, verschwinden deshalb fast
sofort, solange man nicht einen Zeitpunkt kennt, zu dem sie noch (bzw.
schon!) existierte.

All dieses I<sollte> eigentlich in einem Metadata-Modul stattfinden. So
weit bin ich aber nicht, da mein Hauptziel das effiziente Herunterladen
großer Dateien ist.

Womit ich beim Thema wäre.

=head2 Effizient herunterladen

Transfers im Freenet zeichnen sich durch zwei Eigenschaften aus: hohe
Latenz und vergleichsweise hoher Durchsatz. Dies ist ungewöhnlich, ergibt
sich aber aus dem Suchverfahren: die Suche nach einem Datenblock kann sehr
lange dauern (sogar einige Male fehlschlagen bevor die Daten eintreffen),
sie sind jedoch einfach parallelisierbar.

Wie in Java üblich, erreichte man dies früher durch massive Benutzung
von Threads. Der Freenet-Referenz-Daemon ist davon inzwischen abgekommen
(zu langsam, zu viel Speicher und zu hohe Komplexität), doch viele
Clients haben auch heute noch Voreinstellungen wie `Anzahl der Threads pro
Download'' und viele sind auch so implementiert.

Da Perls aktuelle Thread-Implementierung ein Prozessmodell simuliert
ist der Overhead ebenfalls entsprechend hoch, und man erhält bei
Thread-Benutzung viele ihrer Nachteile, jedoch keine nennenswerten
Vorteil, außer das alles etwas langsamer läuft und man daher besser
zuschauen kann :)

Für C<Net::FCP> (oder besser: für mich) kam es deshalb nicht in Frage,
Parallelisierung auf Thread-Basis zu implementieren. Das Problem auf
den Modul-Benutzer abzuschieben erschien mir auch nicht fair, daher
unterstützt C<Net::FCP> die Module L<Coro>, L<Event>, L<Glib> oder L<Tk>,
bzw. deren Event-Steuerung. Man hat also die Wahl, auf welcher Basis man sein
Programm aufbaut, und es geht auch ganz ohne Event-System (wie die obigen
einfachen Beispiele zeigen).

=head3 Transaktionen

C<Net::FCP> benutzt für jeden Request eine I<Transaktion>. Das ist ein
Objekt, das den Zustand und eintreffende Ergebnisse speichert.

Jede Anfrage, (z.B. C<client_get>) wird intern in ein solches
Transaktionsobjekt verwandelt. Für jede ``einfache'' Methode wie
C<client_get> oder C<insert_private_key> gibt es eine entsprechende
Methode mit C<txn_>-Präfix, die statt des Resultats ein solches Objekt
liefert.

Transaktionsobjekte besitzen einige Methoden, mit denen sie konfiguriert
werden können oder Ergebnisse abgefragt werden können. Die wichtigste
ist die C<result>-Methode, die auf das Ergebnis wartet und es
zurückliefert:

   # $fcp->client_get wird intern so implementiert:
   my $txn = $fcp->txn_client_get (...);
   return $tdn->result;

Es ist übrigens immer gefahrlos, Transaktionsobjekte zu erzeugen. Etwaige
Fehler bei der Durchführung werden immer erst beim Aufruf von C<result>
und immer als Perl-Exceptions gemeldet.

Um also alle Freenet-Objekte im Array C<@download> gleichzeitig
anzufordern, reicht folgender Code:

   map $_->result,
       map $_->txn_client_get ($_),
           @download;

Zuerst werden alle URIs auf eine entsprechende Transaktion gemapped, und
dann von allen Transaktionen das Resultat angefordert.

Natürlich brauchen manche Zugriffe länger als andere. Wenn Transaktionen
früher beendet werden, sollte man gleich eine neue starten, um Freenet
am Laufen zu halten.

Dazu benötigt man ein Signal, daß eine Transaktion beendet ist. Dies
macht C<Net::FCP> mit Hilfe eines Callbacks:

   my $txn = $fcp->txn_client_get (...)
                 ->cb (\&callback);

Diesen setzt man mit Hilfe der C<cb>-Methode. Alle Methoden, die ein
Transaktionsobjekt konfigurieren, liefern das Transaktionsobjekt zurück,
man kann also Aufrufketten wie im Beispiel bilden.

Der Callback wird aufgerufen, wenn der Request (erfolgreich oder nicht)
beendet wurde.

Nun braucht man allerdings die Hauptschleife des jeweiligen Event-Systems,
da man ja nicht mehr auf ein bestimmtes Ergebis wartet, sondern auf ein
beliebiges.

Dazu sollte man C<Net::FCP> auf ein bestimmtes Event-System zwingen. Das
folgende Beispiel tut dies und lädt die Kommandozeileargumente parallel
herunter:

   use Net::FCP qw(event=Event); # oder event=Glib, oder...

   my $fcp = new Net::FCP;
   $fcp->txn_client_get ($_)->cb (\&finished) for @ARGV;

   Event::loop; # hier passierts, loop ist die Hauptschleife von Event

Die Transaktionsobjekte werden übrigens nicht gespeichert, denn sie
werden dem Callback übergeben, und nur dort werden sie gebraucht. Der
Callback könnte so aussehen:

   sub finished {
      my ($txn) = @_;
      my ($meta, $data) = @{ $txn->result };
      # tue etwas
   }

Oder, mit Fehlerprüfung:

   sub finished {
      my ($txn) = @_;
      my ($meta, $data) = eval { @{ $txn->result } };
      if ($@) {
         warn "fehler: $@, wird einfach ignoriert :)"
      } else {
         warn "Lo and Behold! We got soemthing!";
         # tue etwas
      }
   }

=head3 Fortschritt ist nicht aufzuhalten

Da Zugriffe recht lange dauern können, schickt Freenet regelmäig
Fortschrittsreports. Man kann sich das vorstellen wie C<warn> und
C<die>: C<warn> liefert wichtige Informationen, C<die> einen Fehler.

Die Fortschrittsanzeigen werden normalerweise nicht von C<Net::FCP>
ausgegeben (wäre irgendwie kontraproduktiv in einem GUI-Programm), man
kann aber einen Callback installieren:

   my $fcp = Net::FCP progress => \&progress;

Ein solcher Progress-Callback könnte so aussehen:

   sub progress_cb {
      my ($self, $txn, $type, $attr) = @_;

      warn "progress<$txn,$type," . (join ":", %$attr) . ">\n";
   }

Möchte man Informationen für den Callback bereitstellen, so bietet sich
die C<userdata>-Methode von Transaktionsobjekten an.

Hier ist ein kompletter parallelisierender Client mit Fortschrittsanzeige:

   my $fcp = Net::FCP progress => \&progress;

Ein solcher Progress-Callback könnte so aussehen:

   use Net::FCP qw(event=Event); # oder event=Glib, oder...

   my $fcp = new Net::FCP progress => \&progress_cb;

   $fcp->txn_client_get ($_)->cb (\&finished) for @ARGV;

   Event::loop; # hier passierts, loop ist die Hauptschleife von Event

   sub finished {
      my ($txn) = @_;
      my ($meta, $data) = eval { @{ $txn->result } };
      if ($@) {
         warn "$txn: fehler: $@, wird einfach ignoriert :)\n"
      } else {
         warn "$txn: Lo and Behold! We got something!\n";
         # tue etwas
      }
   }

   sub progress_cb {
      my ($self, $txn, $type, $attr) = @_;

      warn "$txn: progress<$txn,$type," . (join ":", %$attr) . ">\n";
   }

Startet man ihn mit einigen gültigen und ungültigen Freenet-URIs,
bekommt man vieleicht folgende Ausgabe:

   Net::FCP::Txn::ClientGet=HASH(0x81e0f64): ...
      ... fehler: Net::FCP::Exception<<uri_error, ...
      ... reason:Unspecified document name>>, wird einfach ignoriert :)
   Net::FCP::Txn::ClientGet=HASH(0x81e7254): ...
      ... fehler: Net::FCP::Exception<<uri_error,reason: ...
      ... Unknown keytype>>, wird einfach ignoriert :)
   Net::FCP::Txn::ClientGet=HASH(0x81e0c4c): ...
      ... progress<Net::FCP::Txn::ClientGet=HASH(0x81e0c4c), ...
      ... data_found,data_length:74:metadata_length:74>
   Net::FCP::Txn::ClientGet=HASH(0x81e0c4c): ...
      ... progress<Net::FCP::Txn::ClientGet=HASH(0x81e0c4c), ...
      ... data,chunk:116:total:116:received:116>
   Net::FCP::Txn::ClientGet=HASH(0x81e0c4c): ...
      ... Lo and Behold! We got something!
   ... usw.

Benutzt man das C<Coro>-Modul, so kann man Callback-basierte und Thread-
(bzw. Coroutinen-) basierte Programmierung mischen:

   use Net::FCP qw(event=Coro);

   my $fcp = new Net::FCP;

   # Achtung. Pseudocode :)
   for my $url (@urls) {
      async {
         my ($meta, $data) = @{ $fcp->client_get ($url) };

         if ($meta ist ein splitfile) {
            for (@alle_splitfile_blöcke) {
               $fcp->txn_client_get (...)
                   ->cb (\&save_splitfile_block);
            }
         } else {
            # direkt speichern
         }
      };
   }

=head3 Splitfiles

Das Them Splitfiles möchte ich hier noch erwähnen, aber nicht
ausführlich besprechen.

Da die Datenblöcke im Freenet (zur Zeit) nicht größer als 1MB sein
können, müssen größere Dateien (Filme z.B.) aufgeteilt werden. Wenn
man viele Datenblöcke für eine Datei braucht, erhöht sich die
Wahrscheinlichkeit dafür, daß ein Block mal fehlt oder nicht gefundne
werden kann, stark auf einen Wert, der das Herunterladen großer Dateien
unmöglich macht.

Daher wird mit Fehlerkorrekturcodes die Anzahl der Blöcke um 50%
erhöht. Metadaten für ein Splitfile sehen so aus:

   'version' => { 'revision' => '1' },
   'document' => [ {
      'info' => {
            'checksum' => '3bab309132f812cb2a281357b0dc1036920672e2',
            'format' => 'video/mpeg',
            'description' => 'Onion FEC v1.2 file inserted by Fuqid'
         },
      'split_file' => {
         'algo_name' => 'OnionFEC_a_1_2',
         'check_block_count' => '3f',
         'block_count' => '7f',
         'check_block' => {
            '33' => 'freenet:CHK@eTNQ...3CBzTSsI~oPn6EUAwI,I4X...nyGoIRZBLg',
            '32' => 'freenet:CHK@Ee1h...Kg3WZ90KXqwQZMUAwI,ppn...k1z3Sempqw',
            '1e' => 'freenet:CHK@5gBB...fjO27kOtU0hZgkUAwI,Okf...wvtX~wfVNA',
            [viele Zeilen fehlen hier :]
            '3d' => 'freenet:CHK@iIT1...yOToFsyyytV-roUAwI,9u3...-eY7Onag1g',
            '5' => 'freenet:CHK@EeVsn...CNBNVzvTTQ1l0UAwI,q6e...Oh-cc79WBA'
         },
         'block' => {
            '33' => 'freenet:CHK@j522...h2ZK1D1q4UDnFgUAwI,Xwo...XFwI5f9iyw',
            '32' => 'freenet:CHK@VU5v...y-Dnk8SCt9ZKbYUAwI,iX~...3Yk0rmpM9w',
            '5d' => 'freenet:CHK@-wbX...uotK~uZbJp14zsUAwI,-bg...YvbwQeYtyA',
            [viele Zeilen fehlen hier :]
            '43' => 'freenet:CHK@zMXc...ee1cftvdK4~QukUAwI,o99...adXUXGjrlg',
            '5' => 'freenet:CHK@1ZDiv...YTKQbDq1yCPWAUAwI,B9f...fOx~PTZkAA',
            '3d' => 'freenet:CHK@ZGxa...qQIf6rbr-g8btMUAwI,f0x...mmxoJRzaLw'
         },
         'size' => '7e8e804'
         }
      } ],
   }

Die Datenblöcke und die zusätzlichen Korrekturblöcke sind getrennt
aufgeführt. Man braucht nur so viele Blöcke insgesamt, wie die Datei
groß ist. Den Rest kann man aus den heruntergeladenen erzeugen.

Wie genau die Daten auf die Blöcker verteilt werden unterliegt einem
Algorithmus und ist nicht in den Metadaten gespeichert. Der Grund ist,
daß jedes Programm denselben Algorithmus benutzen muss, und Dateien daher
immer gleich auf die Blöcke verteilt werden, so daß Mehrfacheinfügen ins
Freenet keine Duplikate erstellt.

Den genauen Algorithmus kann man in der Datei C<bin/fmd>, dem I<Freenet
Mass Downloader> in der Funktion C<state_splitfile> nachlesen. Der Code
ist weder besonders klar, noch besonders kurz, noch besonders hübsch. Auch
dieser Teil wird irgendwann einmal in ein Modul fließen, damit er anderen
zugänglicher wird.

Interessant ist noch, daß man CHK-Inhalte, die aus dem Freenet
heruntergeladen werden, einfach auf Konsistenz prüfen kann: sie enthalten
schließlich den SHA1-Hash der Daten:

   use Net::FCP::Util;

   my ($meta, $data) = @{ $fcp->client_get ($uri) };

   # Extrahiere den Hash aus der URI
   my $k1 = Net::FCP::Util::extract_chk_hash $uri;
   # Berechne den Hash aus den Daten
   my $k2 = Net::FCP::Util::generate_chk_hask "$meta->{raw}$data";

   # Idealerweie stimmen beide überein...
   $k1 eq $k2 or die "Key/Content mismatch!";

Zwar ist der Freenet-Daemon angeblich perfekt, aber früher passierte
es tatsächlich oft, daß man korrupte Daten geliefert bekam. Retryen
half. Man hat es eben nicht so leicht...

Heute ist das zwar nicht mehr der Fall (...), aber prüfen kostet fast
nichts.

=head2 Publizieren

Das Freenet lebt von vielen Dingen: Den Entwicklern, den Benutzern die
ihr Interesse bekunden, den Regierungen, die die Meinungsäußerung
einschränken - aber vor allem dadurch, daß es sinnvolle Inhalte darin gibt.

Ich bin mir nicht so sicher, I<ob> es so viele sinnvolle Inhalte gibt,
aber noch gab es ja auch keine 1.0-Release...

Nun ja, solange man nichts ins Netz stellt, darf man auch nicht klagen.

Das kann man ändern, indem man so langweilige Dinge wie den I<Freenet
Insertion Wizard> oder das beliebte I<Fuqid> benutzt (was ich noch nie
getan habe). Aber die benutzen kein Perl und sind damit langweilig.

Mit C<Net::FCP> geht es erstmal sehr einfach:

   $fcp->client_put ($uri, $metadata, $data, $htl, $removelocal);

(Auch hier gibt es natürlich wieder die entsprechende C<txn_>-Variante).

Einfügen von Inhalten geht also fast geanuso wie Auslesen. C<$uri> ist
eine Freenet-``URIC'' (mit oder ohne C<freenet:>), wie man zu dieser kommt
gleich mehr.

C<$metadata> kann entweder ein Freenet-Metadata-String sein oder ein Hash
der gleichen Form wie man ihn zurückgeliefert bekommt. C<$data> sind
natürlich die eigentlichen Daten und C<$htl> sind die Hops-To-Live, die
der Key-Insert haben soll. Höhere Werte (bis hin zu 25) speichern die
Daten dauerhafter, brauchen aber auch entsprechend länger.

C<$removelocal>, auf C<1> gesetzt, sorgt dafür, daß der lokale
Netzknoten die Daten I<nicht> cached. Warum man das tun sollte, ist
einfach erklärt: wenn Freenet beim Einfügen die Daten schon im Netz
vorfindet, wird der Einfügevorgang abgebrochen. Möchte man die Daten
regelmäßig ``auffrischen'' dann sorgt diese Option dafür, daß die
Daten den Knoten auf jeden Fall verlassen und erhöhen so die Chance auf
Verbreitung.

Nun die Frage wie man zu einer URI kommt. Möchte man einen CHK-Schlüssel
einfügen, so setzt man die URI einfach auf den String C<CHK@>. Nach dem
Einfügen erhält man die eigentliche URI als Resultat:

   my $attr = $fcp->client_put ('CHK@', "", "Daten\n", 20);
   print "eingefügte URI: $attr->{uri}\n";

Als Ergebnis dieses C<client_put>-Requests erhielt ich:

   freenet:CHK@MT~LuxKHH8fugJehkcgp239h7C4KAwI,378rJzHVZbsQbd7VGMHxSg

Beim Einfügen ins Freenet kann es auch einen I<Key Collision>-Fehler
geben, und zwar genau dann, wenn Freenet die Daten schon findet, die man
einfügen wollte.

C<Net::FCP> behandelt diesen Fehler allerdings genauso wie ein
erfolgreicher Einfügevorgang, lediglich im Hash, den es zurückliefert,
wird das C<key_collision>-Element auf C<1> gesetzt. Wenn die Daten schon
vorhanden sind, ist das Ziel schließlich auch erreicht.

Häufig möchte man den C<CHK>-Schlüssel aber schon im voraus
Wissen. Dazu kann man entweder seinen freundlichen Freenet-Daemon fragen:

   my $key = $fcp->generate_chk ($metadata, $data);

Oder man verwendet das C<Net::FCP::Key::CHK>-Modul, das schneller ist und
keinen Serverzugang benötigt:

   use Net::FCP::Key;

   my $key = (new_from_data Net::FCP::Key::CHK $metadata, $data)->chk;

=head3 SSK-Schlüssel generieren

SSK-Schlüssel bestehen immer aus zwei Teilen, dem öffentlichen
(C<public_key>) und dem privaten (C<private_key>), die zusammen ein Paar
bilden. Neuerdings noch aus einem dritten, dem C<crypto_key>, der es
Brute-Force-Attacken noch schwieriger machen soll.

Solch ein Schlüsselpaar kann man mit einem Aufruf von
C<generate_svk_pair> (auch hierfür gibt es eine C<txn_>-Variante)
erzeugen. Das ``svk'' ist übrigens kein Schreibfehler: SSK-Schlüssel sind
ein Spezialfall von SVK-Schlüsseln, die man aber als normalsterblicher
nirgendwo direkt antrifft.

   my ($public, $private, $crypto) = @{ $fcp->generate_svk_pair };

Daraus kann man beliebig viele SSK-Schlüssel erzeugen, indem man die drei
Teile wie folgt zusammensetzt:

   # Öffentlicher Schlüssel:

   my $name = "..."; # beliebig

   my $get = "SSK\@${public}PAgM,$crypto/$name";
   my $put = "SSK\@$private,$crypto/$name";

Den mit C<$put> bezeichneten Schlüssel muss man zum Einfügen
verwenden. Mit dem mit C<$get> bezeichneten Schlüssel kann man diese
Daten wieder holen. Letzterer kann bedenkenlos veröffentlich werden.

Das SSK-Management kann vom C<Net::FCP::Key::SSK>-Modul übernommen
werden.

=head3 Eine Freesite erzeugen

Um eine Freesite zu erzeugen, sollte man sich zuerst einen dauerhaften
SSK-Schlüssel besorgen:

   # perl -MNet::FCP -MNet::FCP::Key::SSK \
          -e 'Net::FCP::Key::SSK->new_from_fcp (Net::FCP->new) \
                                ->save ($ARGV[0])' mykey

Das erzeugt einen neuen SSK-Schlüssel und speichert ihn gleich in der
Datei C<mykey>.

Dieser SSK-Schlüssel wird die Basis der Freesite.

Für das Einfügen schreibt man sich am besten ein Skript, da man ides
regelmäßig wiederholen sollte. Zuerst ein paar Definitionen:

   my $edition = 1;
   my $keyfile = "mykey";
   my $htl = 10;

Das Skript legt eine editionenbasierte Freesite an und benutzt als Basis
den eben erzeugten SSK-Schlüssel. Der Hops-To-Live-Wert von 10 ist etwas
klein, aber so dauert das Einfügen vielleicht nur ein paar Minuten... In
der Praxis sollte man 20-25 vorziehen, oder das Einfügen regelmäig
wiederholen.

Als nächstes benötigen wir ein paar Module:

   use Net::FCP qw(event=Event);
   use Net::FCP::Metadata;
   use Net::FCP::Key::SSK;

Generell sollte man in einem Perl-Programm den verwendeten
Event-Mechanismus fest angeben. In Freenet-Modulen sollte man dies dagegen
nicht tun, um dem Benutzer die Wahl zu überlassen. Stattdessen sollte
man in Modulen nur Transaktionen benutzen und diese dem Benutzer zur
Verfügung stellen.

Als nächstes werden ein paar notwendige Objekte erzeugt:

   my $fcp = new Net::FCP;
   my $ssk = new_from_file Net::FCP::Key::SSK $keyfile;
   my $manifest = new Net::FCP::Metadata;

Die Metadaten für die Hauptseite (C<$manifest>) werden auch
``Manifest'' genannt, da man dort häufig nur Verweise auf die
jeweiligen Unterseiten ablegt, also sowas wie der Grundstein einer
Freesite. Das C<Net::FCP::Metadata>-Modul biette zur Zeit nur spärliche
Funktionalität, für unsere Zwecke reicht das jedoch aus.

Nun noch zwei Hilfsfuntionen. Zuerst C<add_key>:

   sub add_key {
      my ($name, $key, $meta, $data) = @_;

      # Asynchrones Einfügen
      $fcp->txn_client_put ($chk, $meta, $data, $htl, 1)
          ->cb (sub {
               eval {
                  my $attr = $_[0]->result;
                  printf "Insert of '%s' (%d bytes) ok.\n", $name, length $data;
               } or warn "Error while inserting '$name': $@";
            });
   }

C<add_key> startet eine C<client_put>-Transaktion, ohne auf das Ende zu
warten. Im Callback wird das Resultat angezeigt, oder, wenn ein Fehler
Auftrat, eben dieser. Das Skript sollte so angelegt sein, das man es
einfach nochmal starten kann, wenn einige Schlüssel nicht eingefügt
werden konnten.

Nun noch C<add_file>:

   # Hilfsfunktion zum Einfügen von Dateien
   sub add_file {
      my ($name, $path, $contenttype) = @_;

      # lies die Datei ein
      my $data = do {
         local $/;
         open my $fh, "<", $path
            or die "$path: $!";
         <$fh>
      };

      my $chk = $fcp->generate_chk ("", $data); # keine metadaten
      $manifest->add_redirect ($name => $chk, format => $contenttype);
      add_key $name, $chk, "", $data;
   }

C<add_file> lädt eine externe Datei (< 1MB) und berechnet deren
CHK-Schlüssel. Diesen Schlüssel fügt es als Verweis unter dem Namen
C<$name> in das Manifest ein. Als letztes benutzt es C<add_key>, um die
Datei einzufügen.

Das Vorausberechnen des CHK-Schlüssels macht es möglich, das Manifest
paralell zu den anderen Schlüsseln einzufügen.  Würde man auf den
Einfügevorgang warten, müsste man das Manifest am Ende getrennt
hochladen.

Nun ans Zusammenbauen. Zuerst werden (unsichtbare) Verweise auf die
vorherige bzw. die nächste Edition eingefügt:

   $manifest->add_redirect (".prev" => $ssk->gen_pub ($edition - 1))
      if $edition > 1;
   $manifest->add_redirect (".next" => $ssk->gen_pub ($edition + 1));

Dies nutzt zum einen die Eigenschaft von SSKs, einfach vorausberechnet
werden zu können, als auch die Methode C<gen_pub>, die den öffentlichen
SSK-Schlüssel mit optionalem Suffix generiert.

Dadurch können Benutzer auch ``per Hand'' eine neuere oder ältere Edition
suchen, indem sie einfach die Zahl (C<.../2//index.html>) vor dem C<//>
ändern.

Als nächstes folgt der eigentliche Inhalt der Freesite, eine HTML-Seite,
ein Bild und der Quellcode des Skriptes, der sie generiert hat:

   add_file "activelink.png" => "logo.png", "image/png";
   add_file "" => "index.html", "text/html";
   add_file "index.html" => "index.html", "text/html";
   add_file "freesite" => "freesite", "text/plain";

Die Datei C<index.html> wird zweimal hinzugefügt, einmal unter dem Namen
``'' und ein zweitesmal unter dem Namen ``C<index.html>''. Dadurch kann man
erreichen, was viele HTTP-Server ebenfalls machen, nämlich eine URI, die
auf ein Verzeichnis zeigt, auf eine Datei darin zu verweisen. Das die
Datei zweimal eingefügt wird ist kein Problem, da der CHK-Schlüssel
derselbe ist (und Mehrfacheinfügen kein Fehler).

Nachdem die Dateien hinzugefügt (und vor allem ins Manifest eingetragen)
wurden, kann man das Manifest einfügen:

   my $site = $ssk->gen_pub ($edition);
   add_key "manifest", $site, $manifest, "";

Das Manifest wird. Damit man hinterher auch weiss, was man da eingefügt
hat, sollte man den Hauptschlüssel auch ausgeben:

   print "site generated as $site//\n";

Und da die ganzen Einfügevorgange ja nur gestartet wurden, muss man auf
deren Ende warten:

   Event::loop;

Solange C<Event> noch aktive Watcher sieht, bleibt es in der
Event-Schleife. Wenn es keinen aktiven Watcher mehr gibt, kehrt C<loop>
automatisch zurück und das Programm ist beendet.

Die Ausgabe sieht dann z.B. so aus:

   site generated as SSK@wg...TBRylfnDlUBfjETgPAgM,Jr...UBDPfw1UO1g/1//
   Insert of 'freesite' (1688 bytes) ok.
   Insert of 'activelink.png' (1346 bytes) ok.
   Insert of 'index.html' (200 bytes) ok.
   Insert of '' (200 bytes) ok.
   Insert of 'manifest' (0 bytes) ok.

Wenn man einen Fehler gemacht hat, kann man einfach einen neuen
SSK-Schlüssel generieren. Das heißt, solange man seine Site nicht schon
veröffentlicht hat.

Die Alternative wäre z.B. ein täglicher Date-Based-Redirect, d.h.
tägliches komplettes Neueinfügen. Da bügeln sich Fehler schnell von
selbst aus, man muss sein Skript dann natürlich über Tage oder Monate
regelmäßig starten.

Eine offensichtliche Verbesserung wäre es, HTML-Dateien abzuändern, so
daß man Links auf die nächste Revision nicht hardcodieren muss sondern
etwa als C<%%NEXT%%//activelink.png> schreiben könnte.

Nun ja, ich hoffe, es machen sich nun einige Leser auf, um eigene
Freesites zu erstellen oder andere Anwendungen für das Freenet zu
erstellen.

=head2 Verweise

=over 4

=item L<http://www.freenetproject.org/>

Die Hauptseite des Freenet-Projekts. Hier gibt es auch White-Papers, etwas
Dokumentation und Mailinglisten(-archive).

=item L<http://www.freenethelp.org/>

Hier findet der gestresste Freenetter Hilfe beim Einrichten und Betrieb
seines Knotens. Vielleicht.

=back


Revision:	1.2
Committed:	Sun Jun 20 20:31:05 2004 UTC (22 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.1:	+172 -413 lines
Log Message:	* empty log message *