NAME

    Crypt::OpenToken - Perl implementation of Ping Identity's "OpenToken"

SYNOPSIS

      use Crypt::OpenToken;
    
      my $data = {
          foo => 'bar',
          bar => 'baz',
      };
    
      # create an OpenToken factory based on a given shared password
      my $factory = Crypt::OpenToken->new(password => 'abc123');
    
      # encrypt a hash-ref of data into an OpenToken.
      my $token_str = $factory->create(
          Crypt::OpenToken::CIPHER_AES128,
          $data,
      );
    
      # decrypt an OpenToken, check if its valid, and get data back out
      my $token = $factory->parse($token_str);
      if ($token->is_valid) {
          $data = $token->data();
      }

DESCRIPTION

    This module provides a Perl implementation of the "OpenToken" standard
    as defined by Ping Identity in their IETF Draft.

METHODS

    Crypt::OpenToken->new(password => $password)

      Instantiates a new OpenToken factory, which can encrypt/decrypt
      OpenTokens using the specified shared $password.

    $factory->create($cipher, $data)

      Encrypts the given hash-ref of $data using the specified $cipher
      (which should be one of the CIPHER_* constants).

      Returns back to the caller a Base64 encoded string which represents
      the OpenToken.

      NOTE: during the encryption of the OpenToken, a random Initialization
      Vector will be selected; as such it is not possible to encrypt the
      same data more than once and get the same OpenToken back.

    $factory->parse($token)

      Decrypts a Base64 encoded OpenToken, returning a
      Crypt::OpenToken::Token object back to the caller. Throws a fatal
      exception in the event of an error.

      It is the callers responsibility to then check to see if the token
      itself is valid (see Crypt::OpenToken::Token for details).

CONSTANTS

    The following constant values are available for selecting an encryption
    cipher to use:

    Crypt::OpenToken::CIPHER_NULL

      "Null" encryption (e.g. no encryption whatsoever). Requires
      Crypt::NULL.

    Crypt::OpenToken::CIPHER_AES256

      "AES" encryption, 256-bit. Requires Crypt::Rijndael.

    Crypt::OpenToken::CIPHER_AES128

      "AES" encryption, 128-bit. Requires Crypt::Rijndael.

    Crypt::OpenToken::CIPHER_DES3

      "TripleDES" encryption, 168-bit. Requires Crypt::DES.

CAVEATS

      * This module does not (yet) support the "obfuscate password" option
      that is configurable within PingFederate's OpenToken adapter.

AUTHOR

    Graham TerMarsch (cpan@howlingfrog.com)

    Shawn Devlin (shawn.devlin@socialtext.com)

 Contributors

    Thanks to those who have provided feedback, comments, and patches:

      Jeremy Stashewsky
      Travis Spencer

 Sponsors

    BIG thanks also go out to those who sponsored Crypt::OpenToken:

    Socialtext

      Thanks for sponsoring the initial development of Crypt::OpenToken,
      and then being willing to release it to the world.

    Ping Identity

      Thanks for your assistance during the initial development, providing
      feedback along the way, and answering our questions as they arose.

COPYRIGHT & LICENSE

 Crypt::OpenToken

    Crypt::OpenToken is Copyright (C) 2010, Socialtext, and is released
    under the Artistic-2.0 license.

 OpenToken specification

    The OpenToken specification is Copyright (C) 2007-2010 Ping Identity
    Corporation, and released under the MIT License:

      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
      "Software"), to deal in the Software without restriction, including
      without limitation the rights to use, copy, modify, merge, publish,
      distribute, sub-license, and/or sell copies of the Software, and to
      permit persons to whom the Software is furnished to do so, subject to
      the following conditions:

      The above copyright notice and this permission notice shall be
      included in all copies or substantial portions of the Software.

      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
      NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
      BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
      ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
      CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      SOFTWARE.

SEE ALSO

    http://tools.ietf.org/html/draft-smith-opentoken-02

    http://www.pingidentity.com/opentoken