feda/doc/node_gen.txt

                  NODE MASTER KEY GENERATION


RUNNING THE GENERATOR

== please see the "CHALLENGE-RESPONSE TABLES" section below ==

To generate your node key, simply run the feda-ng program like this:

   ./feda-ng

It will continuously generate pairs of private/public keys and try the
public key for pattern-matching hash.  To be recognized by other FEDAnet
nodes, first N bits of the hash must match the pattern 0xFEDAFEDAFE...
The number N is set individually on each node, but generaly it is unlikely
you'll be able to make any use of keys with N less than 20, and to run a
respectable node you should perhaps have a key with N=24 or higher.

As keys are found, the feda-ng program will save them in subdirs of
its working directory (the one where you launched it); the subdirs will be
named like 13, 16, 20 etc., according to the number N; every key is stored
in a text file named smth. like 49feb618794a8e1e4439 (exactly 20
hexadecimal digits) which is the node ID derived from the public key.  The
file contains something like this:

id          49feb618794a8e1e4439
preflen     11
secret      b9bc0c2ffa8b0cd0a71773603ad3663dd67dd790dded41053baebc4abaf23586
            f29e1b00a4f9461f94ece9ecf8fb17e78b66faa853b249feb618794a8e1e4439
public      f29e1b00a4f9461f94ece9ecf8fb17e78b66faa853b249feb618794a8e1e4439
yeshash     fec1481b69b3156b18dcab28fe9da3035a1f73fa9eecfdbc6725381545488a88

(in this example, N is only 11, so this key is not very useful; actually,
this example was created during one of the early test runs, the current
version wouldn't even bother to save such key).

Out of the box, the feda-ng program saves keys with N no less than 12, and
simply discards keys with shorter N.  Keys with N=12 (and even with N=19)
are not very useful, but dropping them all may make the impression the
program does nothing useful at all, which may be frustrating.  Having some
keys already, even not very useful in practice, you can at least see what
do they look like.  It takes several minutes for even a N=12 key to appear;
the exact time depends on your processor and your luck, as it is all
random.

As the program runs, it prints dots (.....), one dot per 32 keys generated
and tried.  When it saves a key, it prints a latin letter, 'A' for a key
with N=10, 'B' for a key witn N=11, etc.  If you use the -m flag to set the
minimum to something less than 10, then for such keys the corresponding
digit will be printed (e.g., '7' will mean N=7), but, well, you won't do
that, will you?  So, if you run the program out of the box with no flags,
digits and the 'A' and 'B' letters won't appear, 'C' will correspond to
N=12, 'D' to N=13, 'H' to N=17, 'K' to N=20 (so you're very lucky if you
see the 'K' on the screen), 'L' is for N=21, 'M' is for N=22, 'N' means
N=23, and if you see 'O' (or any of the later aplhabet letters, such as P,
Q, R...), feel free to stop the generation process: you have the N=24+ key.
Again, it all depends on your processor and your luck, but, well, expect
this to take several month.  On the other hand, a key with N=20 typically
takes only a day or two to generate.



MEMORY AND CPU CONSUMPTION

Every running instance of the feda-ng program takes a bit more than 256 MB
of your RAM (and it actually can't work in swap memory because the 256 MB
are all actively used by the hash computation), and if it has enough RAM,
it will take 100% of _one_ CPU.  Hardly you can find a single-CPU machine
nowadays (well, these multiple "cores" are separate CPUs from the
computational point of view), so you might want to run several instances of
feda-ng, e.g., in several xterms, or in virtual terminals provided by the
well-known screen program, or just in background, with output redirected to
/dev/null.  You can run as many of them as you want, only watch carefully
for your machine not using any swap; and they will happily run within one
directory, as they can't conflict on key files they save.  Use the 'top'
utility or the like to see for sure every instance you launched uses 100%
of CPU time (or close to that, like 97%).  If the indicated usage is lower,
consider removing some of your instances.

The feda-ng instances may be safely interrupted at any moment, all you
loose is the current hash computation, which only takes a small fraction of
a second.

On start, the program calls the system scheduler asking to reschedule it in
the SCHED_IDLE mode (which seems to be Linux-specific, so on non-Linux
systems you may need to add 'CONF="-DFEDA_NG_SCHED=0"' to disable this
feature), and if it succeeds, the program will never use your CPU when it
is needed for anything else.



SECURITY CONSIDERATIONS

Please remember the importance of the keys you generate.  The private key
of your node *IS* your node in some sense, because the node ID is derived
from it: actually, the ID is the last 10 bytes of your public key, which
is, in turn, _computed_ from your private key.  You can't therefore "change
the key" of your node, like you change your passwords and other
credentials; the only thing you can do is to give up your node and run
another one.

Technically you'll never need your master key to appear on a computer
connected to the Internet, and the best way to handle it is to REALLY
handle it away from any networking.  If you have an old laptop or even a
SBC which you can dedicate for signing your point keys (which is the only
operation you need your master key for), then use it.  Alternativaly, you
can have a live system on a USB flash, but make sure you boot your computer
from a cold stop and it is disconnected from everything but the power
source.

Please note that you don't need a computationally powerful machine for
regular key signing operations, you only need a lot of CPU time to
_generate_ the master key, this is a one-time operation (unless, of course,
you decide to change your node or have more than one of them).  However, to
be sure you master key didn't leak out, you should setup the machine up to
the point where the key can be generated (that is, the feda-ng program
works), and then disconnect the machine from any networks, permanently.
Once you get a key you're satisfied with, if you need for other purposes
the machine you used for the generation, then take the key away from it
(e.g., on a USB flash stick), then WIPE AND REINSTALL the machine
completely.  Only after that you can safely connect the former generation
machine to networks again.

And one more thing: you must remain the only person who has (or ever had)
any access to the master key.  In a worst possible case, there may be _two_
persons who ever _could_ access the key, and you must be absolutely
confident in the other person.  In case a third person (literally third,
after you being the first and someone else being the second) gets a chance
to access the key, please immediately close your node, issuing the "node
shutdown" broadcast request.



CHALLENGE-RESPONSE TABLES

Taking the hash is time- and memory-consuming.  Your node software needs to
perform this operation each time someone on the Internet claims to be a
previously-unknown node; going unrestricted, this may easily lead to a DoS
for your node.

There are several measures taken to prevent the DoS attack or at least make
it harder to perform.  One of the measures is implemented in the exchange
protocol which lets your node to ask the one who wants you to verify
his hash, to perform a hash computation on his own first.  The trick is
that you don't perform that computation, you only verify if your peer
performed it correctly.  For this to work, you need a supply of
pre-computed hashes for random values.  During the master key mining
process, you have to compute a lot of those hashes anyway, then why not to
save some of them for future use?

Just run the feda-ng program with an additional parameter -t, like

  ./feda-ng -t _table1

-- where ``_table1'' is the file name for the challenge-response table you
want to generate.

If you run several instances of the feda-ng program, USE DIFFERENT FILES!
There's no collision prevention measures, so running several instances of
feda-ng on the same table file would inevitably lead to corrupted records.
You'd better join the results to form a single table later, using the
feda-ct program.

Use ``feda-ct scan'' on the table files being generated to get an idea on
how many records are still unfilled.  The ``feda-ct cannibal'' command lets
you move the records from one table to another; only the records that can
fill empty slots of the first table, get moved (and zeroed within the
second table, so its rate may drop).

To fill the last hundreds of slots of a table, ``feda-ct fill'' may be
used.  Please note it generates challenges randomly for each empty slot,
and then computes hashes, which is slow.  Perhaps it is a good idea first
to wait for a table become like 98%-filled (which may take several days),
then try to cannibalize other tables (you can continue to fill them
later, using feda-ng), and only then, when ``feda-ct scan'' shows there are
no more than 100-200 empty slots, run the ``feda-ct fill'' command.

It is useful to create a lot of tables during your node generation.  Once a
table is ready, move it off your working directory and let the feda-ng
program to make yet another table.  Remember, your running node will only
need one table at a time, but it is very useful to replace the table
regularily.