list-class$ $@ 2dup bl skip nip -
    list-class$ off list-class$ $!
    s"   * " list-class$ $+! ;
: /ul 2drop cr
    list-class$ $free list-stack stack> list-class$ !
    list-class$ $@len 0= IF  cr  THEN ;
: li 2drop
    cr list-class$ $. ;
: /li 2drop ;
: h1 2drop ." # " ;
: /h1 2drop ."  #" cr cr ;
: h2 2drop ." ## " ;
: /h2 2drop ."  ##" cr cr ;
: h3 2drop ." ### " ;
: /h3 2drop ."  ###" cr cr ;

: blockquote 2drop
    br$ $@len 0= IF  "\\\n"  br$ $!  THEN
    "> " br$ $+! br$ $@ 1 /string type ;
: /blockquote 2drop
    br$ $@len 4 u> IF  br$ 2 2 $del  ELSE  br$ $free  THEN  cr cr ;
................................................................................
: span ( -- )
    a-params-class new >o r> o-stack >stack
    [: ['] a-params >body scan-vals ;] execute-parsing ;
: /span 2drop
    a-params:dispose o-stack stack> >r o> ;
synonym div span
: /div /span cr ;


synonym style span
synonym /style /span

object class{ table-params
    field: align$
    field: cellpadding$
    field: cellspacing$
................................................................................

$100 buffer: escape-chars
'\' escape-chars '*' + c!
'\' escape-chars '_' + c!
'\' escape-chars '\' + c!
'\' escape-chars '~' + c!
'\' escape-chars '[' + c!


: type-esc'd ( addr u -- )
    bounds ?DO
	I c@ dup escape-chars + c@ ?dup-IF  emit  THEN  emit
    LOOP ;

: type-nolf ( addr u -- )

    list-class$ $@ 2dup bl skip nip -
    list-class$ off list-class$ $!
    s"   * " list-class$ $+! ;
: /ul 2drop cr
    list-class$ $free list-stack stack> list-class$ !
    list-class$ $@len 0= IF  cr  THEN ;
: li 2drop
    cr list-class$ $@ 2 safe/string type ;
: /li 2drop ;
: h1 2drop ." # " ;
: /h1 2drop ."  #" cr cr ;
: h2 2drop cr ." ## " ;
: /h2 2drop ."  ##" cr cr ;
: h3 2drop cr ." ### " ;
: /h3 2drop ."  ###" cr cr ;

: blockquote 2drop
    br$ $@len 0= IF  "\\\n"  br$ $!  THEN
    "> " br$ $+! br$ $@ 1 /string type ;
: /blockquote 2drop
    br$ $@len 4 u> IF  br$ 2 2 $del  ELSE  br$ $free  THEN  cr cr ;
................................................................................
: span ( -- )
    a-params-class new >o r> o-stack >stack
    [: ['] a-params >body scan-vals ;] execute-parsing ;
: /span 2drop
    a-params:dispose o-stack stack> >r o> ;
synonym div span
: /div /span cr ;
synonym p div
synonym /p /div
synonym style span
synonym /style /span

object class{ table-params
    field: align$
    field: cellpadding$
    field: cellspacing$
................................................................................

$100 buffer: escape-chars
'\' escape-chars '*' + c!
'\' escape-chars '_' + c!
'\' escape-chars '\' + c!
'\' escape-chars '~' + c!
'\' escape-chars '[' + c!
'\' escape-chars '`' + c!

: type-esc'd ( addr u -- )
    bounds ?DO
	I c@ dup escape-chars + c@ ?dup-IF  emit  THEN  emit
    LOOP ;

: type-nolf ( addr u -- )

<h1>Encryption</h1>

<p>To protect privacy, everything is encrypted with the strongest encryption
available. The reasons for selecting the algorithms were:</p>

<h2>Key Exchange and Signatures</h2>
<ul>

<li>RSA: Reasonable (128bit) strength requires at least 3kbit key size;
factoring is not as hard as originally assumed; the algorithm are still above
polynomial, but way below brute force, and any further breakthrough will
require to increase the key size to unreasonable limits. With a 4kbit key (512
bytes per key), the connection setup information won't fit into the 1kB
packets.</li>
<li>Diffie-Hellman discrete logarithm has essentially the same strength as RSA.</li>
<li>Elliptic Curve Cryptography is still considered "strong", i.e. there is
only the very generic big/little step attack, which means a 256 bit key equals
128 bit strength.</li>
</ul>

<p>The selection therefore was Ed25519, a Edwards form variant of Dan
Bernstein's curve25519. &nbsp;Edwards form is notationally simpler and regular
than other curves, allowing more optimizations. &nbsp;The parameters of this
curve are known-good, following the "nothing up my sleeve" principle.</p>

<h3>Key Exchange Procedure</h3>

<p>The first phase of a key exchange uses ephemeral (one-time) keys. Let's call
the initiator Alice, and the connected device Bob:</p>
<ol>

<li>Alice generates a key pair, and sends Bob the public key, together with a
connection request.</li>
<li>Bob creates a key pair and sends Alice the public key. Using this public
and secret key, he generates a shared secret1, and uses that to encrypt his
permanent public key (used for authentication). An attacker can see the
ephemeral key, but not the permanent pubkey. &nbsp;Bob puts his state in an
encrypted string where only Bob knows the key, and sends this "ticket" back to
Alice. &nbsp;Receiving the ticket will actually open up the connection.</li>
<li>Alice receives both keys and can now create two shared secrets: secret1 is
the ephemeral secret, secret2 is the authentication secret. &nbsp;She sends her
authentication pubkey back to Bob encrypted with secret1. &nbsp;This allows Bob
to compute secret2. &nbsp;Furthermore, Alice sends back Bob's ticket and a
random per-connection seed for the symmetric keys; the ticket can be (in
theory) used to open several connections to Bob with a single packet (no reply
required).</li>
</ol>

<p>The general formula for ECC Diffie-Hellman key exchange is secret =
pk1*(sk2)&nbsp;= pk2*(sk1). For secret2, I modify this to avoid side-channel
attacks in the lengthy curve point computation, and use secret2 =
pka*(skb*secret1)&nbsp;= pkb*(ska*secret1). &nbsp;The scalar multiplication in
mod <i>l</i>&nbsp;(the number of curve points) is much faster than the curve
point computation, and is much less likely to leak information.</p>

<h2>Symmetric Crypto</h2>

<p>The requirement is AEAD: Authenticate and encrypt/decrypt together. &nbsp;Candidates
&nbsp;were:</p>
<ul>


<li>AES in CGM - this has two problems.</li>
<ol>
<li>CGM is not a secure hash, and the GF(2^n) field used gives &nbsp;security
level of only about 64 bits for 128 bits checksum.</li>
<li>AES uses a constant key, and therefore, side-channel attacks are more
likely to succeed.</li>
</ol>
<li>xsalsa/salsa20+poly1305: This uses a stream cipher and a GF(p) polynom,
which provides full 128 bit security for the 128 bit checksum, but the security
of the checksum depends on the encryption. &nbsp;There's a low risk that the
proof here is basing on wrong assumptions. &nbsp;As a stream cipher, there is
no constant key, so side-channel attacks are more difficult. &nbsp;This
combination wins over AES/CGM.</li>
<li>Keccak in duplex mode provides both encryption and strong authentication,
which does not depend on the encryption. &nbsp;The checksum is a keyed
plaintext checksum, so it actually protects the plain text, and proves
knowledge of the key at the same time. &nbsp;Verification of the packet is
possible without actually decrypting it (i.e. it <i>also</i>&nbsp;is a
ciphertext checksum). &nbsp;Strength is &gt;256 bits, providing a very high
margin. &nbsp;Furthermore, Keccak/SHA-3 is a universal crypto primitive, so
everything needed for symmetric crypto is done with just one primitive. &nbsp;Keccak
wins over xsalsa/salsa20+poly1305.</li>
</ul>

# Encryption #

To protect privacy, everything is encrypted with the strongest encryption
available. The reasons for selecting the algorithms were:

## Key Exchange and Signatures ##


* RSA: Reasonable (128bit) strength requires at least 3kbit key size;
  factoring is not as hard as originally assumed; the algorithm are still
  above polynomial, but way below brute force, and any further breakthrough
  will require to increase the key size to unreasonable limits. With a 4kbit
  key (512 bytes per key), the connection setup information won't fit into the
  1kB packets.
* Diffie-Hellman discrete logarithm has essentially the same strength as RSA.
* Elliptic Curve Cryptography is still considered "strong", i.e. there is only
  the very generic big/little step attack, which means a 256 bit key equals
  128 bit strength.


The selection therefore was Ed25519, a Edwards form variant of Dan Bernstein's
curve25519.  Edwards form is notationally simpler and regular than other
curves, allowing more optimizations.  The parameters of this curve are
known-good, following the "nothing up my sleeve" principle.

### Key Exchange Procedure ###

The first phase of a key exchange uses ephemeral (one-time) keys. Let's call
the initiator Alice, and the connected device Bob:


1. Alice generates a key pair, and sends Bob the public key, together with a
   connection request.
1. Bob creates a key pair and sends Alice the public key. Using this public
   and secret key, he generates a shared secret1, and uses that to encrypt his
   permanent public key (used for authentication). An attacker can see the
   ephemeral key, but not the permanent pubkey.  Bob puts his state in an
   encrypted string where only Bob knows the key, and sends this "ticket" back
   to Alice.  Receiving the ticket will actually open up the connection.
1. Alice receives both keys and can now create two shared secrets: secret1 is
   the ephemeral secret, secret2 is the authentication secret.  She sends her
   authentication pubkey back to Bob encrypted with secret1.  This allows Bob
   to compute secret2.  Furthermore, Alice sends back Bob's ticket and a
   random per-connection seed for the symmetric keys; the ticket can be (in
   theory) used to open several connections to Bob with a single packet (no
   reply required).


The general formula for ECC Diffie-Hellman key exchange is _secret =
pk1\*(sk2) = pk2\*(sk1)_. For secret2, I modify this to avoid side-channel
attacks in the lengthy curve point computation, and use _secret2 =
pka\*(skb\*secret1) = pkb\*(ska\*secret1)_.  The scalar multiplication in mod
_l_ (the number of curve points) is much faster than the curve point
computation, and is much less likely to leak information.

## Symmetric Crypto ##

The requirement is AEAD: Authenticate and encrypt/decrypt


together.  Candidates were:

* AES in CGM — this has two problems.

  1. CGM is not a secure hash, and the GF(2^n) field used gives  security
     level of only about 64 bits for 128 bits checksum.
  2. AES uses a constant key, and therefore, side-channel attacks are more
     likely to succeed.

* xsalsa/salsa20+poly1305: This uses a stream cipher and a GF(p) polynom,
  which provides full 128 bit security for the 128 bit checksum, but the
  security of the checksum depends on the encryption.  There's a low risk that
  the proof here is basing on wrong assumptions.  As a stream cipher, there is
  no constant key, so side-channel attacks are more difficult.  This
  combination wins over AES/CGM.
* Keccak in duplex mode provides both encryption and strong authentication,
  which does not depend on the encryption.  The checksum is a keyed plaintext
  checksum, so it actually protects the plain text, and proves knowledge of
  the key at the same time.  Verification of the packet is possible without
  actually decrypting it (i.e. it _also_ is a ciphertext checksum).  Strength
  is >256 bits, providing a very high margin.  Furthermore, Keccak/SHA-3 is a

  universal crypto primitive, so everything needed for symmetric crypto is
  done with just one primitive.  Keccak wins over xsalsa/salsa20+poly1305.

<h1>Key Format</h1>

<div>The public key is the primary key (the ID) of a key. &nbsp;Other fields
are:</div>

<div>
<ul>
<li>Private key (for secret key ring) - the private key may be protected by a
pass phrase and a pass file</li>
<li>Nickname (for humans)</li>
<li>Full name (for humans)</li>
<li>Creation and expiration dates</li>
</ul>

<h2>Signatures</h2>

<div>Keys may be signed, we treat key signatures as separate entities. &nbsp;A
signature consists of</div>

<div>
<ul>
<li>The pubkey of the signed key</li>
<li>The pubkey of the signer</li>
<li>The "digest", the cryptographic checksum that proves that the signer has
signed the key</li>
</ul></div>

<div>This feature will be implemented when Dan Bernstein integrates signatures
into NaCl; maybe a bit earlier, since the code for these signatures is already
tested.</div></div>

# Key Format #

The public key is the primary key (the ID) of a key.  Other fields are:




* Private key (for secret key ring) — the private key may be protected by a
  pass phrase and a pass file
* Nickname (for humans)
* Full name (for humans)
* Creation and expiration dates


## Signatures ##

Keys may be signed, we treat key signatures as separate entities.  A signature
consists of



* The pubkey of the signed key
* The pubkey of the signer
* The “digest”, the cryptographic checksum that proves that the signer has
  signed the key


This feature will be implemented when Dan Bernstein integrates signatures
into NaCl; maybe a bit earlier, since the code for these signatures is already
tested.

revocation is declaring the successor key, which reestablishs trust. To do
that, you must actually proof that you are the legitimate owner of the exposed
secret key, so how do you do that?  After all, the adversary has stolen
it!

Therefore, the requirements are as follows:

  + Only the creator of the secret key can revoke it
  + A thief of the secret key can't (i.e. further information is necessary)
  + Revocation must present a trustworthy replacement key
  + Third parties must trust both the revocation and the replacement key
    without another trustworthy instance, i.e. trusting only their communication
    partner

## Key Creation ##

I create two random number s1 and s2.  Using these numbers, I create
pubkeys p1=[s1]base and p2=[s2]base.  Points can be compressed to a
32 byte number using the compress() function, and then can be treated
as scalar values like [s].  I compute [s]=[s1×compress(p2)] as "work
secret" (i.e. the secret key that is proving my identity), and
p=[s]base, my pubkey.  I publish p and p1, which together are stored
as identity.  The assumption is that p1 can't be reversed to get s1,
and p won't reveal s.  An attacker who stole s can't guess s1, because
he doesn't have p2, and so it's even more difficult to get s2.  An
attacker who stole s can generate a new pair of p1, p2, but that would
give him a different identity (a suspicious identity, though).  After
generating the key, s1 is destroyed; it is no longer needed, though it
can be recomputed using s and p2 and the extended euclidean algorithm.

## Proof of Creation ##

I keep s2 as offline copy (it's just 64 hex digits or 40 base85
characters), and s as protected online copy in my device; s is subject
to attacks and backdoors, and therefore at risk.  To revoke a key, I
publish p2, which the recipient can validate by [compress(p2)]p1==p.

To sign a new key, I use s2 as signature key, i.e. the recipient can
use the just published p2 to verify the transition to the replacement
key.  Of course, the new key also has a signature with s, the old key.
The format of the revocation attribute is actually ‹new pubkeys: pnew,
p1new› ‹p2, sig using s2› ‹sig using snew› ‹date:never› ‹sig using s›.

revocation is declaring the successor key, which reestablishs trust. To do
that, you must actually proof that you are the legitimate owner of the exposed
secret key, so how do you do that?  After all, the adversary has stolen
it!

Therefore, the requirements are as follows:

* Only the creator of the secret key can revoke it
* A thief of the secret key can't (i.e. further information is necessary)
* Revocation must present a trustworthy replacement key
* Third parties must trust both the revocation and the replacement key
  without another trustworthy instance, i.e. trusting only their communication
  partner

## Key Creation ##

I create two random number s1 and s2.  Using these numbers, I create
pubkeys p1=\[s1]base and p2=\[s2]base.  Points can be compressed to a
32 byte number using the compress() function, and then can be treated
as scalar values like \[s].  I compute \[s]=\[s1×compress(p2)] as "work
secret" (i.e. the secret key that is proving my identity), and
p=\[s]base, my pubkey.  I publish p and p1, which together are stored
as identity.  The assumption is that p1 can't be reversed to get s1,
and p won't reveal s.  An attacker who stole s can't guess s1, because
he doesn't have p2, and so it's even more difficult to get s2.  An
attacker who stole s can generate a new pair of p1, p2, but that would
give him a different identity (a suspicious identity, though).  After
generating the key, s1 is destroyed; it is no longer needed, though it
can be recomputed using s and p2 and the extended euclidean algorithm.

## Proof of Creation ##

I keep s2 as offline copy (it's just 64 hex digits or 40 base85
characters), and s as protected online copy in my device; s is subject
to attacks and backdoors, and therefore at risk.  To revoke a key, I
publish p2, which the recipient can validate by \[compress(p2)]p1==p.

To sign a new key, I use s2 as signature key, i.e. the recipient can
use the just published p2 to verify the transition to the replacement
key.  Of course, the new key also has a signature with s, the old key.
The format of the revocation attribute is actually ‹new pubkeys: pnew,
p1new› ‹p2, sig using s2› ‹sig using snew› ‹date:never› ‹sig using s›.

The documentation is work in progress. The seven layers of net2o are not
equal to the ISO-OSI layers, but this layering provides a familiar starting
point:

1. Physical layer — this is not part of net2o itself.
2. [Topology](topology.md)
3. [Encryption](encryption.wiki)
4. [Flow Control](flow-control.md)
5. [Commands](commands.md)
6. [Distributed Data](distributed-data.wiki)
7. [Applications](applications.wiki)

## Videos & Presentations ##

................................................................................
## Discussions ##

* The [pki](pki.md) problem
* [Client authentication](client-auth.md)
* [Handover](handover.wiki)
* [Ack cookies](ackcookies.wiki)
* [Random number seat belts](rng.md)
* [Key format](key-format.wiki)
* [Key revocation](key-revocation.md)
* [NSA backdoor](nsa-backdoor.md)
* [Data retention](data-retention.md)
* [Onion Routing](onion-routing.md)
* [Threat Model](threat-model.md)
* [What it's not for](whatnotfor.md)
* [Nettie logo](nettie.md)
* [$quid CryptoCurrency](squid.md)
* [Guidelines of Conduct](guidelines.md)

[de](/net2o/wiki?name=net2o.de)
[中文](net2o.zh.md)

The documentation is work in progress. The seven layers of net2o are not
equal to the ISO-OSI layers, but this layering provides a familiar starting
point:

1. Physical layer — this is not part of net2o itself.
2. [Topology](topology.md)
3. [Encryption](encryption.md)
4. [Flow Control](flow-control.md)
5. [Commands](commands.md)
6. [Distributed Data](distributed-data.wiki)
7. [Applications](applications.wiki)

## Videos & Presentations ##

................................................................................
## Discussions ##

* The [pki](pki.md) problem
* [Client authentication](client-auth.md)
* [Handover](handover.wiki)
* [Ack cookies](ackcookies.wiki)
* [Random number seat belts](rng.md)
* [Key format](key-format.md)
* [Key revocation](key-revocation.md)
* [NSA backdoor](nsa-backdoor.md)
* [Data retention](data-retention.md)
* [Onion Routing](onion-routing.md)
* [Threat Model](threat-model.md)
* [What it's not for](whatnotfor.md)
* [Nettie logo](nettie.md)
* [$quid CryptoCurrency](squid.md)
* [Guidelines of Conduct](guidelines.md)

[de](/net2o/wiki?name=net2o.de)
[中文](net2o.zh.md)