Commits

Toby Inkster  committed d2a834e

add FAQ

  • Participants
  • Parent commits bd3992f

Comments (0)

Files changed (1)

File lib/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.
+