"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/Crypto.md" between
n2n-2.8.tar.gz and n2n-3.0.tar.gz

About: n2n is a layer-two peer-to-peer virtual private network (VPN) which allows bypassing intermediate firewalls.

Crypto.md  (n2n-2.8):Crypto.md  (n2n-3.0)
skipping to change at line 14 skipping to change at line 14
### Overview ### Overview
Payload encryption currently comes in four different flavors using ciphers of di fferent origins. Supported ciphers are enabled using the indicated command line option: Payload encryption currently comes in four different flavors using ciphers of di fferent origins. Supported ciphers are enabled using the indicated command line option:
- Twofish in CTS mode (`-A2`) - Twofish in CTS mode (`-A2`)
- AES in CBC mode (`-A3`) - AES in CBC mode (`-A3`)
- ChaCha20 (CTR) (`-A4`) - ChaCha20 (CTR) (`-A4`)
- SPECK in CTR mode (`-A5`) - SPECK in CTR mode (`-A5`)
To renounce encryption, `-A1` enables the so called `null_transform` transmittin
g all payload data unencryptedly.
The following chart might help to make a quick comparison and decide what cipher to use: The following chart might help to make a quick comparison and decide what cipher to use:
| Cipher | Mode | Block Size | Key Size | IV length |Speed | Built-In | Origin | | Cipher | Mode | Block Size | Key Size | IV length |Speed | Built-In | Origin |
| :---: | :---:| :---: | :---: | :---: |:---: | :---: | --- | | :---: | :---:| :---: | :---: | :---: |:---: | :---: | --- |
|Twofish | CTS | 128 bits | 256 bit | 32 bit | - | Y | |Twofish | CTS | 128 bits | 256 bit | 128 bit | -..O | Y |
Bruce Schneier | Bruce Schneier |
|AES | CBC | 128 bits | 128, 192, 256 bit| 64 bit | O..+ | N | |AES | CTS | 128 bits | 128, 192, 256 bit| 128 bit | O..+ | Y |
Joan Daemen, Vincent Rijmen, NSA-approved | Joan Daemen, Vincent Rijmen, NSA-approved |
|ChaCha20| CTR | Stream | 256 bit | 128 bit | +..++| N | |ChaCha20| CTR | Stream | 256 bit | 128 bit | +..++| Y |
Daniel J. Bernstein | Daniel J. Bernstein |
|SPECK | CTR | Stream | 256 bit | 128 bit | ++ | Y | NSA | |SPECK | CTR | Stream | 256 bit | 128 bit | ++ | Y | NSA |
The two block ciphers Twofish and AES are used in CTS mode (Twofish) and CBC mod e(AES). AES requires a padding which results in encrypted payload size modulo th eir blocksize. Sizewise, this could be considered as a disadvantage. On the othe r hand, stream ciphers need a longer initialization vector (IV) to be transmitte d with the cipher. The two block ciphers Twofish and AES are used in CTS mode.
Note that AES and ChaCha20 are available only if n2n is compiled with openSSL su pport. n2n will work well without them offering the respectively reduced choice of remaining built-in ciphers (Twofish, SPECK). n2n has all four ciphers built-in as basic versions. Some of them optionally com pile to faster versions by the means of available hardware support (AES-NI, SSE, AVX – please see the [Building document](./Building.md) for details. Depending on your platform, AES and ChaCha20 might also draw notable acceleration from opt ionally compiling with openSSL 1.1 support.
### Twofish The`-k <key>` command line parameter supplies the key. As even non-privileged us ers might get to see the command line parameters (try `ps -Af | grep edge`), the key can also be supplied through the `N2N_KEY` environment variable: `sudo N2N_ KEY=mysecretpass edge -c mynetwork -a 192.168.100.1 -f -l supernode.ntop.org:777 7`.
This implementation prepends a 32 bit random value to the plain text. In the `sr c/transform_tf.c` file, it is called `nonce`. In CBC mode, this basically has th e same effect as a respectively shorter IV. Providing `-k <key>` without specifying any cipher by `-A_` will default to AES encryption.
Twofish requires no padding as it employs a CBC/CTS scheme which can send out pl aintext-length ciphertexts. The scheme however has a small flaw in handling mess ages shorter than one block, only low-level programmer might encounter this. To renounce encryption, `-A1` enables the so called `null_transform` transmittin g all payload data unencryptedly. Omitting `-A_` and not providing a key through `-k <key>` shows the same effect.
Twofish is the slowest of the ciphers present. ### Twofish
_We might try to find a faster implementation._ This implementation prepends a 128 bit random value to the plain text. Its size is adjustable by changing the `TF_PREAMBLE_SIZE` definition found in `src/transf orm_tf.c`. It defaults to TF_BLOCK_SIZE (== 16). As CTS uses underlying CBC mode , this basically has the same effect as a respectively shorter IV. However, this flexibility does not come for free as an additional block needs to be encrypted .
### AES Twofish requires no padding as it employs a CBC/CTS scheme which can send out pl aintext-length ciphertexts. The scheme however has a small flaw in handling mess ages shorter than one block, only low-level programmer might encounter this.
AES uses the standard way of an IV but it does not neccessarily transmit the ful l IV along with the packets. The size of the transmitted part is adjustable by c hanging the `TRANSOP_AES_IV_SEED_SIZE` definition found in `src/transform_aes.c` . It defaults to 8 meaning that 8 bytes (of max 16) are transmitted. The remaini ng 8 bytes are fixed, key-derived material is used to fill up to full block size . A single AES-ECB encryption step is applied to these 16 bytes before they get used as regular IV for AES-CBCing the payload. On Intel CPUs, Twofish usually is the slowest of the ciphers present. However, o n Raspberry Pi 3B+, Twofish was observed to be faster than AES-CTS. Your mileage may vary. Cipher speed's can be compared running the `tools/n2n-benchmark` tool .
Padding to the last block happens by filling `0x00`-bytes and indicating their n umber as the last byte of the block. This could lead to up to 16 extra bytes. ### AES
AES relies on openSSL's `evp_*` interface which also offers hardware acceleratio n where available (SSE, AES-NI, …). It however is slower than the following stre am ciphers because the CBC mode cannot compete with the optimized stream ciphers . AES also prepends a random value to the plaintext. Its size is adjustable by cha nging the `AES_PREAMBLE_SIZE` definition found in `src/transform_aes.c`. It defa ults to AES_BLOCK_SIZE (== 16). The AES scheme uses a CBC/CTS scheme which can s end out plaintext-length ciphertexts as long as they are one block or more in le ngth.
_Perhaps, AES-CTR being a stream cipher could have competed with the stream ciph ers._ Apart from n2n's plain C implementation, Intel's AES-NI is supported – again, pl ease have a look at the [Building document](./Building.md). In case of openSSL s upport its `evp_*` interface gets used which also offers hardware acceleration w here available (SSE, AES-NI, …). It however is slower than the following stream ciphers because the CBC mode cannot compete with the optimized stream ciphers.
_Another possible extension would be to bring CTS mode to AES in some future ver sion, just to avoid unneccessary weight gains from padding. CTS mode works well starting with plain texts from one block plus. So, we might revert back to the T wofish-way of IV handling with a full block IV._ This cipher's different key-sizes are triggered by the length of the user-provid ed key: 22 characters or less make n2n use AES-128, between 23 and 32 characters lead to AES-192, and 33 or more characters trigger AES-256.
### ChaCha20 ### ChaCha20
ChaCha20 was the first stream cipher supported by n2n. ChaCha20 was the first stream cipher supported by n2n.
It also relies on openSSL's `evp_*` interface. It does not use the Poly1305 mess age tag from the same author though. Whole packet's checksum will be handled in the header (see below). In addition to the basic C implementation, an SSE version is offered. If compile d with openSSL support, ChaCha20 is provided via the `evp_*` interface. It is no t used together with the Poly1305 message tag from the same author though. Whole packet's checksum will be handled in the header (see below).
The random full 128-bit IV is transmitted in plain. The random full 128-bit IV is transmitted in plain.
ChaCha20 usually performs faster than AES-CBC. ChaCha20 usually performs faster than AES-CTS.
### SPECK ### SPECK
SPECK is recommended by the NSA for offical use in case AES implementation is no t feasible due to system constraints (performance, size, …). The block cipher is used in CTR mode making it a stream cipher. The random full 128-bit IV is trans mitted in plain. SPECK is recommended by the NSA for offical use in case AES implementation is no t feasible due to system constraints (performance, size, …). The block cipher is used in CTR mode making it a stream cipher. The random full 128-bit IV is trans mitted in plain.
On Intel CPUs, SPECK performs even faster than openSSL's ChaCha20 as it takes ad vantage of SSE4 or AVX2 if available (compile using `-march=native`). On Raspber ry's ARM CPU, it is second place behind ChaCha20 and before AES-CBC. On modern Intel CPUs, SPECK performs even faster than openSSL's ChaCha20 as it t akes advantage of SSE4, AVX2, or AVX512 if available. On Raspberry's ARM CPU, it is second place behind ChaCha20 and before Twofish.
### Random Numbers ### Random Numbers
Throughout n2n, pseudo-random numbers are generated for several purposes, e.g. r andom MAC assignment and the IVs for use with the various ciphers. Regarding IVs , especially for using in the stream ciphers, the pseudo-random numbers shall be as collision-free as possible. n2n uses an implementation of XORSHIFT128+ which shows a periodicity of 2¹²⁸. Throughout n2n, pseudo-random numbers are generated for several purposes, e.g. r andom MAC assignment and the IVs for use with the various ciphers. Regarding IVs , especially for using in the stream ciphers, the pseudo-random numbers shall be as collision-free as possible. n2n uses an implementation of XORSHIFT128+ which shows a periodicity of 2¹²⁸.
Its initialization relies on seeding with a value as random as possible. Various sources are tapped including a syscall to Linux' `SYS_getrandom` as well as Int els hardware random number generators `RDRND` and `RDSEED`, if available (compil e using `-march=native`). Its initialization relies on seeding with a value as random as possible. Various sources are tapped including a syscall to Linux' `SYS_getrandom` as well as Int els hardware random number generators `RDRND` and `RDSEED`, if available (compil e using `-march=native`).
### Pearson Hashing ### Pearson Block Hashing
For general purpose hashing, n2n employs Pearson hashing as it offers variable h ash sizes and is said not to be too "collidy". However, this is not a cryptograp hically secure hashing function which by the way is not required here: The hashi ng is never applied in a way that the hash shall prove the knowledge of a secret without showing the secret. For general purpose hashing, n2n employs [Pearson Block Hashing](https://github. com/Logan007/pearsonB) as it offers variable hash sizes and is said not to be to o "collidy". However, this is not a cryptographically secure hashing function wh ich by the way is not required here: The hashing is never applied in a way that the hash value shall publicly prove the knowledge of a secret without showing th e secret itself.
_Pearson hashing is tweakable by making your own permutation of the 256 byte tab le._ _Pearson hashing is tweakable by using your own block-sized permutation._ Here, we use a three-round xor-rotate-multiply permutation scheme on 64-bit wide integ er numbers with constants discovered by [David Stafford](http://zimbry.blogspot. com/2011/09/better-bit-mixing-improving-on.html) (`mix13`, permission obtained v ia eMail) which, meanwhile, is better known as part of `splitmix64()`.
_Pearson hashing allows verification of parts of the hash only – just in case pe rformance requirements would urge to do so._ _Pearson hashing allows verification of block-sized parts of the hash only – jus t in case performance requirements would urge to do so._
## Header ## Header
### Overview ### Overview
Packet's header consist of a COMMON section followed by a packet-type specific s ection, e.g. REGISTER, REGISTER_ACK, PACKET including the payload, REGISTER_SUPE R, … Packet's header consist of a COMMON section followed by a packet-type specific s ection, e.g. REGISTER, REGISTER_ACK, PACKET including the payload, REGISTER_SUPE R, …
The COMMON section is built as follows: The COMMON section is built as follows:
``` ```
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Version=2 ! TTL ! Flags ! ! Version = 3 ! TTL ! Flags !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
4 ! Community : 4 ! Community ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 ! ... Community ... : 8 ! ... Community ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 ! ... Community ... : 12 ! ... Community ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 ! ... Community ... ! 16 ! ... Community ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
20 ! ... Community !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
``` ```
In case of a PACKET-type, it is succeeded by the fields depicted below: In case of a PACKET-type, it is succeeded by the fields depicted below:
``` ```
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
20 ! Source MAC Address : 24 ! Source MAC Address :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
24 : ! Destination MAC Address : 28 : ! Destination MAC Address :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
28 : ! 32 : !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
32 ! Socket Flags (v=IPv4) ! Destination UDP Port ! 36 ! Socket Flags (v=IPv4) ! Destination UDP Port !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
36 ! Destination IPv4 Address ! 40 ! Destination IPv4 Address !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
40 ! Transform ID ! Payload ... ! 44 ! Compress'n ID ! Transform ID ! Payload ... !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
44 ! 48 ! !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+...
``` ```
### Encryption ### Encryption
If enabled (`-H`), all fields but the payload (which is handled seperately as ou tlined above) get encrypted using SPECK in CTR mode. As packet headers need to b e decryptable by the supernode and we do not want to add another key (to keep it a simple interface), the community name serves as key (keep it secret!) because it is already known to the supernode. The community name consists of up to 16 c haracters (well, 15 + `0x00`), so key size of 128 bit is a reasonable choice her e. If enabled (`-H`), all fields but the payload (which is handled separately as ou tlined above) get encrypted using SPECK in CTR mode. As packet headers need to b e decryptable by the supernode and we do not want to add another key (to keep it a simple interface), the community name serves as key (keep it secret!) because it is already known to the supernode. The community name consists of up to 20 c haracters (well, 19 + `0x00`), so key size of 128 bit is a reasonable choice her e.
The scheme applied tries to maintain compatibility with current packet format an d works as follows: The scheme applied tries to maintain compatibility with current packet format an d works as follows:
- First line of 4 bytes (Version, TTL, Flags) goes to fifth line: - First line of 4 bytes (Version, TTL, Flags) goes to sixth line:
``` ```
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Community ... : ! Community ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
4 ! ... Community ... : 4 ! ... Community ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 ! ... Community ... : 8 ! ... Community ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 ! ... Community ! 12 ! ... Community ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 ! ... Community !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 ! Version=2 ! TTL ! Flags ! 20 ! Version = 3 ! TTL ! Flags !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
``` ```
- To be able to identify a correctly decrpyted header later on, a magic number i - To be able to identify a correctly decrpyted header later on, a magic number i
s stamped in fourth line starting at byte number 12. We use "n2n" string and add s stamped in fourth line starting at byte number 16. We use "n2" string and add
the header length to be able to stop header decryption right before an eventual the 16-bit header length to be able to stop header decryption right before an ev
ly following payload begins – in case of PACKET-type, header-length does not equ entually following ethernet data payload begins – in case of PACKET-type, header
al packet-length. -length does not equal packet-length. 16-bit length is required because REGISTER
_SUPER_ACK packets consist of header only and could grow quite large due to thei
r payload (other supernodes of federation) – don't mix up this kind of payload (
part of the header) with the ethernet data payload of PACKET messages.
- The rest of the community field, namely the first 16 bytes, is reframed toward
s a 128-bit IV for the header encryption.
- The rest of the community field, namely the first 12 bytes, is reframed toward s a 96-bit IV for the header encryption.
``` ```
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! IV ... : ! IV ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
4 ! ... IV ... : 4 ! ... IV ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 ! ... IV : 8 ! ... IV ... :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
12 ! 24-bit Magic Number, "n2n" = 0x6E326E ! Header Length ! 12 ! ... IV !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
16 ! Version=2 ! TTL ! Flags ! 16 ! Magic Number "n2" = 0x6E32 ! Header Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
20 ! Version = 3 ! TTL ! Flags !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
``` ```
- As we use a stream cipher, the IV should be a nonce. The IV plays an additiona l role sketched later, see the following sections on checksum and replay protect ion. For use in header encryption and decryption, four bytes reading ASCII "n2n! " are appended to the 96-bit IV hereby internally making it a full 128-bit IV. - As we use a stream cipher, the IV should be a nonce. The IV plays an additiona l role sketched later, see the following sections on checksum and replay protect ion.
- To make a less predictable use of the key space – just think of the typically reset MSB of ASCII characters of community names – we actually use a hash of the community name as key. - To make a less predictable use of the key space – just think of the typically reset MSB of ASCII characters of community names – we actually use a hash of the community name as key.
- Encryption starts at byte number 12 and ends at header's end. It does not comp rise the payload which eventually has its own encryption scheme as chosen with t he `-A_` options. - Encryption starts at byte number 16 and ends at header's end. It does not comp rise PACKET's ethernet data payload which eventually has its own encryption sche me as chosen with the `-A_` options.
Decryption checks all known communities (several in case of supernode, only one at edge) as keys. On success, the emerging magic number will reveal the correct community whose name will be copied back to the original fields allowing for reg ular packet handling. Decryption checks all known communities (several in case of supernode, only one at edge) as keys. On success, the emerging magic number along with a reasonable header's length value will reveal the correct community whose name will be copie d back to the original fields allowing for regular packet handling.
Thus, header encryption will only work with previously determined community name s introduced to the supernode by `-c <path>` parameter. Also, it should be clear that header encryption is a per-community decision, i.e. all nodes and the supe rnode need to have it enabled. However, the supernode supports encrpyted and une ncrypted communities in parallel, it determines their status online at arrival o f the first packet. Use a fresh community name for encrypted communities; do not use a previously used one of former unecrpyted communities: their names were tr ansmitted openly. Thus, header encryption will only work with previously determined community name s introduced to the supernode by `-c <path>` parameter. Also, it should be clear that header encryption is a per-community decision, i.e. all nodes and the supe rnode need to have it enabled. However, the supernode supports encrypted and une ncrypted communities in parallel, it determines their status online at arrival o f the first packet. Use a fresh community name for encrypted communities; do not use a previously used one of former unecrypted communities: their names were tr ansmitted openly.
### Checksum ### Checksum
The whole packet including the eventually present payload is checksummed using a modified Person hashing. It might seem a little short compared to usual message tags of 96 up to 128 bit, especially when using a stream cipher which easily al lows for bit-flips. So, the 16-bit checksum is filled up with 80 more bits to ob tain a 96-bit pre-IV. This pre-IV gets encrypted using a single block-cipher ste p to get the pseudo-random looking IV. This way, the checksum resists targeted b it-flips (to header, payload, and IV) as any change to the whole 96-bit IV would render the header un-decryptable. The whole packet including the eventually present payload is checksummed using a Person block hashing scheme. The 64-bit checksum is exclusive-ored with a (shif ted by 32 bit) 64-bit time stamp and filled up with 32 more random bits to obtai n a 128-bit pre-IV. This pre-IV gets encrypted using a single block-cipher step to get the pseudo-random looking IV. This way, the checksum resists targeted bit -flips (to header, payload, and IV) as any change to the whole 128-bit IV would render the header un-decryptable. Also, as explained below, the checksum comes a long with a time stamp minimizing opportunities for random attacks.
The single block-cipher step employs SPECK because it is fast, always present as built-in and it offers a 96-bit version. The key is derived from the header key – a hash of the hash. The single block-cipher step employs SPECK because it is quite fast and it offer s a 128-bit block cipher version. The key is derived from the header key – a has h of the hash.
The checksum gets verified by the edges and the supernode. The checksum is calculated by the edges and the supernode. Changes to the payloa d will cause a different locally calculated checksum. Extracting the time stamp by exclusive-oring an erroneous checksum will lead to an invalid timestamp. So, checksum errors are indirectly detected when checking for a valid time stamp.
### Replay Protection ### Replay Protection
The aforementioned fill-up does not completely rely on random bits. A 52-bit tim e stamp displaying a microsecond-accuracy is encoded to the 96-bit pre-IV as wel l: The aforementioned 128-bit pre-IV can be depicted as follows:
``` ```
0123456789012345678901234567890123456789012345678901234567890123456789012345 0123456789012345678901234567890123456789012345678901234567890123456789012345
67890123456789012345 6789012345678901234567890123456789012345678901234567
+---------------------------------------------------------------------------- +----------------------------------------------------------------+-----------
--------------------+ --------------------+-------------------------------+
! 52-bit time stamp with microsecond-accuracy ! 28 pseudo-random bits ! 64-bit checksum of the whole packet ! 0x00
!16-bit checksum! ! !
+---------------------------------------------------------------------------- + - - - - - - - - - - - - - - - - - - - - - - - XOR - - - - - - - - - - - - -
--------------------+ - - - - - - - - - -! 32 pseudo-random bits !
! 0x00 ! 52-bit time stamp with microsecond-accuracy
! countr ! F ! !
+----------------------------------------------------------------------------
--------------------+-------------------------------+
``` ```
Encrypting this pre-IV with a block cipher step will generate a pseudo-random lo
oking IV which gets written to the packet and used for the header encryption. The time stamp consists of the 52-bit microsecond value, a 8-bit counter in case
of equal following time stamps and, a 4-bit flag field F (accuracy indicator in
last bit). edge and supernode monitor their own time stamps for doublets which
would indicate an accuracy issue. If the counter overflows on the same time stam
p, the sub-second part of the time stamp will also become counter. In this case,
the whole stamp carries the accuracy bit flag (lowest bit) set so other edges a
nd supernodes can handle this stamp appropriately.
Encrypting this pre-IV using a block cipher step will generate a pseudo-random l
ooking IV which gets written to the packet and used for the header encryption.
Due to the time-stamp encoded, the IV will more likely be unique, close to a rea l nonce. Due to the time-stamp encoded, the IV will more likely be unique, close to a rea l nonce.
Upon receival, the time stamp as well as the checksum can be extracted from the IV by performing a 96-bit block-cipher decryption step. Verification of the time stamp happens in two steps: Upon receival, the time stamp as well as the checksum can be extracted from the IV by performing a 128-bit block-cipher decryption step. Verification of the tim e stamp happens in two steps:
- The (remote) time stamp is checked against the local clock. It may not deviate more than plus/minus 16 seconds. So, edges and supernode need to keep a somewha t current time. This limit can be adjusted by changing the `TIME_STAMP_FRAME` de finition. It is time-zone indifferent as UTC is used. - The (remote) time stamp is checked against the local clock. It may not deviate more than plus/minus 16 seconds. So, edges and supernode need to keep a somewha t current time. This limit can be adjusted by changing the `TIME_STAMP_FRAME` de finition. It is time-zone indifferent as UTC is used.
- Valid (remote) time stamps get stored as "last valid time stamp" seen from eac - Valid (remote) time stamps get stored as "last valid time stamp" seen from eac
h node (supernode and edges). So, a newly arriving packet's time stamp can be co h node (supernode and edges). So, a newly arriving packet's time stamp can be co
mpared to the last valid one. It should be equal or higher. However, as UDP pack mpared to the last valid one. It should be equal or higher. However, as UDP pack
ets may overtake each other just by taking another path through the internet, th ets may overtake each other just by taking another path through the internet, th
ey are allowed to be 160 millisecond earlier than the last valid one. This limit ey are allowed to be 160 millisecond earlier than the last valid one. This limit
can be adjusted by changing the `TIME_STAMP_JITTER` definition. is set with the `TIME_STAMP_JITTER` definition. If the accuracy flag is set, th
e time stamp will be allowed a jitter eight times as high, corresponding to 1.25
seconds by default.
- However, the systemic packets such as REGISTER_SUPER are not allowed any time
stamp jitter because n2n relies on the actual sender's socket. A replay from ano
ther IP within any allowed jitter time frame would deviate the traffic which sha
ll be prevented (even if it remains undecryptable). Under absolutely rare (!) ci
rcumstances, this might cause a re-registration requirement which happens automa
tically but might cause a small delay – security (including network availability
) first! REGISTER packets from the local multicast environment are exempt from t
he very strict no-jitter requirement because they indeed regularly can show some
deviation if compared to time stamps in packets received on the regular socket.
As these packets are incoming on different sockets, their processing is more li
kely to no take place in the order these packets were sent.
The way the IV is used for replay protection and for checksumming makes enabled header encryption a prerequisite for these features. The way the IV is used for replay protection and for checksumming makes enabled header encryption a prerequisite for these features.
 End of changes. 54 change blocks. 
77 lines changed or deleted 114 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)