NAME

Crypt::PWSafe3 - Read and write Passwordsafe v3 files

SYNOPSIS

 use Crypt::PWSafe3;
 my $vault = Crypt::PWSafe3->new(file => 'filename.psafe3', password => 'somesecret');
 
 # fetch all database records
 my @records = $vault->getrecords();
 foreach my $record (@records) {
   print $record->uuid;
   print $record->title;
   print $record->passwd;
   # see Crypt::PWSafe3::Record for more details on accessing records
 }

 # same as above but don't detach records from vault
 foreach my $uuid ($vault->looprecord) {
   # either change a record
   $vault->modifyrecord($uuid, passwd => 'p1');

   # or just access it directly
   print $vault->{record}->{$uuid}->title;
 }

 # add a new record
 $vault->newrecord(user => 'u1', passwd => 'p1', title => 't1');

 # modify an existing record
 $vault->modifyrecord($uuid, passwd => 'p1');

 # replace a record (aka edit it)
 my $record = $vault->getrecord($uuid);
 $record->title('t2');
 $record->passwd('foobar');
 $vault->addrecord($record);

 # mark the vault as modified (not required if
 # changes were done with ::modifyrecord()
 $vault->markmodified();

 # save the vault
 $vault->save();

 # save it under another name using another password
 $vault->save(file => 'another.pwsafe3', passwd => 'blah'); 

 # access database headers
 print $vault->getheader('wholastsaved')->value();
 print scalar localtime($vault->getheader('lastsavetime')->value());

 # add/replace a database header
 my $h = Crypt::PWSafe3::HeaderField->new(name => 'savedonhost', value => 'localhost');
 $vault->addheader($h);

DESCRIPTION

Crypt::PWSafe3 provides read and write access to password database files created by Password Safe V3 (and up) available at http://passwordsafe.sf.net.

METHODS

new()

The new() method creates a new Crypt::PWSafe3 object. Any parameters must be given as hash parameters.

 my $vault = Crypt::PWSafe3->new(
                     file     => 'vault.psafe3',
                     password => 'secret',
                     whoami   => 'user1',
                     program  => 'mypwtool v1',
                     create   => 0,   # or 1
 );

Mandatory parameters:

file: Specifies the password safe (v3) file. If it exists it will be read in. Otherwise it will be created if you call save().
password: The password required to decrypt the password safe file.

Optional parameters:

whoami: Specifies the user who saves the password safe file. If omitted the environment variable USER will be used when calling save().
program: Specifies which program saved the password safe file. If omitted, the content of the perl variable $0 will be used, which contains the name of the current running script.
create: If set to 0, new() will fail if the file doesn't exist, otherwise it will try to create it. Enabled by default.

The optional parameters will become header fields of the password safe file. You can manually set/override more headers. See section addheader() for more details.

getrecords()

Returns a list of all records found in the password safe file. Each element is an Crypt::PWSafe3::Record object.

A record object is identified by its UUID4 value, which is a unique identifier. You can access the uuid by:

 $record->uuid

Accessing other record properties works the same. For more details, refer to Crypt::PWSafe3::Record.

Note: record objects returned by getrecords() are still associated with the Crypt::PWSafe3 object. So, if you modify a field of such a record, the change will be populated back into the vault. Of course you'd still need to save it.

Sample:

 foreach my $rec ($vault->getrecords) {
   $rec->note('blah fasel');
 }
 $vault->save();

However, it's also possible to use the modifyrecord() method, see below.

looprecord()

Returns a list of UUIDs of all known records. You can use this list to iterate over the records without copying them and optionally changing them in place.

Example:

 foreach my $uuid ($vault->looprecord) {
   # either change a record
   $vault->modifyrecord($uuid, passwd => 'p1');

   # or just access it directly
   print $vault->{record}->{$uuid}->title;
 }

modifyrecord(uuid, parameter-hash)

Modifies the record identified by the given UUID using the values of the supplied parameter hash.

Example:

   $vault->modifyrecord($uuid, passwd => 'p1');

The parameter hash may contain any valid record field type with according values. Refer to Crypt::PWSafe3::Record for details about available fields.

newrecord(parameter-hash)

Create a new record. The UUID of the record will be generated automatically. Refer to Crypt::PWSafe3::Record for details about available fields.

addrecord(Crypt::PWSafe3::Record object)

Add a record to the vault. The record must be an Crypt::PWSafe3::Record object.

deleterecord(uuid)

Delete the record identified by the given UUID.

save([parameter-hash])

Save the current password safe vault back to disk.

If not otherwise specified, use the same file and password as we used to open it initially. If the file doesn't exist it will be created.

You may specify another filename and password here by using a parameter hash.

Example:

 $vault->save(file => 'anotherfile.psafe3', passwd => 'foo');

Please note, that the vault will be written to a temporary file first, then this temporary file will be read in and if that works, it will be moved over the destination file. This way the original file persists if the written database gets corrupted by some unknown reason (a bug for instance).

getheader(name)

Returns a raw Crypt::PWSafe3::HeaderField object. Refer to Crypt::PWSafe3::HeaderField for details how to access it.

addheader(object)

Adds a header field to the password safe database. The object parameter must be an Crypt::PWSafe3::HeaderField object.

If the header already exists it will be replaced.

Refer to Crypt::PWSafe3::HeaderField for details how to create new ones .

AUTHOR

T.v.Dein <tlinden@cpan.org>

BUGS

Report bugs to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Crypt-PWSafe3.

COPYRIGHT

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms of the Artistic License 2.0, see: <http://www.perlfoundation.org/artistic_license_2_0>

VERSION

Crypt::PWSafe3 Version 1.22.