Ruby Version Gem Build Status 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 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:

$ gem install ipcrypt

Installation for CLI usage

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

$ 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:
  gem 'ipcrypt'
  1. Execute the following command:
  $ bundle install

CLI Usage

$ 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

crypter = IPCrypt::IP['94.175.013.122', '73.155.92.01']
=> #<IPCrypt::Engine:0x00007f87139ae150 @default_key="\xB5\xBA\xE1\xD6\x1C\x9F\xD1#[\x93\xD8\x86\xBC\xFD\xACx", @ips=["94.175.013.122", "73.155.92.01"]>

crypter.ips = crypter.encrypt
=> ["126.189.155.194", "51.239.168.232"]

crypter
=> #<IPCrypt::Engine:0x00007f87139ae150 @default_key="\xB5\xBA\xE1\xD6\x1C\x9F\xD1#[\x93\xD8\x86\xBC\xFD\xACx", @ips=["126.189.155.194", "51.239.168.232"]>

crypter.decrypt crypter.default_key
=> ["94.175.13.122", "73.155.92.1"]

Using a set key

key = 'secret-16-bytes!'
=> "secret-16-bytes!"

crypter = 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"]>

crypter.ips = crypter.encrypt key
=> ["239.130.3.132", "168.16.121.58"]

crypter
=> #<IPCrypt::Engine:0x00007fb84f1a4230 @default_key="FN\xECa\x92\xA3\x1A\xC3(E\x9E\xF4\xD4\xBC\x8F)", @ips=["239.130.3.132", "168.16.121.58"]>

crypter.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.