1Net::SSH::Perl::Agent(3U)ser Contributed Perl DocumentatiNoent::SSH::Perl::Agent(3)
2
6 Net::SSH::Perl::Agent - Client for agent authentication
7
9 use Net::SSH::Perl::Agent;
10 my $agent = Net::SSH::Perl::Agent->new(2); ## SSH-2 protocol
11 my $iter = $agent->identity_iterator;
12 while (my($key, $comment) = $iter->()) {
13 ## Do something with $key.
14 }
15
17 Net::SSH::Perl::Agent provides a client for agent-based publickey
18 authentication. The idea behind agent authentication is that an auth
19 daemon is started as the parent of all of your other processes (eg. as
20 the parent of your shell process); all other processes thus inherit the
21 connection to the daemon.
22 After loading your public keys into the agent using ssh-add, the agent
24 listens on a Unix domain socket for requests for identities. When
25 requested it sends back the public portions of the keys, which the SSH
26 client (ie. Net::SSH::Perl, in this case) can send to the sshd, to
27 determine if the keys will be accepted on the basis of authorization.
28 If so, the client requests that the agent use the key to decrypt a
29 random challenge (SSH-1) or sign a piece of data (SSH-2).
30 Net::SSH::Perl::Agent implements the client portion of the
32 authentication agent; this is the piece that interfaces with
33 Net::SSH::Perl's authentication mechanism to contact the agent daemon
34 and ask for identities, etc. If you use publickey authentication (RSA
35 authentication in SSH-1, PublicKey authentication in SSH-2), an attempt
36 will automatically be made to contact the authentication agent. If the
37 attempt succeeds, Net::SSH::Perl will try to use the identities
38 returned from the agent, in addition to any identity files on disk.
39
41 Net::SSH::Perl::Agent->new($version)
42 Constructs a new Agent object and returns that object.
43 $version should be either 1 or 2 and is a mandatory argument; it
45 specifies the protocol version that the agent client should use when
46 talking to the agent daemon.
47 $agent->identity_iterator
49 This is probably the easiest way to get at the identities provided by
50 the agent. identity_iterator returns an iterator function that, when
51 invoked, will returned the next identity in the list from the agent.
52 For example:
53 my $iter = $agent->identity_iterator;
55 while (my($key, $comment) = $iter->()) {
56 ## Do something with $key.
57 }
58 If called in scalar context, the iterator function will return the next
60 key (a subclass of Net::SSH::Perl::Key). If called in list context (as
61 above), both the key and the comment are returned.
62 $agent->first_identity
64 Returns the first identity in the list provided by the auth agent.
65 If called in scalar context, the iterator function will return the next
67 key (a subclass of Net::SSH::Perl::Key). If called in list context,
68 both the key and the comment are returned.
69 $agent->next_identity
71 Returns the next identity in the list provided by the auth agent. You
72 must call this after first calling the first_identity method. For
73 example:
74 my($key, $comment) = $agent->first_identity;
76 ## Do something.
77 while (($key, $comment) = $agent->next_identity) {
79 ## Do something.
80 }
81 If called in scalar context, the iterator function will return the next
83 key (a subclass of Net::SSH::Perl::Key). If called in list context,
84 both the key and the comment are returned.
85 $agent->sign($key, $data)
87 Asks the agent $agent to sign the data $data using the private portion
88 of $key. The key and the data are sent to the agent, which returns the
89 signature; the signature is then sent to the sshd for verification.
90 This method is only applicable in SSH-2.
92 $agent->decrypt($key, $data, $session_id)
94 Asks the agent to which $agent holds an open connection to decrypt the
95 data $data using the private portion of $key. $data should be a big
96 integer (Math::GMP object), and is generally a challenge to a request
97 for RSA authentication. $session_id is the SSH session ID:
98 $ssh->session_id
100 where $ssh is a Net::SSH::Perl::SSH1 object.
102 This method is only applicable in SSH-1.
104
106 Please see the Net::SSH::Perl manpage for author, copyright, and
107 license information.
108perl v5.36.0 2023-01-20 Net::SSH::Perl::Agent(3)