README.md in signed_form-0.0.1.pre1 vs README.md in signed_form-0.0.1
- old
+ new
@@ -1,24 +1,30 @@
# SignedForm
+[](http://badge.fury.io/rb/signed_form)
+[](https://travis-ci.org/erichmenge/signed_form)
+[](https://codeclimate.com/github/erichmenge/signed_form)
+
SignedForm brings new convenience and security to your Rails 4 or Rails 3 application.
## How It Works
-Traditionally, when you create a form with Rails you enter your fields using something like `f.input :name` and etc.
-Once you're done making your form you need to make sure that you've either set those parameters as accessible in the
-model (Rails 3) or use `permit` (Rails 4). This is redundant. Why would you make a form for a user to fill out and
-then not accept their input? Thus you need to always maintain this synchronization.
+Traditionally, when you create a form with Rails you enter your fields using something like `f.text_field :name` and so
+on. Once you're done making your form you need to make sure that you've either set those parameters as accessible in
+the model (Rails 3) or use `permit` (Rails 4). This is redundant. Why would you make a form for a user to fill out and
+then not accept their input? You need to always maintain this synchronization.
SignedForm generates a list of attributes that you have in your form and attaches them to be submitted with the form
along with a HMAC-SHA1 signature of those attributes to protect them from tampering. That means no more `permit` and
no more `attr_accessible`. It just works.
What this looks like:
``` erb
<%= signed_form_for(@user) do |f| %>
+ <% f.add_signed_fields :zipcode, :state # Optionally add additional fields to sign %>
+
<%= f.text_field :name %>
<%= f.text_field :address %>
<%= f.submit %>
<% end %>
```
@@ -38,13 +44,11 @@
Of course, you're free to continue using the standard `form_for`. `SignedForm` is strictly opt-in. It won't change the
way you use standard forms.
## Alpha Quality Software
-Because of the security sensitive nature of this gem I'm releasing this as 0.0.1.pre1 until I can get some more eyeballs
-on the code. This software should not be considered production ready. At this time it is only suitable for
-experimentation.
+This software should not be considered production ready. At this time it is only suitable for experimentation.
Now that I've made that disclaimer, you should know that SignedForm is functional.
## Requirements
@@ -55,40 +59,61 @@
## Installation
Add this line to your application's Gemfile:
- gem 'signed_form', '0.0.1.pre1'
+ gem 'signed_form', '~> 0.0.1'
And then execute:
$ bundle
If you're using Rails 3, you'll also need to install the [strong_parameters](https://github.com/rails/strong_parameters)
gem. Please set it up as instructed on the linked GitHub repo.
If you're using Rails 4, it works out of the box.
+You'll need to include `SignedForm::ActionController::PermitSignedParams` in the controller(s) you want to use SignedForm with. This can
+be done application wide by adding the `include` to your ApplicationController.
+
+``` ruby
+ApplicationController < ActionController::Base
+ include SignedForm::ActionController::PermitSignedParams
+
+ # ...
+end
+```
+
You'll also need to create an initializer:
$ echo 'SignedForm::HMAC.secret_key = SecureRandom.hex(64)' > config/initializers/signed_form.rb
**IMPORTANT** Please read below for information regarding this secret key.
+## Support for other Builders
+
+* [SimpleForm](https://github.com/erichmenge/signed_form-simple_form)
+
## Special Considerations
If you're running only a single application server the above initializer should work great for you, with a couple of
caveats. If a user is in process of filling out a form and you restart your server, their form will be invalidated.
You could pick a secret key using `rake secret` and put that in the initializer instead, but then in the event you
remove a field someone could still access it using the old signature if some malicious person were to keep it around.
If you're running multiple application servers, the above initializer will not work. You'll need to keep the key in sync
between all the servers. The security caveat with that is that if you ever remove a field from a form without updating
-that secret key, a malicious user could still access the field with the old signature. So you'll probably want to
-choose a new secret in the event you remove access to an attribute in a form.
+that secret key, a malicious user could still access the field with the old signature. So you'll probably want to choose
+a new secret in the event you remove access to an attribute in a form.
My above initializer example errs on the side of caution, generating a new secret key every time the app starts up. Only
you can decide what is right for you with respect to the secret key.
+
+### Caching
+
+Another consideration to be aware of is caching. If you cache a form, and then change the secret key that form will
+perpetually submit parameters that fail verification. So if you want to cache the form you should tie the cache key to
+something that will be changed whenever the secret key changes.
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)