]>
Commit | Line | Data |
---|---|---|
9108f8d9 | 1 | SSH-AGENT(1) OpenBSD Reference Manual SSH-AGENT(1) |
2 | ||
3 | NAME | |
4 | ssh-agent - authentication agent | |
5 | ||
6 | SYNOPSIS | |
7 | ssh-agent [-a bind_address] [-c | -s] [-t life] [-d] [command [args ...]] | |
8 | ssh-agent [-c | -s] -k | |
9 | ||
10 | DESCRIPTION | |
11 | ssh-agent is a program to hold private keys used for public key authenti- | |
12 | cation (RSA, DSA). The idea is that ssh-agent is started in the begin- | |
13 | ning of an X-session or a login session, and all other windows or pro- | |
14 | grams are started as clients to the ssh-agent program. Through use of | |
15 | environment variables the agent can be located and automatically used for | |
16 | authentication when logging in to other machines using ssh(1). | |
17 | ||
18 | The options are as follows: | |
19 | ||
20 | -a bind_address | |
21 | Bind the agent to the unix-domain socket bind_address. The de- | |
22 | fault is /tmp/ssh-XXXXXXXXXX/agent.<ppid>. | |
23 | ||
24 | -c Generate C-shell commands on stdout. This is the default if | |
25 | SHELL looks like it's a csh style of shell. | |
26 | ||
27 | -s Generate Bourne shell commands on stdout. This is the default if | |
28 | SHELL does not look like it's a csh style of shell. | |
29 | ||
30 | -k Kill the current agent (given by the SSH_AGENT_PID environment | |
31 | variable). | |
32 | ||
33 | -t life | |
34 | Set a default value for the maximum lifetime of identities added | |
35 | to the agent. The lifetime may be specified in seconds or in a | |
36 | time format specified in sshd_config(5). A lifetime specified | |
37 | for an identity with ssh-add(1) overrides this value. Without | |
38 | this option the default maximum lifetime is forever. | |
39 | ||
40 | -d Debug mode. When this option is specified ssh-agent will not | |
41 | fork. | |
42 | ||
43 | If a commandline is given, this is executed as a subprocess of the agent. | |
44 | When the command dies, so does the agent. | |
45 | ||
46 | The agent initially does not have any private keys. Keys are added using | |
47 | ssh-add(1). When executed without arguments, ssh-add(1) adds the files | |
48 | ~/.ssh/id_rsa, ~/.ssh/id_dsa and ~/.ssh/identity. If the identity has a | |
49 | passphrase, ssh-add(1) asks for the passphrase (using a small X11 appli- | |
50 | cation if running under X11, or from the terminal if running without X). | |
51 | It then sends the identity to the agent. Several identities can be | |
52 | stored in the agent; the agent can automatically use any of these identi- | |
53 | ties. ssh-add -l displays the identities currently held by the agent. | |
54 | ||
55 | The idea is that the agent is run in the user's local PC, laptop, or ter- | |
56 | minal. Authentication data need not be stored on any other machine, and | |
57 | authentication passphrases never go over the network. However, the con- | |
58 | nection to the agent is forwarded over SSH remote logins, and the user | |
59 | can thus use the privileges given by the identities anywhere in the net- | |
60 | work in a secure way. | |
61 | ||
62 | There are two main ways to get an agent set up: The first is that the | |
63 | agent starts a new subcommand into which some environment variables are | |
64 | exported, eg ssh-agent xterm &. The second is that the agent prints the | |
65 | needed shell commands (either sh(1) or csh(1) syntax can be generated) | |
66 | which can be evalled in the calling shell, eg eval `ssh-agent -s` for | |
67 | Bourne-type shells such as sh(1) or ksh(1) and eval `ssh-agent -c` for | |
68 | csh(1) and derivatives. | |
69 | ||
70 | Later ssh(1) looks at these variables and uses them to establish a con- | |
71 | nection to the agent. | |
72 | ||
73 | The agent will never send a private key over its request channel. In- | |
74 | stead, operations that require a private key will be performed by the | |
75 | agent, and the result will be returned to the requester. This way, pri- | |
76 | vate keys are not exposed to clients using the agent. | |
77 | ||
78 | A unix-domain socket is created and the name of this socket is stored in | |
79 | the SSH_AUTH_SOCK environment variable. The socket is made accessible | |
80 | only to the current user. This method is easily abused by root or anoth- | |
81 | er instance of the same user. | |
82 | ||
83 | The SSH_AGENT_PID environment variable holds the agent's process ID. | |
84 | ||
85 | The agent exits automatically when the command given on the command line | |
86 | terminates. | |
87 | ||
88 | FILES | |
89 | ~/.ssh/identity | |
90 | Contains the protocol version 1 RSA authentication identity of | |
91 | the user. | |
92 | ||
93 | ~/.ssh/id_dsa | |
94 | Contains the protocol version 2 DSA authentication identity of | |
95 | the user. | |
96 | ||
97 | ~/.ssh/id_rsa | |
98 | Contains the protocol version 2 RSA authentication identity of | |
99 | the user. | |
100 | ||
101 | /tmp/ssh-XXXXXXXXXX/agent.<ppid> | |
102 | Unix-domain sockets used to contain the connection to the authen- | |
103 | tication agent. These sockets should only be readable by the | |
104 | owner. The sockets should get automatically removed when the | |
105 | agent exits. | |
106 | ||
107 | SEE ALSO | |
108 | ssh(1), ssh-add(1), ssh-keygen(1), sshd(8) | |
109 | ||
110 | AUTHORS | |
111 | OpenSSH is a derivative of the original and free ssh 1.2.12 release by | |
112 | Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo | |
113 | de Raadt and Dug Song removed many bugs, re-added newer features and cre- | |
114 | ated OpenSSH. Markus Friedl contributed the support for SSH protocol | |
115 | versions 1.5 and 2.0. | |
116 | ||
117 | OpenBSD 4.0 September 25, 1999 2 |