NAME

Config::OpenSSH::Authkey - interface to OpenSSH authorized_keys data

SYNOPSIS

use Config::OpenSSH::Authkey ();
my $ak = Config::OpenSSH::Authkey->new;

$ak->file( 'authorized_keys' );

while (my $entry = $ak->iterate) {
  ...

DESCRIPTION

This module provides an interface to the entries in an OpenSSH authorzied_keys file. Both SSH1 and SSH2 protocol public keys are supported. Config::OpenSSH::Authkey::Entry provides an interface to individual entries (lines) in the authorzied_keys file.

This is a pure Perl interface, so may differ from how OpenSSH parses the authorzied_keys data. The sshd(8) manual and OpenSSH 5.2 source code were consulted in the creation of this module.

Consult the "OPTIONS" section for means to customize how authorized_keys data is handled.

CLASS METHODS

new

Constructor method. Accepts a hash reference containing "OPTIONS" that alter how the instance behaves.

my $ak = Config::OpenSSH::Authkey->new({
  tag_dups => 1,
  nostore_nonkey_data => 1,
});

INSTANCE METHODS

fh

Accepts a filehandle, stores this handle in the instance, for future use by iterate or consume.

file

Accepts a filename, attempts to open this file, and store the resulting filehandle in the instance for future use by iterate or consume. Throws an exception if the file cannot be opened.

iterate

Returns the next entry of the filehandle (or, lacking a filehandle in the instance, throws an error. Call fh or file first). Returned data will either be "Config::OpenSSH::Authkey::MetaEntry" (comments, blank lines) or Config::OpenSSH::Authkey::Entry (public key) objects.

For example, to exclude SSHv1 authorized_keys data, while retaining all other data in the file:

while (my $entry = $ak->iterate) {
  if ($entry->can("prototol")) {
    next if $entry->protocol == 1;
  }
  
  print $output_fh $entry->as_string, "\n";
}

consume

This method consumes all data in the fh or file opened in the instance, and saves it to the module key store. The auto_store option is temporarily enabled to allow this. Set the nostore_nonkey_data option to avoid saving non-key material to the key store. Stored keys can be accessed by calling the get_stored_keys method.

parse data

Attempts to parse input data, either as a comment or blank line with "Config::OpenSSH::Authkey::MetaEntry", or as a public key via Config::OpenSSH::Authkey::Entry. Will throw an exception if the public key cannot be parsed.

Returns either an "Config::OpenSSH::Authkey::MetaEntry" or Config::OpenSSH::Authkey::Entry object.

get_stored_keys

Returns an array reference of any public keys stored in the instance. keys will only be populated if the auto_store option is enabled.

Keys will be either "Config::OpenSSH::Authkey::MetaEntry" (comments, blank lines) or Config::OpenSSH::Authkey::Entry (public key) objects. To avoid storing comments and blank lines, enable the nostore_nonkey_data option before calling iterate or consume.

reset_store

Removes all authorized_keys entries stored by the instance. Also removes all the seen keys from the duplicate check stash.

reset_dups

Removes all the seen keys from the duplicate check stash. This method is likely useless if a custom code reference has been installed to handle the duplicate key checks.

OPTIONS

The following options can be specified as arguments in a hash reference to the new method, or by calling the option name as a method. All options default to false. Pass a true value to enable.

auto_store boolean

Whether to store parsed entries in the instance. The default is to not store any entries.

tag_dups boolean

Whether to check for duplicate authorized_keys keys. The default is to not check for duplicate keys. If this option is enabled, the duplicate_of method of Config::OpenSSH::Authkey::Entry should be used to check whether a particular entry is a duplicate.

nostore_nonkey_data boolean

Whether to store non-key data (comments, blank lines) in the auto-store data structure. The default is to store these lines. The iterate method always returns these lines, regardless of this setting.

Config::OpenSSH::Authkey::MetaEntry

Utility class that stores blank lines or comments. The object supports an as_string method that will return the line. Disable the storage of this data in the key store by enabling the nostore_nonkey_data option.

Use the ref function or the can method to distinguish these entries from Config::OpenSSH::Authkey::Entry objects.

BUGS

No known bugs. Newer versions of this module may be available from CPAN.

If the bug is in the latest version, send a report to the author. Patches that fix problems or add new features are welcome.

SEE ALSO

sshd(8), Config::OpenSSH::Authkey::Entry

AUTHOR

Jeremy Mates, <jmates@sial.org>

COPYRIGHT

Copyright 2009-2010 by Jeremy Mates.

This program is free software; you can redistribute it and/or modify it under the Artistic license.