libweb-id-perl 1.922-2 / usr / share / perl5 / Web / ID / FAQ.pod

=head1 NAME

Web::ID::FAQ - frequently asked questions about WebID

=head1 FREQUENTLY ASKED QUESTIONS

=head2 So what is WebID?

Web Identification and Discovery.

Firstly it's the concept of identifying people with HTTP URIs. URI
stands for Uniform Resource Identifier. While often used as identifiers
for web pages and other digital resources, they're just string
identifiers and may be used to identify anything - car parts, gorillas,
abstract concepts, and, yes, people.

WebID is also a protocol that allows websites to discover which URI
identifies you, using a secure certificate that is installed in your
browser.

=head2 URIs can identify non-digital resources?

Yes. Of course, if you type a URI which identifies a web page into a web
browser, you'd expect to see that web page (or an error message explaining
why you cannot), but if you type a URI which identifies a car part, don't
expect that spark plug to jump out of your screen into your hands.

URIs that identify non-digital resouces should either be unresolvable
(e.g. C<< urn:isbn:978-0099800200 >> which identifies a book - your
browser can't do anything with that URI); should produce an error message
explaining why the resource cannot be provided; or should redirect to
a digital resource (e.g. C<< http://example.com/id/alice >> might
identify Alice, and redirect to C<< http://example.com/data/alice >>
which is a document with information about Alice).

Further reading: I<Cool URIs for the Semantic Web>,
L<http://www.w3.org/TR/cooluris/>.

=head2 So I can use WebID to limit who has access to my site?

On its own, no.

WebID allows a website to establish an identifier for a visitor,
but what the website does with that information (whether it uses
it to block access to certain resources) is beyond the scope of
WebID.

=head2 How does WebID work?

In summary, your browser establishes an HTTPS connection to a web
server. As part of the SSL/TLS handshake, the server can request
that the browser identifies itself with a certificate. Your browser
then sends your certificate to the server. This certificate includes
a URI that identifies you.

Behind the scenes, the server fetches that URI, and retrieves a
profile document about you (this document can include as much or as
little personal data about you as you like). This document uses the
RDF data model, and contains data that allows the server to verify
that the certificate exchanged as part of your HTTPS request really
belongs to you.

The user experience is that a WebID user visits a WebID-enabled site;
their browser prompts them to pick a certificate from the list of
installed certificates; they choose; the site knows who they are.

No passwords are required (though many browsers do offer the option
to protect the installed certificates with a password).

=head2 So WebID requires HTTPS?

WebID could theoretically be used over other SSL/TLS protocols, such as
OpenVPN, secure IMAP/POP3 connections, and so forth.

But yes, it only works over secure connections. Really, would you want to
be identifying yourself over an insecure channel?

=head2 How can I use WebID in Perl?

For Plack/PSGI-based websites, there exists a module
L<Plack::Middleware::Auth::WebID> to make things (relatively) easy.
It stuffs the client's WebID URI into C<< $env->{WEBID} >>.

For Catalyst-based websites, be aware that recent versions of
Catalyst are built on Plack. See L<Catalyst::PSGI> for details.

Otherwise, you need to use L<Web::ID> directly. Assuming you've
configured your web server to request a client certificate from the
browser, and you've managed to get that client certificate into
Perl in PEM format, then it's just:

  my $webid  = Web::ID->new(certificate => $pem);
  my $uri    = $webid->uri;

And you have the URI.

What is PEM? Well, X509 certificates come in a variety of different
interrelated formats. PEM is a common one, and often what web servers
make available. If you have DER though, it's easy to convert it to
PEM:

  my $pem = "\n-----BEGIN CERTIFICATE-----\n"
          . encode_base64($der)
          . "\n-----END CERTIFICATE-----\n";

If you have another format, then OpenSSL may be able to convert it.

Once you have the URI, you can use it as a plain old string identifier
for the user, whenever you need to identify them in databases, etc.

The C<< $webid >> object in the above example, or in the Plack
middleware, C<< $env->{WEBID_OBJECT} >>, is an object blessed into
the L<Web::ID> package and will allow you to retrieve further
information about the user - their name, e-mail address, blog URL,
interests, friends, etc - depending on what information they've
chosen to include in their profile.

=head2 How does WebID compare to OpenID?

Both use URIs to identify people, however the way they choose their URIs
differs. In OpenID you use the same URI string to identify your blog or
homepage, and to identify yourself. In WebID you use different URIs to
identify different things - one URI for your blog, one for you.

In WebID you almost never have to type that URI - it's embedded into a
certificate in your browser's certificate store.

WebID doesn't require typing or passwords. This makes it more suitable
than OpenID for non-interactive processes (e.g. authenticated downloads
run via a cron job).

WebID requires a secure connection.

WebID is built upon the architecture of the Semantic Web.

=head1 SEE ALSO

L<Web::ID>.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

=head1 COPYRIGHT AND LICENCE

This software is copyright (c) 2012 by Toby Inkster.

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

This FAQ document is additionally available under the Creative Commons
Attribution-ShareAlike 2.0 UK: England and Wales licence
L<http://creativecommons.org/licenses/by-sa/2.0/uk/>, and the GNU
Free Documentation License version 1.3, or at your option any later
version L<http://www.gnu.org/licenses/fdl>.

=head1 DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.