NAME

Config::OpenSSH::Authkey::Entry - authorized_keys file entry handler

SYNOPSIS

This module is used by Config::OpenSSH::Authkey, though can be used standalone:

my $entry = Config::OpenSSH::Authkey::Entry->new();

# assuming $fh is opened to an authorized_keys file...
eval {
  $entry->parse($fh->getline);
  if ($entry->protocol == 1) {
    warn "warning: deprecated SSHv1 key detected ...\n";
  }
};
...

DESCRIPTION

This module parses lines from OpenSSH authorized_keys files, and offers various methods to interact with the data. The AUTHORIZED_KEYS FILE FORMAT section of sshd(8) details the format of these lines. I use the term entry to mean a line from an authorized_keys file.

Errors are thrown via die or croak, notably when parsing an entry via the new or key methods. Some of the options handling is provided by Config::OpenSSH::Authkey::Entry::Options.

CLASS METHODS

new optional data to parse

Constructor. Optionally accepts an authorized_keys file entry to parse.

split_options option string

Accepts a string of comma separated options, and parses these into a list of hash references. In scalar context, returns a reference to the list. In list context, returns a list.

INSTANCE METHODS

parse data to parse

Utility method in event data to parse was not passed to new.

key optional key to parse

Returns the public key material. If passed a string, will attempt to parse that string as a new key (and options, and comment, if those are present).

Throws an exception if no key material present in the instance.

keytype

Returns the type of the key, either rsa1 for a SSHv1 key, or rsa or dsa for the two different SSHv2 key types. This is the same format as the ssh-keygen(1) -t option accepts.

protocol

Returns the major SSH protocol version of the key, 1 or 2.

Note that SSHv1 has been replaced by SSHv2 for over a decade as of 2010. I strongly recommend that SSHv1 be disabled.

comment optional new comment

Returns the comment, if any, of the parsed entry. ssh-keygen(1) defaults to user@host for this field. If a string is passed, updates the comment to that string. If no comment is set, returns the empty string.

Note that OpenSSH 5.5 may truncate key comments to 72 characters if keys are converted to the RFC 4716 format via ssh-keygen -e ....

unset_comment

Deletes the comment.

options optional new option string

Returns any options set in the entry as a comma separated value string, or, if passed a string, sets that string as the new option set.

# get
my $option_str = $entry->options();

# set
$entry->options('from="127.0.0.1",no-agent-forwarding');

Returns the empty string if no options have been set.

unset_options

Deletes all the options.

get_option option name

Returns the value (or values) for a named option. OpenSSH does allow duplicate entries for options, though in most cases this method will only return a single value. Options are boolean or string value; boolean options return the name of the method, while string options return the string value. Assuming the options have been set as shown above:

# returns 'no-agent-forwarding'
$entry->get_option('no-agent-forwarding');

# returns '127.0.0.1'
$entry->get_option('from');

In scalar context, only the first option is returned (or the empty string). In list context, a list of one (or rarely more) values will be returned (or the empty list).

set_option option name, optional value

Enables an option, or with an additional argument, sets the string value for that option.

# boolean
$entry->set_option('no-agent-forwarding');

# string value
$entry->set_option(from => '127.0.0.1');

If multiple options with the same name are present in the options list, only the first option found will be updated, and all subsequent entries removed from the options list.

unset_option option name

Deletes all occurrences of the named option.

as_string

Returns the entry formatted as an OpenSSH authorized_keys line. Throws an exception if no key material present in the instance.

duplicate_of optional value

If supplied with an argument, stores this data in the object. Always returns the value of this data, which is 0 by default. Used by Config::OpenSSH::Authkey to track whether (and of what) a key is a duplicate of.

unset_duplicate

Clears the duplicate status of the instance, if any.

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), ssh-keygen(1), Config::OpenSSH::Authkey

AUTHOR

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

COPYRIGHT

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

This module is free software; you can redistribute it and/or modify it under the Artistic License (2.0).