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!
Fernet is distributed as a rubygem, so
gem 'fernet' to your application's Gemfile or install it yourself
gem install fernet.
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@example.com')
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
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.
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
Fernet is compatible with Ruby 1.9 and above. It is tested on the rubies available on this Travis CI configuration file
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.
If you find a security issue with Fernet, please report it by emailing the fernet security list: firstname.lastname@example.org
Fernet is copyright (c) Harold Giménez and is released under the terms of the MIT License found in the LICENSE file.