/ 
Palm-Keyring-0.93
River stage zero No dependents
/ Palm::Keyring

NAME

Palm::Keyring - Handler for Palm Keyring databases.

DESCRIPTION

The Keyring PDB handler is a helper class for the Palm::PDB package. It parses Keyring for Palm OS databases. See http://gnukeyring.sourceforge.net/.

It has the standard Palm::PDB methods with 2 additional public methods. Decrypt and Encrypt.

It currently supports the v4 Keyring databases. The v5 databases from the pre-release keyring-2.0 are not supported.

This module doesn't store the decrypted content. It only keeps it until it returns it to you or encrypts it.

SYNOPSIS

use Palm::PDB;
use Palm::Keyring;

my $pass = 'password';
my $file = 'Keys-Gtkr.pdb';
my $pdb  = new Palm::PDB;
$pdb->Load($file);

foreach (0..$#{ $pdb->{'records'} }) {
    next if $_ = 0; # skip the password record
    my $rec  = $pdb->{'records'}->[$_];
    my $acct = $pdb->Decrypt($rec, $pass);
    print $rec->{'name'}, ' - ', $acct->{'account'}, "\n";
}

SUBROUTINES/METHODS

new

$pdb = new Palm::Keyring([$password]);

Create a new PDB, initialized with the various Palm::Keyring fields and an empty record list.

Use this method if you're creating a Keyring PDB from scratch otherwise you can just use Palm::PDB::new() before calling Load().

If you pass in a password, it will initalize the first record with the encrypted password.

Encrypt

$pdb->Encrypt($rec, $acct[, $password]);

Encrypts an account into a record, either with the password previously used, or with a password that is passed.

$rec is a record from $pdb->{'records'} or a new_Record(). $acct is a hashref in the format below.

my $acct = {
    name       => $rec->{'name'},
    account    => $account,
    password   => $password,
    notes      => $notes,
    lastchange => {
        year  => 107, # years since 1900
        month =>   0, # 0-11, 0 = January, 11 = December
        day   =>  30, # 1-31, same as localtime
    },
};

If you have changed anything other than the lastchange, or don't pass in a lastchange key, Encrypt() will generate a new lastchange date for you.

If you pass in a lastchange field that is different than the one in the record, it will honor what you passed in.

Encrypt() only uses the $acct->{'name'} if there is not already a $rec->{'name'}.

Decrypt

my $acct = $pdb->Decrypt($rec[, $password]);

Decrypts the record and returns a hashref for the account as described under Encrypt().

foreach (0..$#{ $pdb->{'records'}) {
    next if $_ == 0;
    my $rec = $pdb->{'records'}->[$_];
    my $acct = $pdb->Decrypt($rec[, $password]);
    # do something with $acct
}

Password

$pdb->Password([$password[, $new_password]]);

Either sets the password to be used to crypt, or if you pass $new_password, changes the password on the database.

If you have created a new $pdb, and you didn't set a password when you called new(), you only need to pass one password and it will set that as the password.

If nothing is passed, it forgets the password that it was remembering.

DEPENDENCIES

Palm::StdAppInfo

Digest::MD5

Crypt::DES

Readonly

THANKS

I would like to thank the helpful Perlmonk shigetsu who gave me some great advice and helped me get my first module posted. http://perlmonks.org/?node_id=596998

I would also like to thank Johan Vromans <jvromans@squirrel.nl> -- http://www.squirrel.nl/people/jvromans. He had his own Palm::KeyRing module that he posted a couple of days before mine was ready and he was kind enough to let me have the namespace as well as giving me some very helpful hints about doing a few things that I was unsure of. He is really great.

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-palm-keyring at rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Andrew Fresh <andrew@mad-techies.org>

LICENSE AND COPYRIGHT

Copyright 2004, 2005, 2006, 2007 Andrew Fresh, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Palm::PDB(3)

Palm::StdAppInfo(3)

The Keyring for Palm OS website: http://gnukeyring.sourceforge.net/

Johan Vromans also has a wxkeyring app that now uses this module, available from his website at http://www.vromans.org/johan/software/