NAME

CGI::Auth::FOAF_SSL - authentication using WebID (FOAF+SSL)

SYNOPSIS

  use CGI qw(:all);
  use CGI::Auth::FOAF_SSL;
  
  my $auth = CGI::Auth::FOAF_SSL->new_from_cgi;
  
  print header(-type=>'text/html', -cookie=>$auth->cookie);
  
  if (defined $auth && $auth->is_secure)
  {
    if (defined $auth->subject)
    {
      printf("<p>Hello <a href='%s'>%s</a>!</p>\n",
             escapeHTML($auth->subject->homepage),
             escapeHTML($auth->subject->name));
    }
    else
    {
      print "<p>Hello!</p>\n";
    }
  }
  else
  {
    print "<p>Greetings stranger!</p>\n";
  }

DESCRIPTION

FOAF+SSL (a.k.a. WebID) is a simple authentication scheme described at http://esw.w3.org/topic/foaf+ssl. This module implements the server end of FOAF+SSL in Perl.

It is suitable for handling authentication using FOAF+SSL over HTTPS. Your web server needs to be using HTTPS, configured to request client certificates, and make the certificate PEM available to your script. If you are using Apache, this means that you want to set the following directives in your SSL virtual host setup:

 SSLEngine on
 SSLVerifyClient optional_no_ca
 SSLVerifyDepth  1
 SSLOptions +StdEnvVars +ExportCertData

Configuration

$CGI::Auth::FOAF_SSL::ua_string = 'MyTool/1.0'
Set the User-Agent string for any HTTP requests.

Constructors

new($pem_encoded)
Performs FOAF+SSL authentication on a PEM-encoded key. If authentication is completely unsuccessful, returns undef. Otherwise, returns a CGI::Auth::FOAF_SSL object. Use is_secure to check if authentication was completely successful.

You probably want to use new_from_cgi instead.

(DER encoded certificates should work too.)
new_from_cgi($cgi_object)
Performs FOAF+SSL authentication on a CGI object. This is a wrapper around new which extracts the PEM-encoded client certificate from the CGI request. It has the same return values as new.

If $cgi_object is omitted, uses CGI->new instead.

Public Methods

is_secure
Returns true iff the FOAF+SSL authentication process was completely successful.
subject
Returns a CGI::Auth::FOAF_SSL::Agent object which represents the subject of the certificate.

This method has aliases agent and certified_thing for back-compat reasons.
cookie
HTTP cookie related to the authentication process. Sending this to the client isn't strictly necessary, but it allows for a session to be established, greatly speeding up subsequent accesses. See also the COOKIES section of this documentation.

COOKIES

FOAF+SSL is entirely RESTful: there is no state kept between requests. This really simplifies authentication for both parties (client and server) for one-off requests. However, because FOAF+SSL requires the server to make various HTTP requests to authenticate the client, each request is slowed down significantly.

Cookies provide us with a way of speeding this up. Use of cookies is entirely optional, but greatly increases the speed of authentication for the second and subsequent requests a client makes. If your FOAF+SSL-secured service generally requires clients to make multiple requests in a short period, you should seriously consider using cookies to speed this up.

The method works like this: on the first request, authentication happens as normal. However, all RDF files relevant to authenticating the client are kept on disk (usually somewhere like '/tmp') in N-Triples format. They are associated with a session that is given a randomly generated identifier. This random identifier is sent the client as a cookie. On subsequent requests, the client includes the cookie and thus CGI::Auth::FOAF_SSL is able to retrieve the data it needs from disk in N-Triples format, rather than having to reach out onto the web for it again.

To use this feature, you must perform authentication before printing anything back to the client, use CGI::Auth::FOAF_SSL's cookie method, and then pass that to the client as part of the HTTP response header.

  use CGI qw(:all);
  use CGI::Auth::FOAF_SSL;
  
  my $auth = CGI::Auth::FOAF_SSL->new_from_cgi;
  
  if (defined $auth && $auth->is_secure)
  {
    print header('-type' => 'text/html',
                 '-cookie' => $auth->cookie);

    my $user = $auth->agent;
    # ...
  }
  else # anonymous access
  {
    print header('-type' => 'text/html');
    
    # ...
  }

Old sessions are automatically purged after an hour of inactivity.

BUGS

Please report any bugs to http://rt.cpan.org/.

AUTHOR

Toby Inkster, <tobyink@cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.