Fernet

Fernet allows you to easily generate and verify HMAC based authentication
tokens for issuing API requests between remote servers. It also encrypts
the message so it can be used to transmit secure data over the wire.

Fernet is usually served as a digestif after a meal but may also be served
with coffee and espresso or mixed into coffee and espresso drinks.

Fernet about it!

Installation

Fernet is distributed as a rubygem, so
either add gem 'fernet' to your application’s Gemfile or install it yourself
by running gem install fernet.

Usage

Both server and client must share a secret.

You want to encode some data in the token as well, for example, an email
address can be used to verify it on the other end.

token = Fernet.generate(secret, '[email protected]')

On the server side, the receiver can use this token to verify whether it’s
legit:

verifier = Fernet.verifier(secret, token)
if verifier.valid?
  operate_on(verifier.message) # the original, decrypted message
end

The verifier is valid if:

• The token was generated in the last 60 seconds (or some configurable TTL)
• The secret used to generate the token matches

Otherwise, verified will be false, and you should deny the request with an
HTTP 401, for example.

The specs
(spec/fernet_spec.rb)
have more usage examples.

Global configuration

It’s possible to configure fernet via the Configuration class. To do so, put
this in an initializer:

# default values shown here
Fernet::Configuration.run do |config|
  config.enforce_ttl = true
  config.ttl         = 60
end

Generating a secret

Generating appropriate secrets is beyond the scope of Fernet, but you should
generate it using /dev/random in a *nix. To generate a base64-encoded 256 bit
(32 byte) random sequence, try:

dd if=/dev/urandom bs=32 count=1 2>/dev/null | openssl base64

Ruby Compatibility

Fernet is compatible with Ruby 1.9 and above. It is tested on the rubies
available on this Travis CI configuration
file

Attribution

This library was largely made possible by Mr. Tom
Maher, who clearly articulated the mechanics
behind this process, and further found ways to make it
more
secure.

Similarly, Mr. Keith Rarick who implemented a Go
version and put together the Fernet
spec which is used by this project to
verify interoparability.

Contributing

Contributions are welcome via github pull requests.

To run the test suite:

• Clone the project
• Init submodules with git submodule init && git submodule update
• Run the suite: bundle exec rspec spec

Thanks to all contributors.

Security disclosures

If you find a security issue with Fernet, please report it by emailing
the fernet security list: [email protected]

License

Fernet is copyright © Harold Giménez and is released under the terms of the
MIT License found in the LICENSE file.