/ 
CGI-Auth-FOAF_SSL-0.50
/ CGI::Auth::FOAF_SSL

NAME

CGI::Auth::FOAF_SSL - Authentication using FOAF+SSL.

VERSION

0.50

SYNOPSIS

use CGI qw(:all);
use CGI::Auth::FOAF_SSL;

my $cgi  = CGI->new;
my $auth = CGI::Auth::FOAF_SSL->new_from_cgi($cgi);

print header('-type' => 'text/html', '-cookie' => $auth->cookie);

if (defined $auth && $auth->is_secure)
{
	if (defined $auth->agent)
	{
		printf("<p>Hello <a href='%s'>%s</a>! You are logged on with FOAF+SSL.</p>\n",
			escapeHTML($auth->agent->homepage),
			escapeHTML($auth->agent->name));
	}
	else
	{
		print "<p>Hello! You are logged on with FOAF+SSL.</p>\n";
	}
}
else
{
	print "<p>Greetings stranger. You are unknown in these parts.</p>\n";
}

DESCRIPTION

FOAF+SSL is a simple authentication scheme described at http://esw.w3.org/topic/foaf+ssl. This module provides FOAF+SSL authentication for CGI scripts.

This requires the web server to be using HTTPS and to be configured to request client certificates and to pass the certificate details on as environment variables for scripts. If you are using Apache, this means that you want to set the following directives in your SSL virtual host setup:

SSLEngine on
# SSLCipherSuite (see Apache documentation)
# SSLProtocol (see Apache documentation)
# SSLCertificateFile (see Apache documentation)
# SSLCertificateKeyFile (see Apache documentation)
SSLVerifyClient optional_no_ca
SSLVerifyDepth  1
SSLOptions +StdEnvVars +ExportCertData

As of version 0.50, this package no longer uses RDF::Redland, using RDF::Trine and RDF::Query instead.

CONFIGURATION

$CGI::Auth::FOAF_SSL::path_openssl = '/usr/bin/openssl'

Set the path to the OpenSSL binary.

$CGI::Auth::FOAF_SSL::ua_string = 'MyTool/1.0'

Set the User-Agent string for any HTTP requests.

CONSTRUCTORS

$auth = CGI::Auth::FOAF_SSL->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.

$auth = CGI::Auth::FOAF_SSL->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.

PUBLIC METHODS

$cookie = $auth->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.

$bool = $auth->is_secure

Returns true iff the authentication process was completely successful.

$agent = $auth->agent

Returns an object which represents the agent making the request. This object includes the following methods: name, homepage, mbox and img.

Another method included is identity which returns the RDF URI representing the agent.

$account = $auth->account

Returns an object which represents the account making the request. This object includes the following methods: name, homepage.

Another method included is identity which returns the RDF URI representing the account.

$thing = $auth->certified_thing

Returns an object representing the thing which the certificate belongs to. This object includes a method called identity which returns its RDF URI.

Usually you will want to use agent or account instead.

UTILITY METHOD

$model = $auth->get_trine_model($uri);

Get an RDF::Trine::Model corresponding to a URI.

BUGS

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

SEE ALSO

http://lists.foaf-project.org/mailman/listinfo/foaf-protocols, http://esw.w3.org/topic/foaf+ssl.

CGI, RDF::Trine.

http://httpd.apache.org/docs/2.0/mod/mod_ssl.html.

http://www.perlrdf.org/.

AUTHOR

Toby Inkster, <tobyink@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Toby Inkster

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.