rails_cook

A library to verify and decrypt Ruby on Rails session cookies written in Erlang.

Requirements

Requires Erlang/OTP >= 22.

Erlang/OTP >= 22 is required due to the use of the new crypto API.

Summary

Want to reuse a session created by a Ruby on Rails application for an Erlang service, such as a web API or websocket server?

try rails_cook:verify_and_decrypt(auto, <<"secret key base">>, <<"cookie">>) of
  {RailsVersion, CookiePayload} -> jiffy:decode(CookiePayload) % or your preferred deserialization
catch
  error:bad_sig -> "Invalid session cookie";
  error:unknown_rails_version -> "Unable to determine Rails version"
end

The auto argument will ask the library to attempt to automatically infer the Rails version that created the cookie. Rails went though a couple of different cookie storage formats over the years (supported are 4 and 5.1. Version 3 or less is not supported due to the cookie payload being serialized with Ruby object marshaling).

Instead of auto, you can specify the version explicitly:

rails_cook:verify_and_decrypt(rails_5_1, <<"secret key base">>, <<"cookie">>)

The utilized decryption/verification and HMAC digest algorithms are configurable, as they are in Rails, so if you changed the defaults in your Rails setup, you should be able to get this library to decrypt your cookie. Reasonable defaults are assumed:

Purpose	Rails 4	Rails 5
HMAC digest	SHA-1	SHA-1
Decryption/Verification	AES-256-CBC	AES-256-GCM

To override any property, just pass an additional proplist to any of the functions. All exported functions have a variant that expects a proplist as the final argument:

try rails_cook:verify_and_decrypt(rails_4,
                                  <<"secret key base">>,
                                  <<"cookie">>,
                                  [{'hmac_hash_alg', md5}]) of
  % ...
catch
  % ...
end

A full list of settings is given here:

Setting	Description
hmac_hash_alg	Sets the HMAC digest algorithm to be used for signed cookies Rails config setting: config.action_dispatch.signed_cookie_digest Default: sha
cipher_alg	Sets the cipher to be used for decryption/verification of encrypted cookies Rails config setting: config.action_dispatch.encrypted_cookie_cipher Default: aes_256_cbc, aes_256_gcm
encrypted_cookie_salt	Cookie salt (encrypted cookies) Rails config setting: config.action_dispatch.encrypted_cookie_salt Default: <<"encrypted cookie">>
encrypted_signed_cookie_salt	Cookie salt (encrypted & signed cookies) Rails config setting: config.action_dispatch.encrypted_signed_cookie_salt Default: <<"signed encrypted cookie">>
authenticated_encrypted_cookie_salt	Cookie salt (authenticated & encrypted cookies) Rails config setting: config.action_dispatch.authenticated_encrypted_cookie_salt Default: <<"authenticated encrypted cookie">>

To Do

This library currently makes no effort to actually deserialize the cookie payload. Whether it should do so, or leave that to you is being considered.

The API is not yet stable, and may change with updates.