plucky (3) Net::SSH::AuthorizedKey.3pm.gz

NAME

       Net::SSH::AuthorizedKey - Virtual Base Class for SSH Public Keys

SYNOPSIS

           use Net::SSH::AuthorizedKey;

             # Either parse a string (without leading whitespace or comments):
           my $key = Net::SSH::AuthorizedKey->parse( $line );

           if(defined $key) {
                 # ssh-1 or ssh-2
               print "Key parsed, type is ", $key->type(), "\n";
           } else {
               die "Cannot parse key '$line'";
           }

             # ... or create an object yourself:
           my $pubkey = Net::SSH::AuthorizedKey->new(
               options  => { from                  => 'foo@bar.com',
                             "no-agent-forwarding" => 1 },
               key      => "123....890",
               keylen   => 1024,
               exponent => 35,
               type     => "ssh-1",
           );

DESCRIPTION

       Net::SSH::AuthorizedKey is a virtual base class for ssh public keys.  Real implementations of it are
       Net::SSH::AuthorizedKey::SSH1 and Net::SSH::AuthorizedKey::SSH2.

       The only way to using it directly is by calling its parse() method, and passing it an authorized_keys
       string (aka a line from an authorized_keys file). If it recognizes either a ssh-1 or a ssh-2 type key, it
       will return a Net::SSH::AuthorizedKey::SSH1 or a Net::SSH::AuthorizedKey::SSH2 object, both of which
       support the accessor methods defined in the FIELDS section below.

       The as_string() method will cobble the (perhaps modified) fields together and return them as a string
       suitable as a line for an authorized_keys file.

   METHODS
       "parse( $line )"
           Reads in a single text line containing a ssh-1 or ssh-2 key.  Returns a Net::SSH::AuthorizedKey::SSH1
           or a Net::SSH::AuthorizedKey::SSH2 object, or "undef" in case of an error.

       "fingerprint()"
           Returns a MD5 hex hash of the parsed key. The hash is unique for functionally identical keys. Fields
           not contributing to the key's functional uniqueness are ignored.

       "error()"
           Returns the last parsing error encountered as a text string.

       "as_string( )"
           Return the object as a string suitable as a autorized_keys line.

   FIELDS
       All of the following fields are available via accessors:

       "type"
           Type of ssh key, usually "ssh-1" or "ssh-2".

       "key"
           Public key, either a long number (ssh-1) or a line of alphanumeric characters (ssh-2).

       "keylen"
           Length of the key in bit (e.g. 1024).

       "exponent"
           Two-digit number in front of the key in ssh-1 authorized_keys lines.

       "options"
           Returns a reference to a hash with options key/value pairs, listed in front of the key.

   IMPLEMENTATION REFERENCE
       The key parsers implemented in this distribution are implemented similarily as the authorized_keys file
       parser in the openssh source distribution.

       Openssh contains the authorized_keys parser in its auth2_pubkey.c file. The user_key_allowed2() function
       opens the file and reads it line by line, ignoring leading whitespace, empty and comment lines.

       After that, if a line doesn't contain a plain key, the parser skips ahead until the first whitespace
       (zooming through quoted areas "..." and interpreting '\"' as an escaped quote), then skips this
       whitespace and tries to read a key one more time.

       Regarding options, the Perl parser isn't as elaborate with semantic peculiarities as openssh's
       auth_parse_options(), but this might be added in the future.

NOTES FOR SUBCLASS DEVELOPERS

       If you're just using Net::SSH::AuthorizedKey to parse keys, the following section doesn't concern you.
       It's only relevant if you add new subclasses to this package, on top of what's already provided.

       Net::SSH::AuthorizedKey is a (semi-)virtual base class that implements options handling for its SSH1 and
       SSH2 subclasses.

       SSH key lines can contain options that carry values (like command="ls") and binary options that are
       either set or unset (like "no_agent_forwarding"). To distinguish the two, and to provide a set of allowed
       option names, the subclass has to implement the method option_type(), which takes an option name, and
       returns

       •   undef if the option is not supported

       •   "s" if the option is a "string" option that carries a value

       •   1 if the option is a binary option

       The subclasses Net::SSH::AuthorizedKey::SSH1 and Net::SSH::AuthorizedKey::SSH2 are doing this already.

LEGALESE

       Copyright 2005-2009 by Mike Schilli, all rights reserved.  This program is free software, you can
       redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

       2005, Mike Schilli <m@perlmeister.com>