Epithet

Epithet generates stable, compact, purposefully prefixed base58 identifiers from 64-bit integers for reversible obfuscation and tamper detection.

• github.com/inopinatus/epithet

• inopinatus.github.io/epithet/

Installation

Add to your Gemfile:

gem 'epithet'

Or install directly:

gem install epithet

Usage

With EPITHET_PASSPHRASE=example_only:

require 'epithet'

def epithet_initialize
  Epithet.configure(
    passphrase: ENV.fetch('EPITHET_PASSPHRASE'),
    scrypt: { salt: 'myapp/production' },
    context: 'v1'
  )
end

epithet_initialize
user_epithet = Epithet.new('user')

id = 42
param = user_epithet.encode(id)
# => "user_GikJf7Y58t5sgqJpifjgZy"

user_epithet.decode(param)
# => 42

Configuration once at initialisation is recommended, because deriving key material from the passphrase uses scrypt, and is consequently expensive. The context: is optional; this parameter is included when deriving the subkey material for obfuscating and tamper resistance, and may be used for separation of purpose or key rotation. The scrypt step is seasoned by a salt, which defaults to a fixed constant; set an application-specific salt, as in the example above, so that two applications inadvertently sharing a passphrase never derive the same keys.

Refer to the Epithet rdoc for the full set of configuration options.

Note that Epithet#decode returns nil when authentication fails, and raises Epithet::FormatError (an ArgumentError) on invalid formats.

Platform support

Epithet supports standard Ruby (aka MRI/CRuby), JRuby, and TruffleRuby. It uses your platform’s OpenSSL scrypt where available; on JRuby it falls back to the BouncyCastle provider bundled with jruby-openssl, and LibreSSL builds can fall back to the optional scrypt gem. To use the latter gem provider, your application must bundle and require scrypt before Epithet, we won’t require it on your behalf. All three providers produce identical key material. To force a provider without a capability check, pass its class in the scrypt parameters, e.g. scrypt: { provider: Epithet::Scrypt::BouncyCastle }; omit provider: to select one automatically.

Development

Install dependencies and run tests:

bundle install
rake test

Contributing

Bug reports and pull requests are welcome on GitHub at github.com/inopinatus/epithet.

Security considerations

See SECURITY.md.

License

The gem is available as open source under the terms of the MIT License.