NAME

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

FREQUENTLY ASKED QUESTIONS

   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.

   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.
       "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. "http://example.com/id/alice" might
       identify Alice, and redirect to "http://example.com/data/alice" which is a document with
       information about Alice).

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

   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.

   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).

   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?

   How can I use WebID in Perl?
       For Plack/PSGI-based websites, there exists a module Plack::Middleware::Auth::WebID to
       make things (relatively) easy.  It stuffs the client's WebID URI into "$env->{WEBID}".

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

       Otherwise, you need to use 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 $webid object in the above example, or in the Plack middleware,
       "$env->{WEBID_OBJECT}", is an object blessed into the 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.

   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.

SEE ALSO

       Web::ID.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

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
       http://creativecommons.org/licenses/by-sa/2.0/uk/ <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 <http://www.gnu.org/licenses/fdl>.

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.