Benjamin Trott > Crypt-Keys-0.06 > Crypt::Keys

Download:
Crypt-Keys-0.06.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.06   Source  

NAME ^

Crypt::Keys - On-disk management of public and private keyfiles

SYNOPSIS ^

    use Crypt::Keys;
    my $key_data = Crypt::Keys->read( Filename => $key_file );

    Crypt::Keys->write(
                    Filename   => $key_file,
                    Passphrase => 'foo',
                    Data       => $key_data,
              );

    my $key_type = Crypt::Keys->detect( Content => $key_content );

DESCRIPTION ^

Crypt::Keys is an on-disk key management system for public and private keyfiles. The goal of the module is to be able to read and write crypto keys in any encoding (eg. PEM, SSH, etc.). It can be used as a front-end for key management, but it does not contain implementations of any of the assymetric cryptography algorithms represented by the keys that it manages. In other words, you can use it to read and write your DSA/RSA/etc. keys, but it does not generate new keys or encrypt/sign data.

Crypt::Keys is useful for authors of the modules that implement those algorithms, however, because it provides all of the backend storage mechanisms to get the keys in and out of the filesystem. There are many key encodings for common key algorithms; Crypt::Keys ensures that the authors of the implementation do not have to worry about the myriad formats but only about the algorithms.

USAGE ^

$key_data = Crypt::Keys->read( %args )

Reads a key from disk. If you specify a format/encoding for the key (see below), Crypt::Keys will try to read the file using that encoding. Otherwise Crypt::Keys will detect the type of the file and use the appropriate encoding plugin automatically.

%args can include:

Format

Specifies the format of the keyfile, ie. the class to be used when decoding the keyfile. Possible formats are: Private::DSA::PEM, Public::RSA::SSH1, etc.

This argument is optional; if not specified read will look at the beginning of the file to determine its format, then will automatically use the correct class to decode that format.

Filename

The path to the key file. This argument is required.

Passphrase

If the keyfile is encrypted, a passphrase will be needed in order to decrypt it. Specify that passphrase here.

This argument is optional; if the keyfile is encrypted, and you do not provide a passphrase, read will return undef, and errstr will be set accordingly (see below).

Returns a reference to a hash containing these keys:

Data

The key data. The contents of Data vary depending on the type of key.

Format

The name of the class used to decode the keyfile.

If an error occurs while reading/decoding the keyfile, read returns undef, and you should call errstr to determine the source of the error (see ERROR HANDLING, below).

Crypt::Keys->write( %args )

Encodes and writes key data to a keyfile, encrypting it if requested.

%args can include:

write returns true on success, and undef on failure; in the latter case you should use errstr to determine what went wrong (see ERROR HANDLING, below).

Crypt::Keys->detect( %args )

Detects the format in which a key is encoded (eg. PEM), and the type of key that is encoded (eg. DSA).

%args can contain:

Returns a hash reference containing these keys:

On failure detect returns undef.

ERROR HANDLING ^

If an error occurs while reading/writing/detecting a keyfile, the method you called will return undef. You should then call the method errstr to determine the error:

    Crypt::Keys->errstr

For example, if you try to read an encrypted keyfile and you do not give a passphrase:

    my $key = Crypt::Keys->read( Filename => $key_file )
        or die "Could not read key file: ", Crypt::Keys->errstr;

AUTHOR & COPYRIGHT ^

Benjamin Trott, ben@rhumba.pair.com

Except where otherwise noted, Crypt::Keys is Copyright 2001 Benjamin Trott. All rights reserved. Crypt::Keys is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: