% chhoyhopper
% ASM Rizvi <asmrizvi@usc.edu>
% March 05, 2021

# COMPONENTS

chhoyhopper consists of:

- ``chhoyhopper-server``: Implement a moving target defense, where the server IPv6 address changes over time. 
- ``chhoyhopper-client``: This program finds the valid IPv6 address to connect to the moving server.

chhoyhopper is written by [*ASM Rizvi*](https://ant.isi.edu/~rizvi/) at the University of Southern California.


# SERVER
With this program, an IPv6 service will be provided at a moving IPv6 address.
The service runs on another IP address and this program forwards 
traffic to that service IP from an IPv6 address
that depends on the current time, a shared secret, and a salt value.

By default the service address changes every minute.
We account for clock skew with a grace period of up to *60s*.
       
By default, the service is ssh on *prefix::f*.
To overwrite, select the translated address with ``--to``.

The key is provided in a file via ``--keyfile``.
The key is arbitrary binary data.

By default we hop over the entire */64* on the given interface.

This daemon runs forever, changing the address regularly.

This program inserts *ip6tables NAT* and *INPUT filter* rules.
NAT rules will be inserted top of the table and will translate the temporary 
IPv6 address to the actual server address. The INPUT filter will be at the top 
of the INPUT chain and will drop packets that do not have the actual server address. 
A packet needs to go through both NAT and INPUT chain rule to get the service. 
No one can reach the IPv6 server without computing the current IPv6 address. 
Even targeting the actual server address won't be successful. 
This program will also insert rules to keep the already established connections. 
Also, it automatically assigns IPv6 address to the interface. 
When the life of an address is over, it stops the service at that address and 
deletes the NAT rules and interface addresses.

# CLIENT
An IPv6 server will be hopping around over different IPv6 addresses. 
This program will find out the correct, current IPv6 address,
which is a function of the time, shared secret, and salt.
Server and client must share a key before making the connection.

# INSTALLATION:
Dependency: dnspython3

To install type: ``sudo python3 setup.py install``

It will automatically install ``dnspython3``, ``chhoyhopper-client`` and ``chhoyhopper-server``.

# SYNOPSIS

chhoyhopper-server [``--address``=*IPv6 address OR domain name*] [``--keyfile``=*key file path*]
			[``--salt``=*constant*] [``--to``=*IPv6 address*] [``--verbose``]

chhoyhopper-client [``--address``=*IPv6 address OR domain name*] [``--keyfile``=*key file path*]
			[``--salt``=*constant*] [``--service``=*application*]

# SERVER OPTIONS
``--address``=*IPv6 address OR domain name*
:	IPv6 address or domain name to open the service, default is hostname.

``--keyfile``=*key file path*
:	Path of the key file. This key file should be shared with the client. Default is file.bin.

``--salt``=*constant*
:	Salt for hashing, default is 4750. Client should use the same salt.

``--to``=*IPv6 address*
:	Internal IPv6 server address, default is prefix::f. NAT rule will translate the dummy to this address. 
``--verbose``
:	Print the system commands executing by this program, default is none.

# CLIENT OPTIONS
``--address``=*IPv6 address OR domain name*
:	IPv6 address or domain name to connect. Client requires to give an address of the service. 

``--keyfile``=*key file path*
:	Path of the key file. This key file should be shared by the server. Default is file.bin.

``--salt``=*constant*
:	Salt for hashing, default is 4750. Server should use the same salt.

``--service``=*application*
:	Service to connect, default is ssh. 

# EXAMPLE
## Server
Running hopping for ssh on *prefix::f*, exporting service on
using *vm18.ant.isi.edu*'s /64 prefix:

1. *Opening service for hostname (default)*:
	``chhoyhopper-server``

2. *Opening service for vm18.ant.isi.edu*:
	``chhoyhopper-server --address vm18.ant.isi.edu``
	
3. *or by IP address*:
	``chhoyhopper-server --address 2001:1878:401::8009:1d15``
	(note that the hopping address will be anywhere in 2001:1878:401::/64,
	not at this public IP address.)

4. *changing key file (this should be shared with clients, default is file.bin)*:
	``chhoyhopper-server --keyfile "/tmp/key"``
		
## Client
An IPv6 client wants to connect to a moving server.

1. *Connecting to vm18.ant.isi.edu*:
	``chhoyhopper-client --address vm18.ant.isi.edu``

2. *Connecting to 2001:1878:401::8009:1d15*:
	``chhoyhopper-client --address 2001:1878:401::8009:1d15``

3. *Using a different key file (dafault is file.bin)*:
	``chhoyhopper-client --address 2001:1878:401::8009:1d15 --key /tmp/public.pem``
