[nncp.git] / doc / usecases.texi

@node Use cases
@unnumbered Use cases

See also this page @ref{Сценарии, on russian}.

@menu
* Occasional connection to mail server: UsecaseMail
* Lightweight fast POP3/IMAP4 replacement: UsecasePOP
* Unreliable/expensive communication link: UsecaseUnreliable
* Slow/expensive link for high-volume data, bad QoS: UsecaseQoS
* Extreme terrestrial environments, no link: UsecaseNoLink
* One-way broadcasting communications: UsecaseBroadcast
* Satellite links: UsecaseSatelliteLinks
* Private, isolated MitM/Sybil-resistant networks: UsecaseF2F
* Highly secure isolated air-gap computers: UsecaseAirgap
* Network censorship bypassing, health: UsecaseCensor
* Reconnaissance, spying, intelligence, covert agents: UsecaseSpy
* Cheap night transfers: UsecaseCaller
* Multicast flooding transmission: UsecaseMulticast
@end menu

@node UsecaseMail
@section Occasional connection to mail server

Assume that you have got your own @url{http://www.postfix.org/,
Postfix}/@url{http://www.exim.org/, Exim} SMTP server connected to the
Internet. But you read and write emails on your notebook, that is
connected to it just from time to time. How can you flush buffered mail
queues when your notebook is connected?

One possibility is to log in and run something like @command{postqueue
-f}, but by default you have got only several days so and sender will
receive notification emails that his messages still are not delivered
yet. Also you must have secure link (SSH, VPN, etc).

Another possibility is to use POP3/IMAP4 servers, but this is too
overcomplicated and bloated for the simple task. Not an option.
@url{https://en.wikipedia.org/wiki/KISS_principle, KISS}!

Just tell both of your Postfix/Exim (on the server and notebook) to drop
email as a mail via NNCP (@ref{nncp-exec}) to specified node.

More information for Postfix is @ref{Postfix, here} and for Exim is
@ref{Exim, here}. All mail will be stored in NNCP @ref{Spool, spool},
that after exchanging and tossing will call local @command{sendmail}
command to deliver them just like that happened on the same machine.

@node UsecasePOP
@section Lightweight fast POP3/IMAP4 replacement

@ref{nncp-daemon} can be connected with @ref{nncp-caller} for a long
time -- it can create TCP connection that lasts for many hours. When
SMTP server receives mail, it will call @ref{nncp-exec} creating an
outbound encrypted packet. Daemon checks outbound directory each second
and immediately sends notification about undelivered packets to remote
side, that also downloads it at once.

There are only dozens of bytes notifying about incoming packets, dozens
of bytes telling to download those packets. Mail packets are compressed
(POP3 and IMAP4 as a rule do not). You have lightweight, compressed,
low-delay, reliable link for the mail with strong encryption and mutual
sides authentication!

@node UsecaseUnreliable
@section Unreliable/expensive communication link

Assume that you have got slow modem/radio/cellular link that frequently
disconnects and causes TCP timeouts. Not all HTTP servers support file
download continuation. SMTP does not support resuming at all and heavy
messages is problematic to retrieve. Moreover, each disconnect leads to
the same data retransmission again, that can not be afforded sometimes.

Just send your @ref{nncp-exec, mail} and @ref{nncp-file, files} through
NNCP. You can use either offline delivery methods -- read about them in
the next section, or you can use included NNCP @ref{nncp-daemon, TCP
daemon}.

The command:

@example
$ nncp-file file_i_want_to_send bob:
$ nncp-file another_file bob:movie.avi
@end example

will queue two files for sending to @emph{bob} node. Fire and forget!
Now this is daemon's job (or offline transfer) to send this files part
by part to remote system when it is available.

@node UsecaseQoS
@section Slow/expensive link for high-volume data, bad QoS

Assume that you can give your relatively cheap 2 TiB removable hard
drive to someone each day at the morning (and take it back at the
evening). This equals to 185 Mbps good quality (without any speed
degradation) link in single direction. What about more and bigger hard
drives? This type of data exchange is called
@url{https://en.wikipedia.org/wiki/Sneakernet, sneakernet}/floppynet.

NNCP allows traffic @ref{Niceness, prioritizing}: each packet has
niceness level, that will guarantee that it will be processed earlier or
later than the other ones. Nearly all commands has corresponding option:

@example
$ nncp-file -nice FLASH myfile node:dst
$ nncp-xfer -nice PRIORITY /mnt/shared
$ nncp-call -nice NORMAL bob
[...]
@end example

Huge files could be split on smaller @ref{Chunked, chunks}, giving
possibility to transfer virtually any volumes using small capacity
storages.

You can also use CD-ROM and tape drives:

@example
$ nncp-bundle -tx bob | cdrecord -tao -
$ nncp-bundle -tx bob | dd of=/dev/sa0 bs=10240
@end example

@node UsecaseNoLink
@section Extreme terrestrial environments, no link

This is some kind of too slow link. Offline delivery methods is the only
choice. Just send files as shown in previous section, but use removable
media for transferring packets to other nodes.

Assume that you send two files to @emph{bob} node. Insert USB storage
device (SD is preferable!), mount it and run @ref{nncp-xfer}:

@example
$ nncp-xfer -node bob /media/usbstick
@end example

to copy all outbound packets related to @emph{bob}. Use @option{-mkdir}
option to create related directory on USB/SD storage if they are missing
(for example when running for the first time).

If you use single storage device to transfer data both to @emph{bob} and
@emph{alice}, then just omit @option{-node} option to copy all available
outgoing packets.

@example
$ nncp-xfer /media/usbstick
@end example

Unmount it and transfer storage to Bob and Alice. When they will insert
it in their computers, they will use exactly the same command:

@example
$ nncp-xfer /media/usbstick
@end example

to find all packets related to their node and copy them locally for
further processing. @command{nncp-xfer} is the only command used with
removable devices.

@node UsecaseBroadcast
@section One-way broadcasting communications

Sometimes you have got high-bandwidth but unidirectional link, for
example, satellite's broadcasting signal. You are not able to use online
@ref{Sync, synchronization protocol} because it requires mutual interaction.

You can use @ref{Bundles, bundles} and stream them above. They are just
a sequence of @ref{Encrypted, encrypted packets} you can catch on.

@example
$ nncp-bundle -tx alice bob eve ... | command to send broadcast
$ command to receive broadcast | nncp-bundle -rx
@end example

With built-in packet duplicates detection ability, you can retransmit
your broadcasts from time to time, to increase chances the recipient
will catch them by regular stream listening.

@node UsecaseSatelliteLinks
@section Satellite links

Satellite links have @strong{very} high delays together with high
bandwidths. You can send several megabits of data per second, but they
will reach the remote side only after half a second!
Most file sharing protocols like
@url{https://en.wikipedia.org/wiki/Files_transferred_over_shell_protocol, FISH},
@url{https://en.wikipedia.org/wiki/FTP, FTP},
@url{https://en.wikipedia.org/wiki/Secure_copy, scp},
@url{https://en.wikipedia.org/wiki/XMODEM, XMODEM}
will perform very badly because of round-trips quantity. Each file
transmission explicitly generates request and acknowledgement packets
that are send over the link. Remote side won't do anything until it
receives them. Moreover not all protocols allow duplex data
transmission (when both sides are sending data simultaneously).

NNCP's @ref{Sync, synchronization protocol} (SP) tries to mitigate all
that issues by reducing number of round-trips, number of packets passing
through. All file lists, file download requests are grouped together
(pipelined) in one huge packet. Only transmission halt and successful
file download acknowledgements are sent explicitly. SP could be asked
only either to upload or download packets for our node. SP could ignore
files with low priority. Full files listing is passing even during the
handshake procedure.

@node UsecaseF2F
@section Private, isolated MitM/Sybil-resistant networks

All Internet connections can be eavesdropped and forged. You
@strong{have to} to use encryption and authentication for securing them.
But it is very hard to secure metadata, that leaks during each online
session. When you start your shiny new software server be sure that
there could be huge quantity of bogus peers trying to perform
@url{https://en.wikipedia.org/wiki/Sybil_attack, Sybil attack}. Opennet
peer-to-peer networking is dangerous thing to do.

The most popular cryptographic protocol in Internet is
@url{https://en.wikipedia.org/wiki/Transport_Layer_Security, TLS} that
is very hard to implement correctly and hard to configure for mutual
participants authentication. Not all TLS configurations and related
protocols provide @url{https://en.wikipedia.org/wiki/Forward_secrecy,
forward secrecy} property -- all previously intercepted packets could be
read if private keys are compromised.

Friend-to-friend networks, darknets can mitigate risks related to fake
and forged nodes. However they are harder to support and require more
time to be done right.

NNCP's @ref{nncp-daemon, TCP daemon} uses
@url{http://noiseprotocol.org/, Noise-IK} protocol to mutually
authenticate peers and provide effective (both participants send payload
in the very first packet) secure transport with forward secrecy
property.

@example
$ nncp-daemon -bind "[::]":5400
@end example

will start TCP daemon listening on all interfaces for incoming
connections.

@example
$ nncp-call bob
@end example

will try to connect to @emph{bob}'s node known TCP addresses (taken from
configuration file) and send all related outbound packets and retrieve
those the Bob has. All interrupted transfers will be automatically
resumed.

Ability to do @ref{MCD, multicast nodes discovery} of participant in
IPv6 networks allows complete ignorance of network addresses specifying.

@node UsecaseAirgap
@section Highly secure isolated air-gap computers

If you worry much about security, then air-gapped computer could be the
only choice you can afford. Computer without any modems, wired and
wireless networks. Obviously the only possibility to exchange mail and
files is to use physically removable storage devices like CD-ROM, hard
drive, SD, tape and USB flash drives (@strong{worst} choice, due to
those devices complexity).

Presumably you have got another own hop before that computer: another
intermediate node which performs basic verification of retrieved storage
devices, possibly by rewriting the data from USB/hard drives to CD-RWs.

NNCP supports packets relying (transitioning) out-of-box.

@verbatim
neigh: {
  bob: {
    [...]
    addrs: {
      lan: "[fe80::5400%igb0]:5400"
    }
  }
  bob-airgap:
    [...]
    via: ["bob"]
  }
}
@end verbatim

That @ref{Configuration, configuration file} tells that we have got two
known neighbours: @emph{bob} and @emph{bob-airgap}. @emph{bob} can be
reached via online connection using @emph{lan} address.
@emph{bob-airgap} can be reached by sending intermediate relay packet
through the @emph{bob}.

Any command like @command{nncp-file myfile bob-airgap:} will
automatically create an encapsulated packet: one for the destination
endpoint, and other carrying it for intermediate relaying node.

Pay attention that relaying node knows nothing about the packet inside,
but just its size and priority. Transition packets are encrypted too:
using well-known @url{https://en.wikipedia.org/wiki/Onion_routing, onion
routing} technology. @emph{bob} can not read @emph{bob-airgap}'s packets.

@node UsecaseCensor
@section Network censorship bypassing, health

This is some kind of bad link too. Some governments tend to forbid
@strong{any} kind of private communication between people, allowing only
entertainment content delivering and popular social networks access
(that are already bloated with advertisements, locally executed
@url{https://www.gnu.org/philosophy/free-sw.html, proprietary}
JavaScript code (for spying on user activities, collect data on them),
shamelessly exploiting the very basic human need of communication).

This is their natural wish. But nobody forces you to obey huge
corporations like Apple, Google or Microsoft. It is your choice to
create an isolated friend-to-friend network with piles of harmless
content and private messaging. Only predators silently watch for their
victims in mammals world -- it harms your health being watched and
feeling that you are the victim that has already done something wrong.

@node UsecaseSpy
@section Reconnaissance, spying, intelligence, covert agents

Those guys know how Internet is a dangerous place incompatible with
privacy. They require quick, fast dropping and picking of data. No
possibility of many round-trips -- just drop the data, fire-and-forget.
It could be either removable media again and/or
@url{https://en.wikipedia.org/wiki/USB_dead_drop, USB dead drops},
@url{https://en.wikipedia.org/wiki/PirateBox, PirateBox}es,
@url{https://en.wikipedia.org/wiki/Short-range_agent_communications, SRAC}.
Short lived short range networks like Bluetooth and WiFi can also
be pretty fast, allowing to quickly fire chunks of queued packets.

Very important property is that compromising of those dead drops and
storages must be neither fatal nor even dangerous. Packets sent through
the network and exchanged via those devices are end-to-end
@ref{Encrypted, encrypted} (but unfortunately lacking forward secrecy).
No filenames, mail recipients are seen.

All node communications are done with so-called @ref{Spool, spool} area:
directory containing only those unprocessed encrypted packets. After
packet transfer you still can not read any of them: you have to run
another stage: @ref{nncp-toss, tossing}, that involves your private
cryptographic keys. So even if your loose your computer, storage devices
and so on -- it is not so bad, because you are not carrying private keys
with it (don't you?), you do not "toss" those packets immediately on the
same device. Tossing (reading those encrypted packets and extracting
transferred files and mail messages) could and should be done on a
separate computer (@ref{nncp-cfgmin} command could help creating
configuration file without private keys for that purpose).

If you really want to carry your private keys, then @ref{nncp-cfgenc}
command will be able to encrypt your configuration file. Passphrase you
enter is strengthened with both CPU and memory hard function.

@node UsecaseCaller
@section Cheap night transfers

Your Internet/telephone traffic price can vary, depending on daytime.
Night calls/connections could be twice as cheaper. You wish to send your
files at that time, but keep high priority email infrequently passing
through in anytime. Also you wish to pass any kind of traffic when the
node is available through the LAN.

You can easily set your preferences in @ref{Call, call
configurations} for @ref{nncp-caller} command used in online
communications.

@verbatim
neigh: {
  [...]
  some-node: {
    [...]
    addrs: {
      lan: "[fe80::be5f:f4ff:fedd:2752%igb0]:5400"
      wan: "some-node.com:5400"
    }
    calls: [
      {
        cron: "*/1 * * * *"
        addr: lan
        nice: MAX
        onlinedeadline: 3600
      },
      {
        cron: "*/10 * * * *"
        addr: wan
        nice: PRIORITY
        xx: rx
      },
      {
        cron: "*/1 0-7 * * *"
        addr: wan
        nice: BULK
        onlinedeadline: 3600
        maxonlinetime: 3600
      },
    ]
  }
}
@end verbatim

@node UsecaseMulticast
@section Multicast flooding transmission

Do you need to send single mail message or file to many recipients at
once? For example an update of some program, network participants list
or available files for freqing? But you are not connected directly to
each of them?

@verbatim
   A-------->E---->F    A -> B C E
  / \        |\    ^    C -> H J
 /   \       |  \  |    E -> D F G
v     v      v    \v    D -> G
B     C      D---->G    J -> K
     / \     ^    /     K -> D G
    /   \    |   /
   v     v   v  /
   H     J<->K<-
@end verbatim

NNCP has @ref{Multicast, multicast} packets format, allowing you to
flood transmission of the single packet to multiple recipients.
@strong{A} sends packet to three destinations. @strong{C} sends it to
the two nodes next. @strong{E} sends it to three. Some participants may
receive multiple copies of the same packet, like @strong{D}, @strong{J},
@strong{G}, @strong{F}, but that copies will be just ignored. If
@strong{B} sends packet to single known to him @strong{A}, then that
packet will be distributed among all other multicast area subscribers.

Moreover those multicast packets are encrypted and require key knowledge
for reading. But that does not prevent their relaying! Also you are not
required to know sender's public keys. That way you can easily create
echo-conferences for files or commands (like mail message delivering)
transmission.

Let's create keys for the new multicast area:

@example
$ nncp-cfgnew -area filelists -nocomments
areas: @{
  filelists: @{
    id: TOU5TKOW4JBIZJBX63D4776C72FMWDAUAUSZNJX4DFOITVYQ5ZQA
    pub: DSHL5O6BK2R3QKJAIJ7BC4UIGE73EC2LJPOV3VTS44KYOTUQYZLA
    prv: AYD5FAA4GDDSAD5N65NJLLFS6TG2NSPQ46KAQO5U722JLVG34SOQ
  @}
@}
@end example

and send that keypair everybody who wants to read that area.
For intermediaries willing to relay packets on, but that should not read
them, you just need to send area's identity. For example @strong{A} adds
to his configuration:

@example
areas: @{
  filelists: @{
    id: TOU...
    pub: DSH...
    prv: AYD...
    subs: ["B", "C", "E"]
    incoming: /home/A/areas/filelists
  @}
@end example

and @strong{E}, that will be relaying intermediary (as we decided):

@example
areas: @{
  filelists: @{
    id: TOU...
    subs: ["D", "F", "G"]
  @}
@end example

After you distributed the knowledge about @code{nodelist} multicast
area, you can share @ref{FreqIndex, file lists}:

@example
$ nncp-file tree-of-A-20210715.txt.zst area:filelists:
$ nncp-toss -node self
@end example