added more documentation on redirect_request and get_protocol

[maypole.git] / lib / Maypole / Manual / Request.pod

diff --git a/lib/Maypole/Manual/Request.pod b/lib/Maypole/Manual/Request.pod
index d3d66f299c66d6116d27c2ba1dba747b23226471..64ee38b02d5dd8a4fe9eb16ab00ba7823d1e90a2 100644 (file)
--- a/lib/Maypole/Manual/Request.pod
+++ b/lib/Maypole/Manual/Request.pod
@@ -1,4 +1,8 @@
-=head1 Maypole Request Hacking Cookbook
+=head1 NAME
+
+Maypole::Manual::Request - Maypole Request Hacking Cookbook
+
+=head1 DESCRIPTION
 
 Hacks; design patterns; recipes: call it what you like, this chapter is a
 developing collection of techniques which can be slotted in to Maypole
@@ -49,6 +53,37 @@ or move the module loading to run-time (my preferred solution):
     BeerDB->setup("...");
     BeerDB::Beer->require;
 
+=head3 Redirecting to SSL for sensitive information
+
+You have a website with forms that people will be entering sensitive information into,
+such as credit cards or login details. You want to make sure that they aren't sent
+in plain text but over SSL instead.
+
+B<Solution>
+
+The solution is a bit tricky for 2 reasons :
+
+Firstly -- Many browsers and web clients will change a redirected 
+POST request into a GET request (which displays all that sensitive information in the
+browser, or access logs and possibly elsewhere) and/or drops the values on the floor.
+
+Secondly -- If somebody has sent that sensitive information in plain text already, then
+sending it again over SSL won't solve the problem.
+
+Redirecting a request is actually rather simple :
+
+$r->redirect_request('https://www.example.com/path'); # perldoc Maypole for API
+
+.. as is checking the protocol :
+
+$r->get_protocol(); # returns 'http' or 'https'
+ 
+You should check that the action that generates the form that people will enter
+the sensitive information into is https and redirect if not.
+
+You should also check that no information is lost when redirecting, possibly by 
+storing it in a session and retrieving it later - see Maypole::Plugin::Session
+
 =head3 Debugging with the command line
 
 You're seeing bizarre problems with Maypole output, and you want to test it in
@@ -598,16 +633,21 @@ to the original C<do_edit> routine. For instance, in this method,
 we use a L<Net::Amazon> object to fill in some fields of a database row
 based on an ISBN:
 
+    use Net::Amazon;
+    my $amazon = Net::Amazon->new(token => 'YOUR_AMZN_TOKEN');
+
+    ...
+
     sub create_from_isbn :Exported {
        my ($self, $r) = @_;
-       my $response = $ua->search(asin => $r->params->{isbn});
-       my ($prop) = $response->properties;
+       my $book_info = $amazon->search(asin => $r->params->{isbn})->properties;
+
        # Rewrite the CGI parameters with the ones from Amazon
-       @{$r->params->{qw(title publisher author year)} =            
-           ($prop->title,
-           $prop->publisher,
-           (join "/", $prop->authors()),
-           $prop->year());
+       $r->params->{title} = $book_info->title;
+       $r->params->{publisher} = $book_info->publisher;
+       $r->params->{year} = $book_info->year;
+       $r->params->{author} = join('and', $book_info->authors());
+ 
        # And jump to the usual edit/create routine
        $self->do_edit($r);
     }