.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Web::ID::FAQ 3pm" .TH Web::ID::FAQ 3pm "2012-05-02" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Web::ID::FAQ \- frequently asked questions about WebID .SH "FREQUENTLY ASKED QUESTIONS" .IX Header "FREQUENTLY ASKED QUESTIONS" .SS "So what is WebID?" .IX Subsection "So what is WebID?" Web Identification and Discovery. .PP Firstly it's the concept of identifying people with \s-1HTTP\s0 URIs. \s-1URI\s0 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. .PP WebID is also a protocol that allows websites to discover which \s-1URI\s0 identifies you, using a secure certificate that is installed in your browser. .SS "URIs can identify non-digital resources?" .IX Subsection "URIs can identify non-digital resources?" Yes. Of course, if you type a \s-1URI\s0 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 \s-1URI\s0 which identifies a car part, don't expect that spark plug to jump out of your screen into your hands. .PP URIs that identify non-digital resouces should either be unresolvable (e.g. \f(CW\*(C`urn:isbn:978\-0099800200\*(C'\fR which identifies a book \- your browser can't do anything with that \s-1URI\s0); should produce an error message explaining why the resource cannot be provided; or should redirect to a digital resource (e.g. \f(CW\*(C`http://example.com/id/alice\*(C'\fR might identify Alice, and redirect to \f(CW\*(C`http://example.com/data/alice\*(C'\fR which is a document with information about Alice). .PP Further reading: \fICool URIs for the Semantic Web\fR, . .SS "So I can use WebID to limit who has access to my site?" .IX Subsection "So I can use WebID to limit who has access to my site?" On its own, no. .PP 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. .SS "How does WebID work?" .IX Subsection "How does WebID work?" In summary, your browser establishes an \s-1HTTPS\s0 connection to a web server. As part of the \s-1SSL/TLS\s0 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 \s-1URI\s0 that identifies you. .PP Behind the scenes, the server fetches that \s-1URI\s0, 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 \&\s-1RDF\s0 data model, and contains data that allows the server to verify that the certificate exchanged as part of your \s-1HTTPS\s0 request really belongs to you. .PP 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. .PP No passwords are required (though many browsers do offer the option to protect the installed certificates with a password). .SS "So WebID requires \s-1HTTPS\s0?" .IX Subsection "So WebID requires HTTPS?" WebID could theoretically be used over other \s-1SSL/TLS\s0 protocols, such as OpenVPN, secure \s-1IMAP/POP3\s0 connections, and so forth. .PP But yes, it only works over secure connections. Really, would you want to be identifying yourself over an insecure channel? .SS "How can I use WebID in Perl?" .IX Subsection "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 \s-1URI\s0 into \f(CW\*(C`$env\->{WEBID}\*(C'\fR. .PP For Catalyst-based websites, be aware that recent versions of Catalyst are built on Plack. See Catalyst::PSGI for details. .PP 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 \s-1PEM\s0 format, then it's just: .PP .Vb 2 \& my $webid = Web::ID\->new(certificate => $pem); \& my $uri = $webid\->uri; .Ve .PP And you have the \s-1URI\s0. .PP What is \s-1PEM\s0? Well, X509 certificates come in a variety of different interrelated formats. \s-1PEM\s0 is a common one, and often what web servers make available. If you have \s-1DER\s0 though, it's easy to convert it to \&\s-1PEM:\s0 .PP .Vb 3 \& my $pem = "\en\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-\en" \& . encode_base64($der) \& . "\en\-\-\-\-\-END CERTIFICATE\-\-\-\-\-\en"; .Ve .PP If you have another format, then OpenSSL may be able to convert it. .PP Once you have the \s-1URI\s0, you can use it as a plain old string identifier for the user, whenever you need to identify them in databases, etc. .PP The \f(CW$webid\fR object in the above example, or in the Plack middleware, \f(CW\*(C`$env\->{WEBID_OBJECT}\*(C'\fR, 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 \s-1URL\s0, interests, friends, etc \- depending on what information they've chosen to include in their profile. .SS "How does WebID compare to OpenID?" .IX Subsection "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 \s-1URI\s0 string to identify your blog or homepage, and to identify yourself. In WebID you use different URIs to identify different things \- one \s-1URI\s0 for your blog, one for you. .PP In WebID you almost never have to type that \s-1URI\s0 \- it's embedded into a certificate in your browser's certificate store. .PP 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). .PP WebID requires a secure connection. .PP WebID is built upon the architecture of the Semantic Web. .SH "SEE ALSO" .IX Header "SEE ALSO" Web::ID. .SH "AUTHOR" .IX Header "AUTHOR" Toby Inkster . .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" This software is copyright (c) 2012 by Toby Inkster. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. .PP This \s-1FAQ\s0 document is additionally available under the Creative Commons Attribution-ShareAlike 2.0 \s-1UK:\s0 England and Wales licence http://creativecommons.org/licenses/by\-sa/2.0/uk/ , and the \s-1GNU\s0 Free Documentation License version 1.3, or at your option any later version . .SH "DISCLAIMER OF WARRANTIES" .IX Header "DISCLAIMER OF WARRANTIES" \&\s-1THIS\s0 \s-1PACKAGE\s0 \s-1IS\s0 \s-1PROVIDED\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1AND\s0 \s-1WITHOUT\s0 \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0 \&\s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1WITHOUT\s0 \s-1LIMITATION\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \&\s-1MERCHANTIBILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.