/ 
Crypt-Keys-0.06
River stage zero No dependents
/ Crypt::Keys

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:

  • Filename

    The path to the file where the encoded key should be written.

    This argument is required.

  • Data

    The key data to be written. This should be a reference to a hash containing the keys described above in the return value from read. In fact, the argument to Data should look exactly like the return value from read.

    This argument is required.

  • Passphrase

    If you wish to encrypt the contents of the key before storing them on disk, you can do so by specifying a passphrase.

    This argument is optional.

  • Format

    Specifies the format in which the key should be encoded.

    This argument is optional if the key was read in from disk using read; in that case, if Format is unspecified the key will be written to disk in the same format in which it was read.

  • Comment

    A comment for the key.

    This argument is optional.

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:

  • Content

    A scalar string of the encoded key contents, or at least part of the key contents; if the string contains only part of the contents, the piece must be taken from the beginning of the encoded key.

    This argument is optional; if not provided, Filename must be provided.

  • Filename

    The path to a file on disk containing the encoded key contents.

    This argument is optional; if not provided, Content must be provided.

Returns a hash reference containing these keys:

  • Format

    The format of the key, in the form of the name of the class that provides the encoding/decoding for that format. For example, Private::DSA::PEM for a PEM-encoded private DSA key. This is the same Format that can be passed to read and write.

  • Description

    A textual description of the keyfile.

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.