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 anderer 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
%pause
                Algorithm::FEC


%page

Freenet-URLs

Übliche Form eines Freenet-Links:

%font "t3"
 http://localhost:8888/
    CHK@pfAv9IejYPXDguEkUhiNUMAwI,blzDbhN~q4JrfRWw
    //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 //) wird 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 Keys (1)

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

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

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

%page

Abrufen eines Keys (2)

Abgerufen Daten bestehen aus Metadaten und 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 identische Daten

%pause
        Freenet ignoriert alles hinter //

%page

Manifest-Metadaten

        Selbst nachschauen durch Lookup in den 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

Freesite-Management

%pause
        Wie verändert man Daten, die man nicht mehr verändern kann?

%pause
        Lösung 1: Veränderbare Keys (TUKs)
%pause
                Viel Rauch, wenig Realität
%pause
        Lösung 2: Editions
%pause
                Links auf zukünftige Inhalte
%pause
                "verkettete Liste"
%pause
        Lösung 3: DBR-Links
%pause
                Date-Based-Redirects

%page

Editions (1)

A-HREF + IMG-Element, zeigt auf activelink der nächsten Edition.

%pause
Beispiel: Freesite "Freenet Explained"

%font "t4"
   SSK@0OhV...oPAgM/fx/4//
   # Link-Ziel
   SSK@0OhV...oPAgM/fx/4//activelink.png
   # IMG-SRC
%font "s"

%pause
        Edition 4 existiert noch nicht
%pause
                Editionen werden durchnummeriert
%pause
                Für Spider: .next-Eintrag

%page

Editions (2)


%pause
Vorteile:
%pause
        "relativ" einfach für Autoren
%pause
        realisierbar mit "Hausmittel"
%pause
        keine Pflege notwendig
%pause

Nachteile:
%pause
        umständlich in der Benutzung
%pause
        "es ist und bleibt ein Hack"

%page

Date-Based-Redirects (1)


Unterstützung spezieller Redirects
%pause
        Datum statt fortlaufender Nummer
%pause
        Metadaten
%pause

Beispiel "The Freenet Help Index":
%pause

%font "t3"
'version' => { 'revision' => '1' },
'document' => [
    { 'date_redirect' => {
         'increment' => '15180',
         'target' => 'SSK@rjY...8PAgM/FreenetHelp'
       }
    }
 ],
%font "s"

%page

Date-Based-Redirects (2)


Vorteile:
%pause
        einfach in der Benutzung
%pause
        sauber über Metadaten implementiert
%pause
        festgelegter Key
%pause

Nachteile:
%pause
        feste Abstände zwischen Updates
%pause
        häufige Pflege
%pause
        keine inserts == keine Freesite

%page

DBR-Abruf

%font "t4"
%pause
my $D = $metadata->{document}[0];
%pause

my $incr = (hex $D->{increment}) || 86400;
my $offs = (hex $D->{offset})    || 0;
my $targ = $D->{target}          || die;
%pause

my ($head, $tail) = split /\//, $targ, 2;
%pause

my $NOW  = time;
my $time = $NOW - $NOW % $incr + $offs;
%pause
my $result = sprintf "%s/%x-%s",
             $head, $time, $tail;
%pause
%font "t3"

   SSK@rjYFfgPHfolmcStiaoxESFfBXz8PAgM/40a16900-FreenetHelp

%page

Effiziente Freenet-Abfragen

%pause
Problem:
        hohe Latenz
        parallele Anfragen absolut notwendig
        Implementation über Threads schlecht
                Perl hat keine echten Threads

Lösung:
        Ereignisgesteuert

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

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.3
Committed:	Sat Jun 26 19:24:46 2004 UTC (22 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.2:	+138 -143 lines
Log Message:	* empty log message *