{"id":18375452,"url":"https://github.com/riboseinc/transcryptor","last_synced_at":"2025-04-06T20:31:03.296Z","repository":{"id":59157949,"uuid":"92382451","full_name":"riboseinc/transcryptor","owner":"riboseinc","description":"Assists your everyday re-encryption needs, in Rails.","archived":false,"fork":false,"pushed_at":"2018-05-31T06:40:37.000Z","size":80,"stargazers_count":2,"open_issues_count":15,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-05T23:32:31.875Z","etag":null,"topics":["encryptor","migration","rails"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riboseinc.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-25T08:32:28.000Z","updated_at":"2023-03-31T06:46:00.000Z","dependencies_parsed_at":"2022-09-13T20:10:17.891Z","dependency_job_id":null,"html_url":"https://github.com/riboseinc/transcryptor","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riboseinc%2Ftranscryptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riboseinc%2Ftranscryptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riboseinc%2Ftranscryptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riboseinc%2Ftranscryptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riboseinc","download_url":"https://codeload.github.com/riboseinc/transcryptor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247547221,"owners_count":20956523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["encryptor","migration","rails"],"created_at":"2024-11-06T00:19:00.749Z","updated_at":"2025-04-06T20:31:02.980Z","avatar_url":"https://github.com/riboseinc.png","language":"Ruby","readme":"= Transcryptor\n\nimage:https://travis-ci.org/riboseinc/transcryptor.svg?branch=master[\"Build Status\", link=\"https://travis-ci.org/riboseinc/transcryptor\"]\nimage:https://codeclimate.com/github/riboseinc/transcryptor/badges/gpa.svg[\"Code Climate Quality\", link=\"https://codeclimate.com/github/riboseinc/transcryptor\"]\nimage:https://codeclimate.com/github/riboseinc/transcryptor/badges/coverage.svg[\"Code Climate Quality\", link=\"https://codeclimate.com/github/riboseinc/transcryptor/coverage\"]\n\nTranscryptor provides utility functions to help migrate records encrypted with https://github.com/attr-encrypted/attr_encrypted[`attr_encrypted`] from one encryption configuration to another.\n\n== Installation\n\nAdd this line to your application's Gemfile:\n\n[source,ruby]\n----\ngem 'transcryptor', github: 'riboseinc/transcryptor'\n----\n\nAnd then execute:\n\n----\nbundle\n----\n\nOr install it yourself as:\n\n----\ngem install transcryptor\n----\n\n== Usage\n\n=== ActiveRecord::Migration\n\nYou have a `User` with `ssn` attribute which needs to be re-encrypted. `User` has next configuration:\n\n[source,ruby]\n----\nclass User \u003c ActiveRecord::Base\n  attr_encrypted :ssn, key: -\u003e(u) { ENV['USER_SSN_ENC_KEY'] },\n                       mode: :per_attribute_iv_and_salt,\n                       algorithm: 'aes-256-gcm'\nend\n----\n\nTo re-ecrypt this column with new key (`ENV['NEW_USER_SSN_ENC_KEY']`), algorithm (`aes-256-cbc`) and mode (`per_attribute_iv`) you can easily define migration.\n\n[source,ruby]\n----\nclass ReEncryptUserSsn \u003c ActiveRecord::Migration\n  def up\n    re_encrypt_column :users, :ssn,\n      { # old configuration of attr_encrypted for :ssn column\n        key: -\u003e(u) { ENV['USER_SSN_ENC_KEY'] },\n        mode: :per_attribute_iv_and_salt,\n        algorithm: 'aes-256-gcm'\n      },\n      { # new configuration of attr_encrypted for :ssn column\n        key: -\u003e(u) { ENV['NEW_USER_SSN_ENC_KEY'] },\n        mode: :per_attribute_iv,\n        algorithm: 'aes-256-cbc'\n      }\n  end\nend\n----\nRun `bundle exec rake db:migrate`. Done!\n\n=== DataMapper::Migration\n\nSee link:#activerecordmigration[ActiveRecord::Migration] for initial data. And then `DataMapper` migration is:\n\n[source,ruby]\n----\nrequire 'dm-migrations/migration_runner'\n\nmigration 1, :re_encrypt_user_ssn do\n  up do\n    re_encrypt_column :users, :ssn,\n      { # old configuration of attr_encrypted for :ssn column\n        key: -\u003e(u) { ENV['USER_SSN_ENC_KEY'] },\n        mode: :per_attribute_iv_and_salt,\n        algorithm: 'aes-256-gcm'\n      },\n      { # new configuration of attr_encrypted for :ssn column\n        key: -\u003e(u) { ENV['NEW_USER_SSN_ENC_KEY'] },\n        mode: :per_attribute_iv,\n        algorithm: 'aes-256-cbc'\n      }\n  end\nend\n\nmigrate_up!\n----\n\n=== Additional options\n\nTaking `ActiveRecord` as an example (the following applies to `DataMapper` as well):\n\n==== `where`\n\nSpecify an SQL string (or a `proc` returning one) inside the `where` option to\nlimit the range on which transcryption is run:\n\n[source,ruby]\n----\nclass ReEncryptUserSsn \u003c ActiveRecord::Migration\n  def up\n    re_encrypt_column :users, :ssn,\n      { # old configuration of attr_encrypted for :ssn column\n        key: -\u003e(u) { ENV['USER_SSN_ENC_KEY'] },\n        mode: :per_attribute_iv_and_salt,\n        algorithm: 'aes-256-gcm'\n      },\n      { # new configuration of attr_encrypted for :ssn column\n        key: -\u003e(u) { ENV['NEW_USER_SSN_ENC_KEY'] },\n        mode: :per_attribute_iv,\n        algorithm: 'aes-256-cbc'\n      },\n      where: -\u003e { \"encrypted_ssn IS NOT NULL\" }\n  end\nend\n----\n\n== Zero Downtime Migration\n\n=== ActiveRecord\n\nCreate new columns in database.\n\n[source,ruby]\n----\nclass Migration1 \u003c ActiveRecord::Migration\n  def up\n    add_column :users, :encrypted_new_ssn\n    add_column :users, :encrypted_new_ssn_iv\n  end\nend\n----\n\nAdd `attr_encrypted` for new columns, `include Transcryptor::ActiveRecord::ZeroDowntime`, and `transcryptor_migrate :old_attribute_name, :new_attribute_name`.\n\n[source,ruby]\n----\nclass User \u003c ActiveRecord::Base\n  include Transcryptor::ActiveRecord::ZeroDowntime\n\n  attr_encrypted :ssn, key: '1qwe1qwe1qwe1qwe1qwe1qwe1qwe1qwe', algorithm: 'aes-256-cbc'\n  attr_encrypted :new_ssn, key: '2asd2asd2asd2asd2asd2asd2asd2asd', algorithm: 'aes-256-gcm'\n\n  transcryptor_migrate :ssn, :new_ssn\nend\n----\n\nCreate `rake` task for zero downtime migration. Or any other way you prefer.\n\n[source,ruby]\n----\nnamespace :zero_downtime\n  desc 'migrate attr_encrypted for User'\n  task user: :environment do\n    User.find_each { |user| user.save! }\n  end\nend\n----\n\nRemove \u0026 rename columns in database after finishing of `rake` task.\n\n[source,ruby]\n----\nclass Migration2 \u003c ActiveRecord::Migration\n  def up\n    remove_column :users, :encrypted_ssn\n    remove_column :users, :encrypted_ssn_iv\n\n    rename_column :users, :encrypted_new_ssn, :encrypted_ssn\n    rename_column :users, :encrypted_new_ssn_iv, :encrypted_ssn_iv\n  end\nend\n----\n\nMove `attr_encrypted` configuration to original attribute and remove all migration code.\n\n[source,ruby]\n----\nclass User \u003c ActiveRecord::Base\n  attr_encrypted :ssn, key: '2asd2asd2asd2asd2asd2asd2asd2asd', algorithm: 'aes-256-gcm'\nend\n----\n\nDone!\n\n== Default Options\n\nDefault options for old and new configuration are absolutelly the same as it is defined in `attr_encrypted` gem.\n\n[source,ruby]\n----\n{\n  prefix:            'encrypted_',\n  suffix:            '',\n  if:                true,\n  unless:            false,\n  encode:            true, # changed from false to true as transcryptor works with DB rows\n  encode_iv:         true,\n  encode_salt:       true,\n  default_encoding:  'm',\n  marshal:           false,\n  marshaler:         Marshal,\n  dump_method:       'dump',\n  load_method:       'load',\n  encryptor:         Encryptor,\n  encrypt_method:    'encrypt',\n  decrypt_method:    'decrypt',\n  mode:              :per_attribute_iv,\n  algorithm:         'aes-256-gcm',\n}\n----\n\n== Zero downtime migration using VersionedFields (from version 0.3.0)\n\nYou can use transcryptor to migrate your encrypted fields in zero downtime\nusing https://github.com/riboseinc/versioned_fields[versioned_fields] gem.\n\nJust include `Transcryptor::Decoder` module and use `decode_with_previous_settings`\nto decode your fields with specific settings:\n\n```ruby\n# db/migrate_versioned_fields/user/ssn.rb\n\nVersionedFields::Migration.draw_for(User, :ssn) do\n  config.include Transcryptor::Decoder\n\n  version 1\n  version(2) do\n    decode_with_previous_settings(migration,\n      key:       '67c3800d1572d9d964a6ff3bd821ed02',\n      algorithm: 'aes-256-gcm'\n    )\n  end\n\n  version(3) do |migration|\n    decode_with_previous_settings(migration,\n      key:       '94dd7e2c40a3d51a8dd0a9137356a18e',\n      algorithm: 'RC2-64-CBC'\n    )\nend\n```\n\n== Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`rake spec` to run the tests. You can also run `bin/console` for an interactive\nprompt that will allow you to experiment.\n\n== Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/riboseinc/transcryptor. This project is intended to be a\nsafe, welcoming space for collaboration, and contributors are expected to\nadhere to the http://contributor-covenant.org[Contributor Covenant] code of\nconduct.\n\n== License\n\nThe gem is available as open source under the terms of the\nhttp://opensource.org/licenses/MIT[MIT License].\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friboseinc%2Ftranscryptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friboseinc%2Ftranscryptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friboseinc%2Ftranscryptor/lists"}