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.

• The AUTHORIZED_KEYS FILE FORMAT section of sshd(8) details the format of authorzied_keys entries.

• Consult the "OPTIONS" section for means to customize how this module operates.

Caveats

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. authorzied_keys file options, in particular, are not checked for validity: this module will parse the valid no-pty option along with the invalid asdf. This makes the module future proof against options being added to OpenSSH, at the cost of passing potentially garbage data around.

Ruminations on Managing authorized_keys Files

OpenSSH authorized_keys files could be managed by a user, or by a centralized control system, or shared between different groups using the same systems. Site legal or security policy may dictate how authorized_keys must be handled: how frequently the keys must be rotated, whether port forwarding and so forth are permitted, whether to restrict keys to only run specific commands.

• Centralized control is the easiest, as the raw keys will be stored under configuration management, or in a database, or directory service, and code will update the various supported authorized_keys files, removing (and possibly warning about) any unknown key entries. The code should include a comment at the top of every managed authorized_keys file stating that the file is managed, and linking to instructions on how to properly add or change keys.

• Shared systems require caution; foreign keys must not be wiped out. The easiest method is to include the target authorized_keys file as one of the sources for valid key material. A comment should be added into to the authorized_keys file, noting what keys are managed by the software.

Rotating authorized_keys data is difficult, as the entries contain no date related metadata like X.509 certificates do. Solutions would be to schedule a yearly calendar event during which all the keys are rotated, or maintain the keys in a database that includes a creation date field on the record.

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 L"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.

https://github.com/thrig/Config-OpenSSH-Authkey

SEE ALSO

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

AUTHOR

thrig - Jeremy Mates (cpan:JMATES) <jmates at cpan.org>

COPYRIGHT

Copyright 2009-2010,2012,2015,2019 by Jeremy Mates

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause

cpanm Config::OpenSSH::Authkey

perl -MCPAN -e shell
install Config::OpenSSH::Authkey