X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/f54651ce685d837d482836e5e9dcf35b67b452b8..HEAD:/ssh-agent.1 diff --git a/ssh-agent.1 b/ssh-agent.1 index b49d62b5..8d1da46e 100644 --- a/ssh-agent.1 +++ b/ssh-agent.1 @@ -1,17 +1,40 @@ -.\" $OpenBSD: ssh-agent.1,v 1.11 2000/04/12 21:47:50 aaron Exp $ -.\" -.\" -*- nroff -*- -.\" -.\" ssh-agent.1 +.\" $OpenBSD: ssh-agent.1,v 1.50 2010/01/17 21:49:09 tedu Exp $ .\" .\" Author: Tatu Ylonen -.\" .\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland .\" All rights reserved .\" -.\" Created: Sat Apr 23 20:10:43 1995 ylo +.\" As far as I am concerned, the code I have written for this software +.\" can be used freely for any purpose. Any derived versions of this +.\" software must be clearly marked as such, and if the derived work is +.\" incompatible with the protocol description in the RFC file, it must be +.\" called by a name other than "ssh" or "Secure Shell". +.\" +.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. +.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. +.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. .\" -.Dd September 25, 1999 +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate$ .Dt SSH-AGENT 1 .Os .Sh NAME @@ -20,42 +43,65 @@ .Sh SYNOPSIS .Nm ssh-agent .Op Fl c Li | Fl s -.Op Fl k -.Oo -.Ar command -.Op Ar args ... -.Oc +.Op Fl d +.Op Fl a Ar bind_address +.Op Fl t Ar life +.Op Ar command Op Ar arg ... +.Nm ssh-agent +.Op Fl c Li | Fl s +.Fl k .Sh DESCRIPTION .Nm -is a program to hold authentication private keys. +is a program to hold private keys used for public key authentication +(RSA, DSA). The idea is that .Nm is started in the beginning of an X-session or a login session, and all other windows or programs are started as clients to the ssh-agent program. Through use of environment variables the agent can be located -and automatically used for RSA authentication when logging in to other +and automatically used for authentication when logging in to other machines using .Xr ssh 1 . .Pp The options are as follows: .Bl -tag -width Ds +.It Fl a Ar bind_address +Bind the agent to the +.Ux Ns -domain +socket +.Ar bind_address . +The default is +.Pa /tmp/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt . .It Fl c Generate C-shell commands on .Dv stdout . This is the default if .Ev SHELL looks like it's a csh style of shell. +.It Fl d +Debug mode. +When this option is specified +.Nm +will not fork. +.It Fl k +Kill the current agent (given by the +.Ev SSH_AGENT_PID +environment variable). .It Fl s Generate Bourne shell commands on .Dv stdout . This is the default if .Ev SHELL does not look like it's a csh style of shell. -.It Fl k -Kill the current agent (given by the -.Ev SSH_AGENT_PID -environment variable). +.It Fl t Ar life +Set a default value for the maximum lifetime of identities added to the agent. +The lifetime may be specified in seconds or in a time format specified in +.Xr sshd_config 5 . +A lifetime specified for an identity with +.Xr ssh-add 1 +overrides this value. +Without this option the default maximum lifetime is forever. .El .Pp If a commandline is given, this is executed as a subprocess of the agent. @@ -66,13 +112,16 @@ Keys are added using .Xr ssh-add 1 . When executed without arguments, .Xr ssh-add 1 -adds the -.Pa $HOME/.ssh/identity -file. +adds the files +.Pa ~/.ssh/id_rsa , +.Pa ~/.ssh/id_dsa +and +.Pa ~/.ssh/identity . If the identity has a passphrase, .Xr ssh-add 1 -asks for the passphrase (using a small X11 application if running -under X11, or from the terminal if running without X). +asks for the passphrase on the terminal if it has one or from a small X11 +program if running under X11. +If neither of these is the case then the authentication will fail. It then sends the identity to the agent. Several identities can be stored in the agent; the agent can automatically use any of these identities. @@ -87,21 +136,38 @@ However, the connection to the agent is forwarded over SSH remote logins, and the user can thus use the privileges given by the identities anywhere in the network in a secure way. .Pp -There are two main ways to get an agent setup: -Either you let the agent -start a new subcommand into which some environment variables are exported, or -you let the agent print the needed shell commands (either +There are two main ways to get an agent set up: +The first is that the agent starts a new subcommand into which some environment +variables are exported, eg +.Cm ssh-agent xterm & . +The second is that the agent prints the needed shell commands (either +.Xr sh 1 +or +.Xr csh 1 +syntax can be generated) which can be evaluated in the calling shell, eg +.Cm eval `ssh-agent -s` +for Bourne-type shells such as .Xr sh 1 or +.Xr ksh 1 +and +.Cm eval `ssh-agent -c` +for .Xr csh 1 -syntax can be generated) which can be evalled in the calling shell. +and derivatives. +.Pp Later .Xr ssh 1 -look at these variables and use them to establish a connection to the agent. +looks at these variables and uses them to establish a connection to the agent. +.Pp +The agent will never send a private key over its request channel. +Instead, operations that require a private key will be performed +by the agent, and the result will be returned to the requester. +This way, private keys are not exposed to clients using the agent. .Pp -A unix-domain socket is created -.Pq Pa /tmp/ssh-XXXXXXXX/agent. , -and the name of this socket is stored in the +A +.Ux Ns -domain +socket is created and the name of this socket is stored in the .Ev SSH_AUTH_SOCK environment variable. @@ -111,61 +177,35 @@ user. .Pp The .Ev SSH_AGENT_PID -environment variable holds the agent's PID. +environment variable holds the agent's process ID. .Pp The agent exits automatically when the command given on the command line terminates. .Sh FILES .Bl -tag -width Ds -.It Pa $HOME/.ssh/identity -Contains the RSA authentication identity of the user. -This file should not be readable by anyone but the user. -It is possible to -specify a passphrase when generating the key; that passphrase will be -used to encrypt the private part of this file. -This file is not used by -.Nm -but is normally added to the agent using -.Xr ssh-add 1 -at login time. -.It Pa /tmp/ssh-XXXX/agent. , -Unix-domain sockets used to contain the connection to the -authentication agent. +.It Pa ~/.ssh/identity +Contains the protocol version 1 RSA authentication identity of the user. +.It Pa ~/.ssh/id_dsa +Contains the protocol version 2 DSA authentication identity of the user. +.It Pa ~/.ssh/id_rsa +Contains the protocol version 2 RSA authentication identity of the user. +.It Pa /tmp/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt +.Ux Ns -domain +sockets used to contain the connection to the authentication agent. These sockets should only be readable by the owner. The sockets should get automatically removed when the agent exits. -.Sh AUTHOR -Tatu Ylonen -.Pp -OpenSSH -is a derivative of the original (free) ssh 1.2.12 release, but with bugs -removed and newer features re-added. -Rapidly after the 1.2.12 release, -newer versions bore successively more restrictive licenses. -This version of OpenSSH -.Bl -bullet -.It -has all components of a restrictive nature (i.e., patents, see -.Xr ssl 8 ) -directly removed from the source code; any licensed or patented components -are chosen from -external libraries. -.It -has been updated to support ssh protocol 1.5. -.It -contains added support for -.Xr kerberos 8 -authentication and ticket passing. -.It -supports one-time password authentication with -.Xr skey 1 . .El -.Pp -The libraries described in -.Xr ssl 8 -are required for proper operation. .Sh SEE ALSO .Xr ssh 1 , .Xr ssh-add 1 , .Xr ssh-keygen 1 , -.Xr sshd 8 , -.Xr ssl 8 +.Xr sshd 8 +.Sh AUTHORS +OpenSSH is a derivative of the original and free +ssh 1.2.12 release by Tatu Ylonen. +Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, +Theo de Raadt and Dug Song +removed many bugs, re-added newer features and +created OpenSSH. +Markus Friedl contributed the support for SSH +protocol versions 1.5 and 2.0.