NAME

Palm::KeyRing - Interface to GNU KeyRing databases

SYNOPSIS

use Palm::KeyRing;

# Open the database.
my $db = Palm::KeyRing->new("Keys-Gtkr.pdb");

# Fetch a decryptor (verifies the password).
my $decryptor = $db->getDecryptor("Secret PassPhrase");
die("Incorrect password") unless $decryptor;

# Fetch record by number (first = 1).
my $rec = $db->getRecord(1);
# Or fetch record by name.
# Note that there can be several records with the same name.
$rec = $db->getRecordsByName("BankAccount")->[0];
# $rec->{name} the name.
# $rec->{category} the category index.
# $rec->{data} contains the encrypteddata.

# Decrypt record.
my ($name, $category, $account, $password, $note, $lastmod) =
  $decryptor->decrypt($rec);

DESCRIPTION

Palm::KeyRing provides a (currently read-only) interface to the keyring files as used by the GNU KeyRing tool on Palm handhelds.

Records in the keyring file have 5 fields: name, account, password, note, and lastmod. All fields except name are encrypted.

The lastmod field, if present, will be returned by the decryptor as an array reference [ year, month, day ], compatible with the first three elements returned by localtime.

METHODS

The following are methods of Palm::KeyRing.

new

Constructor. Takes one argument: the name of the keyring file.

getRecords

Returns the number of records read. Note that the contents will not be decrypted.

getNames

Returns a list (in scalar context: array reference) of all names used in the keyring file.

getRecord

Takes one integer argument, a record number, and returns the record. This is a hash ref with at least keys "name, "data" and "category". Note that "category" is the category index.

If no such record exists, returns undef.

getRecordsByName

Takes two arguments, a record name, and a category mask. Returns an list (or arry ref in scalar context) of the corresponding records. See getRecord above for the return values.

If no such record exists, returns an empty list (or reference).

The category mask is a bit pattern, where bit 0 = category 0 (Unfiled), bit 1 = category 1, and so on. When the category mask is omitted, returns the results for all categories.

getCategory

Takes one argument, a category index. Returns the category as a string.

getCategories

In list context, returns a list of categories. In scalar context returns an array reference.

getDecryptor

Takes one argument, the keyring password. If the password is correct, it returns a decryptor for this keyring. Otherwise, it returns undef.

The decryptor provides one method: decrypt. This method takes one argument, the record (as a hash ref). It returns a list (in scalar context: array reference) of the record name, category_name, account, password, note, and lastmod; all decrypted.

REQUIREMENTS

PDA::Pilot

Crypt::DES

DEMO PROGRAM

Palm::KeyRing comes with a nice GUI based demo program wxkeyring. This program requires WxPerl 0.15 or later.

BUGS AND LIMITATIONS

Installs Palm::Raw as the default handler for Palm::PDB. This could have side effects if the rest of the program also uses Palm::PDB.

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.

SEE ALSO

Palm::PDB

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

AUTHOR

Johan Vromans <jv@cpan.org>.

LICENCE AND COPYRIGHT

Copyright 2007 Johan Vromans, All Rights Reserved.

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