# PGCrypto for ActiveRecord 🆊

[PostgreSQL PGCrypto](https://www.postgresql.org/docs/current/pgcrypto.html)
support for ActiveRecord models.

![Don't roll your own crypto](https://imgs.xkcd.com/comics/cryptography.png)

## About

The goal of this project is to provide a simple and efficient encryption
support for your application records.

Main goals:
 * No _magic_ please
 * No DSLs please
 * Less code, less maintenance
 * Good docs and test coverage
 * Keep it up-to-date (or at least tell people this is no longer maintained)

The available features include:
 * PostgreSQL `pgcrypto` native symmetric encryption using the
   [attribute serialization](https://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Serialization/ClassMethods.html#method-i-serialize) API and Arel API.
 * Logger support for sensitive data query obfuscation.

### A bit of history...

The project was born after trying out `crypt_keeper` and having to deal with
the broken support for PostgreSQL where the stored data would be invalid for
native SQL functions.

I would like to thank Justin for his work, but I decided to move away from the
original work for arguably subjective reasons and the critical importance of
this functionality in my projects.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'active_record-pgcrypto'
```

And then execute:

```ruby
$ bundle
```

Or install it yourself as:

```ruby
$ gem install active_record-pgcrypto
```

## Usage

To start using it with ActiveRecord/Rails, add this to an initializer and
configure your keys:
```ruby
# config/initializers/pgcrypto.rb
require 'active_record/pgcrypto'
# Replace the default environment variable name with your own value/key.
ActiveRecord::PGCrypto::SymmetricCoder.pgcrypto_key = ENV['PGCRYPTO_SYM_KEY']
 ```

Now enable the coder for your model attributes:

```ruby
class MyModel < ActiveRecord::Base
  serialize(:email, ActiveRecord::PGCrypto::SymmetricCoder)
end
```

The coder provides a simple API to help you provide search support by leveraging
Arel API:

```ruby
class MyModel < ActiveRecord::Base
  serialize(:email, ActiveRecord::PGCrypto::SymmetricCoder)

  def self.decrypted_email
    ActiveRecord::PGCrypto::SymmetricCoder.decrypted_arel(arel_table[:email])
  end
end
```

Now you can use add it to your `ActiveRecord::Base#where` queries:

```ruby
MyModel.where(MyModel.decrypted_email.eq('keyword'))
```

## Development

After checking out the repo, run `bundle` to install dependencies.

Then, run `rake` to run the tests.

To install this gem onto your local machine, run `bundle exec rake install`.

To release a new version, update the version number in `version.rb`, and then
run `bundle exec rake release`, which will create a git tag for the version,
push git commits and tags, and push the `.gem` file to
[rubygems.org](https://rubygems.org).

## Contributing

Bug reports and pull requests are welcome on GitHub at
https://github.com/stas/active_record-pgcrypto. This project is intended to be
a safe, welcoming space for collaboration, and contributors are expected to
adhere to the [Contributor Covenant](http://contributor-covenant.org) code of
conduct.

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## Code of Conduct

Everyone interacting with this project codebase, issue
tracker, chat rooms and mailing list is expected to follow the [code of
conduct](https://github.com/[USERNAME]/active_record-pgcrypto/blob/master/CODE_OF_CONDUCT.md).