NAME
    Passwd::Keyring::PWSafe3 - Password storage based on Password Safe
    encrypted files

VERSION
    Version 0.10

SYNOPSIS
    Password Safe implementation of Passwd::Keyring. Passwords are stored in
    the Password Safe (http://passwordsafe.sourceforge.net) encrypted file.

    This module does not require Password Safe to be installed, and can be
    used as generic "store many passwords in file encrypted with single
    master password" storage. Password Safe GUI, if installed, may help the
    user to review, modify, or delete saved passwords.

    Note: actual handling of Password Safe format is based on Crypt::PWSafe3
    module. Passwd::Keyring::PWSafe3 just wraps it into the interface
    compatible with other Passwd::Keyring backends.

        use Passwd::Keyring::PWSafe3;

        my $keyring = Passwd::Keyring::PWSafe3->new(
             app=>"blahblah scraper",
             group=>"Johnny web scrapers",
             file=>"/home/joe/secrets.pwsafe3",        # HOME / passwd-keyring.pwsafe3 by default
             master_password=>"very secret password",  # Or callback. See ->new docs below
        );

        my $username = "John";  # or get from .ini, or from .argv...

        my $password = $keyring->get_password($username, "blahblah.com");
        unless( $password ) {
            $password = <somehow interactively prompt for password>;

            # securely save password for future use
            $keyring->set_password($username, "blahblah.com");
        }

        login_somewhere_using($username, $password);
        if( password_was_wrong ) {
            $keyring->clear_password($username, "blahblah.com");
        }

    Note: see Passwd::Keyring::Auto::KeyringAPI for detailed comments on
    keyring method semantics (this document is installed with
    `Passwd::Keyring::Auto' package).

CAVEATS
    Underlying module (Crypt::PWSafe3) in fact rewrites the whole file on
    every save (with the complete password list as read on init). This means
    that any attempts to use the file paralelly from a few programs, or from
    a few objects within one program, are doomed to cause lost updates.
    Also, all passwords from the file are kept in (unprotected) memory while
    keyring object is active. Therefore, it is recommended to use separate
    .psafe3 file for Passwd::Keyring::PWSafe3, not mixing it with possibly
    used normal Password Safe database, and to delete keyring object after
    it is no longer needed.

    There are some limitations in Crypt::PWSafe3 handling of Password Safe
    format. Passwords are read and saved properly and it is possible to
    alternate using them from perl, and via Password Safe GUI, but some less
    important aspects of the format, like password expiraton policy, may be
    ignored. Refer to Crypt::PWSafe3 docs for more details.

    Finally, at the moment the underlying implementation is very slow,
    depending on the CPU speed opening the ring may take from a few to even
    15-20 seconds, saving changes is much more costly (4-8 minutes on my
    weak laptop). As Crypt::PWSafe3 is at it's early version, one may hope
    for some performance tuning in the future. Using `lazy_save' constructor
    parameter reduces the cost somewhat, by avoiding costly save on every
    password change. It is also possible to construct passwords via Password
    Safe GUI and use this API only to read them.

DATA MAPPING
    Group name is mapped to Password Safe folder.

    Realm is mapped as password title.

    Username and password are ... well, used as username and password.

SUBROUTINES/METHODS
  new(app=>'app name', group=>'passwords folder', file=>'pwsafe3 file', master_password=>'secret or callback', lazy_save=>1)
    Initializes the processing. Croaks if Crypt::PWSafe3 is not installed or
    master password is invalid. May create password file if it is missing.

    Handled named parameters:

    - app - symbolic application name (used in password notes)

    - group - name for the password group (used as folder name)

    - file - location of .pwsafe3 file. If not given,
    `passwd-keyring.pwsafe3' in user home directory is used. Will be created
    if does not exist. Note: absolute path is required, relative paths are
    very error prone.

    - master_password - password required to unlock the file. Can be
    specified as string, or as callback returning a string (usually some way
    of interactively asking user for the password). The callback gets two
    parameters: app and file.

      If this param is missing, module will prompt interactively for this
      password using console prompt.

    - lazy_save - if given, asks not to save the file after every change
    (saving is fairly time consuming), but only when $keyring->save is
    called or when keyring is destroyed.

    Note: it of course does not make much sense to keep app passwords in
    encrypted storage if master password is saved in plain text. The module
    most natural usage is to interactively ask for master password (and use
    it to protect noticeable number of application-specific passwords).

  set_password(username, password, realm)
    Sets (stores) password identified by given realm for given user

  get_password($user_name, $realm)
    Reads previously stored password for given user in given app. If such
    password can not be found, returns undef.

  clear_password($user_name, $realm)
    Removes given password (if present)

  save
    Saves unsaved changes, if any are present.

    Important only when lazy_save was given in constructor.

  is_persistent
    Returns info, whether this keyring actually saves passwords
    persistently.

    (true in this case)

AUTHOR
    Marcin Kasperski

    Approach inspired by http://www.perlmonks.org/?node_id=869620.

BUGS
    Please report any bugs or feature requests to issue tracker at
    https://bitbucket.org/Mekk/perl-keyring-pwsafe3.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Passwd::Keyring::PWSafe3

    You can also look for information at:

    http://search.cpan.org/~mekk/Passwd-Keyring-PWSafe3/

    Source code is tracked at:

    https://bitbucket.org/Mekk/perl-keyring-pwsafe3

LICENSE AND COPYRIGHT
    Copyright 2012 Marcin Kasperski.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.