NAME
CGI::Auth::FOAF_SSL - authentication using FOAF+SSL (WebID)
SYNOPSIS
use CGI qw(:all);
use CGI::Auth::FOAF_SSL;
my $auth = CGI::Auth::FOAF_SSL->new_from_cgi( CGI->new );
print header('-type' => 'text/html', '-cookie' => $auth->cookie);
if (defined $auth && $auth->is_secure)
{
if (defined $auth->agent)
{
printf("
Hello %s!
\n",
escapeHTML($auth->agent->homepage),
escapeHTML($auth->agent->name));
}
else
{
print "Hello!
\n";
}
}
else
{
print "Greetings stranger!
\n";
}
VERSION
1.000
DESCRIPTION
FOAF+SSL (a.k.a. WebID) is a simple authentication scheme described at
. This module provides FOAF+SSL
authentication for CGI scripts written in Perl.
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
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".
If $cgi_object is omitted, uses "CGI->new" instead.
"$auth = CGI::Auth::FOAF_SSL->new_unauthenticated($pem_encoded)"
Creates a CGI::Auth::FOAF_SSL object without doing any
authentication.
It's very unlikely you want to do this. If you do create an
unauthenticated object, then you'll probably want to do some
authentication using the authenticate_by_XXX methods.
Public Methods
"$bool = $auth->is_secure"
Returns true iff the authentication process was completely
successful.
"$agent = $auth->agent"
Returns a CGI::Auth::FOAF_SSL::Agent object which represents the
agent making the request.
"$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. See also
the COOKIES section of this documentation.
"$ok = $auth->authenticate_by_uri($uri)"
Checks if $uri claims that $auth's key identifies it.
This is only relevent if you constructed $auth using
"new_unauthenticated".
"$ok = $auth->authenticate_by_email($email_address)"
Checks if $email_address claims that $auth's key identifies it (via
WebFinger/Fingerpoint).
This is only relevent if you constructed $auth using
"new_unauthenticated".
"$ok = $auth->authenticate_by_sparql($uri, $endpoint)"
Checks if $endpoint claims that $auth's key identifies $uri.
$endpoint may be a SPARQL endpoint URI or an RDF::Trine::Model.
This is only relevent if you constructed $auth using
"new_unauthenticated".
Utility Methods
"$model = $auth->get_trine_model($uri)"
Get an RDF::Trine::Model corresponding to a URI.
"$bi = $auth->make_bigint_from_node($trine_node)"
Turns an RDF::Trine::Node::Literal object into a Math::BigInt
representing the same number.
There are optional named parameters for providing a fallback in the
case where $trine_node has an unrecognised datatype or is not a
literal.
$bi = $auth->make_bigint_from_node(
$trine_node, fallback=>$other_node, fallback_type=>'hex');
The authenticate_by_XXX methods use this.
"$results = $auth->execute_query($sparql)"
Returns the results of a SPARQL query. Uses the certificate
subject's RDF file as a data source, or the certificate subject's
SPARQL endpoint.
See RDF::TrineShortcuts function rdf_query for an explanation of the
return format.
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 .
SEE ALSO
Helper module: CGI::Auth::FOAF_SSL::Agent
Related modules: CGI, RDF::Trine, RDF::ACL.
Information about FOAF+SSL:
,
.
SSL in Apache: .
Mailing list for general Perl RDF/SemWeb discussion and support:
.
AUTHOR
Toby Inkster,
COPYRIGHT AND LICENSE
Copyright (C) 2009-2010 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 or, at your
option, any later version of Perl 5 you may have available.