The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

SXIP::Membersite - SXIP Membersite API

SYNOPSIS

    use SXIP::Membersite;

    my $ms = SXIP::Membersite->new;

    my $homesite_info = $ms->discover($homesite_path);

    if ($ms->verify(\%message, $persona_url)) {
        ...
    }

DESCRIPTION

SXIP::Membersite encapsulates core parts of the Simple eXtensible Identity Protocol, providing functionality required by SXIP Membersites (identity data consumers), compliant with version 2.0 of the SXIP protocol:

Discovery

The process of discovering a Homesite's protocol endpoint based on input typed in by a user.

Verification

The process of verifying that a) the Homesite that sent a message is authoritative for the user, and b) the Homesite did indeed send the message.

The package contains a simple demo Membersite to help you get started.

Integrating the SXIP protocol into your site has many benefits, including:

- Easier for the user to give rich identity data

- Single sign-on for all SXIP-enabled sites

- Verifiable third-party claims, which enable things like portable reputation

Visit http://sxip.org for information and support.

METHODS

my $ms = new(useragent = $useragent, logger => $logger)>

Returns a SXIP::Membersite object.

Parameters:

useragent

Specify an LWP::UsgerAgent-compatible HTTP client (optional). By default an agent is used that follows redirects (maximum 7), and has a timeout of 5 seconds.

logger

Specify a Log4perl-compatible logger object (optional). Logs to STDERR by default.

my $info = disover($homesite_path)

Attempts to discover the protocol endpoint URL of a Homesite, given some user input. If successful, it returns a hashref containing data about the Homesite. Right now it populates a single key, "endpoint", with the endpoint URL.

Example:

  Given: $homesite_path = "example.com"

  - expand URL to http://example.com.
  - fetch http://example.com/dix.html and http://example.com,
    looking for a Homesite delegation tag.
  - if we find a valid tag, return the endpoint URL.
  - if we find no valid tags, croak.
  - if anything goes wrong, croak.

Parameters:

$homesite_path

The data typed in by the user. Most likely a hostname, but possibly a domain name followed by a path. E.g. example.com, example.com/homesite.

verify(\%message, $persona_url)

Given a SXIP response message, and persona URL, attempts to verify that

a) the Homesite that sent a message is authoritative for the user, and

b) the Homesite did indeed send the message.

Note that the first verification step is optional, and only takes place if a persona URL is given.

Example:

  Given:
 
  $message['dix:/homesite-url'] = "http:/example.com/sxip"
  $persona_url = "http://example.com/personas/42"    

  - fetch "http://example.com/personas/42"
  - look for a persona delegation tag matching "http:/example.com/sxip"
  - if none found, croak
  - if found send a "verify-request" message to the Homesite
  - if the Homesite responds with dix:/true, return true
  - if the Homesite responds with dix:/false, return false
  - if anything goes wrong, croak

Parameters:

$message

The SXIP response message. Normally this will just be a hashref of all the POST parameters received by the Membersite. For a repeating POST parameter, the hash value should be an array ref.

$persona_url

The persona URL of the user (optional).

AUTHOR

Sxip Identity, <dev at sxip.org>

COPYRIGHT & LICENSE

The Sxip Identity Software License, Version 1

Copyright (c) 2004-2006 Sxip Identity Corporation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by Sxip Identity Corporation (http://sxip.org)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. The names "Sxip" and "Sxip Identity" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact bizdev@sxip.org.

5. Products derived from this software may not be called "Sxip", nor may "Sxip" appear in their name, without prior written permission of Sxip Identity Corporation.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES OR CONDITIONS, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SXIP NETWORKS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 332:

You forgot a '=back' before '=head1'