.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::SSH::Perl::Agent 3"
.TH Net::SSH::Perl::Agent 3 "2009-01-25" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::SSH::Perl::Agent \- Client for agent authentication
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    use Net::SSH::Perl::Agent;
\&    my $agent = Net::SSH::Perl::Agent->new(2);  ## SSH-2 protocol
\&    my $iter = $agent->identity_iterator;
\&    while (my($key, $comment) = $iter->()) {
\&        ## Do something with $key.
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fINet::SSH::Perl::Agent\fR provides a client for agent-based
publickey authentication. The idea behind agent authentication
is that an auth daemon is started as the parent of all of your
other processes (eg. as the parent of your shell process); all
other processes thus inherit the connection to the daemon.
.PP
After loading your public keys into the agent using \fIssh-add\fR, the
agent listens on a Unix domain socket for requests for identities.
When requested it sends back the public portions of the keys,
which the \s-1SSH\s0 client (ie. \fINet::SSH::Perl\fR, in this case) can
send to the sshd, to determine if the keys will be accepted on
the basis of authorization. If so, the client requests that the
agent use the key to decrypt a random challenge (\s-1SSH\-1\s0) or sign
a piece of data (\s-1SSH\-2\s0).
.PP
\&\fINet::SSH::Perl::Agent\fR implements the client portion of the
authentication agent; this is the piece that interfaces with
\&\fINet::SSH::Perl\fR's authentication mechanism to contact the
agent daemon and ask for identities, etc. If you use publickey
authentication (\fI\s-1RSA\s0\fR authentication in \s-1SSH\-1\s0, \fIPublicKey\fR
authentication in \s-1SSH\-2\s0), an attempt will automatically be
made to contact the authentication agent. If the attempt
succeeds, \fINet::SSH::Perl\fR will try to use the identities
returned from the agent, in addition to any identity files on
disk.
.SH "USAGE"
.IX Header "USAGE"
.Sh "Net::SSH::Perl::Agent\->new($version)"
.IX Subsection "Net::SSH::Perl::Agent->new($version)"
Constructs a new \fIAgent\fR object and returns that object.
.PP
\&\fI$version\fR should be either \fI1\fR or \fI2\fR and is a mandatory
argument; it specifies the protocol version that the agent
client should use when talking to the agent daemon.
.Sh "$agent\->identity_iterator"
.IX Subsection "$agent->identity_iterator"
This is probably the easiest way to get at the identities
provided by the agent. \fIidentity_iterator\fR returns an iterator
function that, when invoked, will returned the next identity
in the list from the agent. For example:
.PP
.Vb 4
\&    my $iter = $agent->identity_iterator;
\&    while (my($key, $comment) = $iter->()) {
\&         ## Do something with $key.
\&    }
.Ve
.PP
If called in scalar context, the iterator function will return
the next key (a subclass of \fINet::SSH::Perl::Key\fR). If called
in list context (as above), both the key and the comment are
returned.
.Sh "$agent\->first_identity"
.IX Subsection "$agent->first_identity"
Returns the first identity in the list provided by the auth
agent.
.PP
If called in scalar context, the iterator function will return
the next key (a subclass of \fINet::SSH::Perl::Key\fR). If called
in list context, both the key and the comment are returned.
.Sh "$agent\->next_identity"
.IX Subsection "$agent->next_identity"
Returns the next identity in the list provided by the auth
agent. You \fImust\fR call this \fIafter\fR first calling the
\&\fIfirst_identity\fR method. For example:
.PP
.Vb 2
\&    my($key, $comment) = $agent->first_identity;
\&    ## Do something.
.Ve
.PP
.Vb 3
\&    while (($key, $comment) = $agent->next_identity) {
\&        ## Do something.
\&    }
.Ve
.PP
If called in scalar context, the iterator function will return
the next key (a subclass of \fINet::SSH::Perl::Key\fR). If called
in list context, both the key and the comment are returned.
.ie n .Sh "$agent\->sign($key, $data)"
.el .Sh "$agent\->sign($key, \f(CW$data\fP)"
.IX Subsection "$agent->sign($key, $data)"
Asks the agent \fI$agent\fR to sign the data \fI$data\fR using the
private portion of \fI$key\fR. The key and the data are sent to
the agent, which returns the signature; the signature is then
sent to the sshd for verification.
.PP
This method is only applicable in \s-1SSH\-2\s0.
.ie n .Sh "$agent\->decrypt($key, $data\fP, \f(CW$session_id)"
.el .Sh "$agent\->decrypt($key, \f(CW$data\fP, \f(CW$session_id\fP)"
.IX Subsection "$agent->decrypt($key, $data, $session_id)"
Asks the agent to which \fI$agent\fR holds an open connection to
decrypt the data \fI$data\fR using the private portion of \fI$key\fR.
\&\fI$data\fR should be a big integer (\fIMath::GMP\fR object), and
is generally a challenge to a request for \s-1RSA\s0 authentication.
\&\fI$session_id\fR is the \s-1SSH\s0 session \s-1ID:\s0
.PP
.Vb 1
\&    $ssh->session_id
.Ve
.PP
where \fI$ssh\fR is a \fINet::SSH::Perl::SSH1\fR object.
.PP
This method is only applicable in \s-1SSH\-1\s0.
.SH "AUTHOR & COPYRIGHTS"
.IX Header "AUTHOR & COPYRIGHTS"
Please see the Net::SSH::Perl manpage for author, copyright,
and license information.