Net::SS...l::Agent(3)

💖 Net::SSH::Perl::Agent 💖

okay bestie, so this page is Net::SSH::Perl::Agent(3), and it lives in the User Contributed Perl Documentation section (that's the "perl" manual, not the system one, iykyk). it's the client side of agent authentication and honestly? it's giving "I do one thing and I do it flawlessly". 🫶

---

✨ NAME ✨

Net::SSH::Perl::Agent — client for agent authentication 🎀

---

🌸 SYNOPSIS 🌸

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.
}

---

🦋 DESCRIPTION 🦋

Net::SSH::Perl::Agent provides a client for agent-based publickey authentication. so like, the whole idea behind agent authentication is that an auth daemon gets started as the parent of all your other processes (eg. as the parent of your shell process), and then literally all of those other processes inherit the connection to the daemon. family plan energy. 🧚

once you've loaded your public keys into the agent using ssh-add, the agent just... sits there listening on a Unix domain socket for requests for identities. when somebody asks, it sends back the public portions of the keys — and then the SSH client (which is Net::SSH::Perl, in this case, hi 👋) can send those to the sshd to figure out whether the keys will be accepted on the basis of authorization. and if they will? the client asks the agent to use the key to decrypt a random challenge (SSH-1) or sign a piece of data (SSH-2). no biggie. 💅

Net::SSH::Perl::Agent implements the client portion of the authentication agent — this is the piece that interfaces with Net::SSH::Perl's authentication mechanism to contact the agent daemon and ask for identities, etc. and here's the slay part: if you use publickey authentication (RSA authentication in SSH-1, PublicKey authentication in SSH-2), an attempt will automatically be made to contact the authentication agent. if that attempt succeeds, Net::SSH::Perl will try to use the identities returned from the agent, in addition to any identity files on disk. best of both worlds fr fr. ⭐

---

💅 USAGE 💅

🎀 Net::SSH::Perl::Agent->new($version)

Constructs a new Agent object and returns that object. brand new, fresh out the box, iconic. ✨

$version should be either 1 or 2 and is a mandatory argument; it specifies the protocol version that the agent client should use when talking to the agent daemon. so like, you gotta pass it, no skipping, bestie. 🙈

🎀 $agent->identity_iterator

This is probably the easiest way to get at the identities provided by the agent. identity_iterator returns an iterator function that, when invoked, will returned the next identity in the list from the agent. (yes the original says "will returned", we love a typo that ate and left no crumbs, keeping it. 😭) for example:

my $iter = $agent->identity_iterator;
while (my($key, $comment) = $iter->()) {
     ## Do something with $key.
}

If called in scalar context, the iterator function will return the next key (a subclass of Net::SSH::Perl::Key). If called in list context (as above), both the key and the comment are returned. two moods, one iterator. 🦋

🎀 $agent->first_identity

Returns the first identity in the list provided by the auth agent. first come, first served, main character energy. 👑

If called in scalar context, the iterator function will return the next key (a subclass of Net::SSH::Perl::Key). If called in list context, both the key and the comment are returned.

🎀 $agent->next_identity

Returns the next identity in the list provided by the auth agent. You must call this after first calling the first_identity method. order matters, bestie, don't come in mid-conversation. for example:

my($key, $comment) = $agent->first_identity;
## Do something.

while (($key, $comment) = $agent->next_identity) {
    ## Do something.
}

If called in scalar context, the iterator function will return the next key (a subclass of Net::SSH::Perl::Key). If called in list context, both the key and the comment are returned.

🎀 $agent->sign($key, $data)

Asks the agent $agent to sign the data $data using the private portion of $key. the key and the data get sent to the agent, which returns the signature; that signature is then sent to the sshd for verification. like passing a note in class but make it cryptography. 💌

⚠️ This method is only applicable in SSH-2.

🎀 $agent->decrypt($key, $data, $session_id)

Asks the agent to which $agent holds an open connection to decrypt the data $data using the private portion of $key. $data should be a big integer (Math::GMP object), and is generally a challenge to a request for RSA authentication. $session_id is the SSH session ID:

$ssh->session_id

where $ssh is a Net::SSH::Perl::SSH1 object.

⚠️ This method is only applicable in SSH-1.

---

👑 AUTHOR & COPYRIGHTS 👑

Please see the Net::SSH::Perl manpage for author, copyright, and license information. 🫶

---

and that's the whole page, periodt. 💖 this was perl v5.42.0, dated 2026-01-17, from the Net::SS...l::Agent(3) page (yes the header really is truncated like that, the way it ate the middle of the name and left us with Net::SS...l::Agent — iconic honestly 💀). go forth and authenticate, bestie 🌈🌸