[![Ruby Version](https://img.shields.io/badge/ruby-~%3E%202.5-red.svg)](https://github.com/eonu/ipcrypt/blob/945450c32a145d7675b5d2b0c796708195d42388/ipcrypt.gemspec#L20)
[![Gem](https://img.shields.io/gem/v/ipcrypt.svg)](https://rubygems.org/gems/ipcrypt)
[![Build Status](https://travis-ci.org/eonu/ipcrypt.svg?branch=master)](https://travis-ci.org/eonu/ipcrypt)
[![License](https://img.shields.io/github/license/eonu/ipcrypt.svg)](https://github.com/eonu/ipcrypt/blob/master/LICENSE)

# IPCrypt

Ruby implementation of the format-preserving IPCrypt encryption algorithm for IPv4 addresses.

---

IPCrypt is a format-preserving cipher for IPv4 addresses - that is, a cipher that accepts an IPv4 address for encryption, and generates a new decryptable IPv4 address.

The cipher was developed by Jean-Philippe Aumasson, initially in the form of a [python implementation](https://github.com/veorq/ipcrypt) which is the reference for this Ruby implementation.

## Features

This gem provides:

- A CLI tool (`ipcrypt`) for the encryption/decryption of IPv4 addresses stored in CSV files
- A Ruby interface in the form of a module (`IPCrypt::IP`) for the encryption/decryption of IPv4 addresses of the class `String` within Ruby applications

## Installation

Install the `ipcrypt` gem:

```bash
$ gem install ipcrypt
```

### Installation for CLI usage

The CLI should be available to use after the gem has been installed:

```bash
$ ipcrypt
Commands:
  ipcrypt d [CSV] [COLUMN]  # Decrypt IPv4 addresses from a CSV file
  ipcrypt e [CSV] [COLUMN]  # Encrypt IPv4 addresses from a CSV file

Options:
  -k, --key=KEY  # 16-byte key
```

### Installation for usage within Ruby applications

1. Add the gem to your application's Gemfile:

  ```ruby
  gem 'ipcrypt'
  ```

2. Execute the following command:

  ```bash
  $ bundle install
  ```

## CLI Usage

```bash
$ cat test.csv
id,firstname,lastname,ip_address,country
1,a,b,127.0.0.1,c
2,d,e,0.0.0.0,f
3,g,h,255.255.255.255,i
4,j,k,192.168.2.1,l

$ ipcrypt e test.csv ip_address -k '16-byte-key-123!' > encrypted.csv

$ cat encrypted.csv
id,firstname,lastname,ip_address,country
1,a,b,94.99.154.180,c
2,d,e,34.112.126.36,f
3,g,h,6.156.93.249,i
4,j,k,41.85.161.64,l

$ ipcrypt d encrypted.csv ip_address -k '16-byte-key-123!'
id,firstname,lastname,ip_address,country
1,a,b,127.0.0.1,c
2,d,e,0.0.0.0,f
3,g,h,255.255.255.255,i
4,j,k,192.168.2.1,l
```

## Usage within Ruby applications

The `IPCrypt::IP` is an interface for instantiating an `IPCrypt::Engine` - this class performs the task of encryption and decryption.

A random 16-byte key will be generated and stored as the `@default_key` instance variable - this can be retrieved with the `#default_key` attribute reader. This default key is used as the encryption key if none is specified as an argument for the `#encrypt` instance method.

### Using a default key

```ruby
encrypter = IPCrypt::IP['94.175.013.122', '73.155.92.01']
=> #<IPCrypt::Engine:0x00007ff9f904fc68 @default_key="\x95\xC6\rM\xE5\xFAKE\xAD\x16\x80\x9A\xF6\xA9\v\x8B", @ips=["94.175.013.122", "73.155.92.01"]>

encrypted = encrypter.encrypt
=> ["221.69.213.73", "80.1.170.94"]

decrypter = IPCrypt::IP[encrypted]
=> #<IPCrypt::Engine:0x00007ff9f91618e0 @default_key="\xF8\x00\x8Cdj\xFF\xE9\x82\xE9\v\x85e\xF6\x7F 8", @ips=["221.69.213.73", "80.1.170.94"]>

decrypted = decrypter.decrypt encrypter.default_key
=> ["94.175.13.122", "73.155.92.1"]
```

### Using a set key

```ruby
key = '16-byte-key-123!'
=> "16-byte-key-123"

encrypter = IPCrypt::IP['94.175.013.122', '73.155.92.01']
=> #<IPCrypt::Engine:0x00007fe851049db8 @default_key="\xCC\xE0j\x13s\xB9B+\xEF'\xC8\xFC\xD4\xA5\xFCW", @ips=["94.175.013.122", "73.155.92.01"]>

encrypted = encrypter.encrypt key
=> ["74.248.51.155", "132.12.16.129"]

decrypter = IPCrypt::IP[encrypted]
=> #<IPCrypt::Engine:0x00007fe85117b1c8 @default_key="\xFA\x9C\x1E\xEE\xA7\xE3\xA1\xFD(9Q\x94\x11\xA4\x90\x19", @ips=["74.248.51.155", "132.12.16.129"]>

decrypted = decrypter.decrypt key
=> ["94.175.13.122", "73.155.92.1"]
```

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/eonu/ipcrypt.