Network Working Group                                          D. Moffat
Internet-Draft                                          Sun Microsystems
Expires: June 10, 2002                                 December 10, 2001                                        Tatu Ylonen
INTERNET-DRAFT                                             Timo J. Rinne
draft-ietf-secsh-agent-01.txt                              Sami Lehtinen
Expires in six months                        SSH Communications Security
                                                       20 November, 2002

               Secure Shell Authentication Agent Forwarding
                     draft-ietf-secsh-agent-00.txt Protocol

Status of this This Memo

This document is an Internet-Draft and is in full conformance
with all provisions of Section 10 of RFC2026.

Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups.  Note that
other groups may also distribute working documents as Internet-
   Drafts.
Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time.  It is inappropriate to use Internet-Drafts Internet-
Drafts as reference material or to cite them other than as
"work in progress."

The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.
http://www.ietf.org/ietf/1id-abstracts.txt

The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on June 10, 2002.

Copyright Notice

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

Abstract

   SSH is a protocol for secure remote login and other secure network
   services over an insecure network.  One of the common authentication
   mechanisms used with SSH is public key.

This document describes the Secure Shell authentication agent forwarding protocol, which protocol
(i.e., the protocol used between a client requesting authentication and
the authentication agent).  This protocol usually runs as in a machine-spe-
cific local channel or over [SSH-TRANS] it a forwarded authentication channel.  It is designed to ensure
assumed that the sensitive private
   keys never leave channel is trusted, so no protection for the users control even when using SSH to login over
   multiple hops. communica-
tions channel is provided by this protocol.

Table of Contents

1.  Introduction  Authentication Agent Protocol   . . . . . . . . . . . . . . . . .  2
  1.1.  Packet Format   . . . . . . . . . . . . . . . . . . . . . . .  2
  1.2.  Forwarding Notices  . . . . . . . . . . . . . . . . . . . . .  3
  1.3.  Requesting Version Number   . . . . . . . . . . . . . . . . .  3
   1.1
  1.4.  Adding Keys to the Agent Operations  . . . . . . . . . . . . . . . . . .  4
  1.5.  Deleting Keys from the Agent  . . . . .  3
   2.  Security Considerations . . . . . . . . . . .  5
  1.6.  Deleting specific key from the Agent  . . . . . . . .  3
   3.  Additional Information . . . .  5
  1.7.  Listing the Keys that the Agent Can Use   . . . . . . . . . .  6
2.  Performing Private Key Operations   . . . . . .  4
       References . . . . . . . . .  6
  2.1.  Signing   . . . . . . . . . . . . . . . . .  4
       Author's Address . . . . . . . . .  7
  2.2.  Decrypting  . . . . . . . . . . . . . .  4
       Full Copyright Statement . . . . . . . . . . .  7
  2.3.  Secure Shell Challenge-Response Authentication  . . . . . . .  7
3.  Administrative Messages   .  5

1. Introduction

   This protocol is designed to facilitate an ad hoc secure single sign
   on mechanism using the SSH protocol.  A typical scenario is that a
   user has their private keys stored on their laptop (host A) . . . . . . . . . . . . . . . . . . .  7
  3.1.  Locking and uses unlocking the SSH protocol to remotely connect to their corporate VPN (host B)
   access point.  Then uses further SSH connections to reach a specific
   host (host C) within the enterprise network.

   Without agent forwarding the user is required to have a copy of their
   private key on host A and host B so that the connection to host C can
   be made using public   . . . . . . . . . . . . . .  8
  3.2.  Miscellaneous Agent Commands  . . . . . . . . . . . . . . . .  8
4.  Agent Forwarding With Secure Shell  . . . . . . . . . . . . . . .  9
  4.1.  Requesting Agent Forwarding   . . . . . . . . . . . . . . . .  9
  4.2.  Agent Forwarding Channels   . . . . . . . . . . . . . . . . .  9
5.  Security Considerations   . . . . . . . . . . . . . . . . . . . .  9
6.  Intellectual Property   . . . . . . . . . . . . . . . . . . . . . 10
7.  Additional Information  . . . . . . . . . . . . . . . . . . . . . 10
8.  References  . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
9.  Address of Authors  . . . . . . . . . . . . . . . . . . . . . . . 10

1.  Authentication Agent Protocol

The authentication agent is a piece of software that runs in a user's
local workstation, laptop, or other trusted device.  It is used to
implement single sign-on.  It holds the user's private keys in its own
storage, and can perform requested operations using the private key.  It
allows the keys to be kept on a smartcard or other special hardware that
can perform cryptographic operations.

The authentication agent protocol is used to communicate between the
authentication agent and clients wanting to authenticate something or
wanting to perform private key operations.

The actual communication between the client and the agent happens using
a machine-dependent trusted communications channel.  This channel would
typically be a local socket, named pipe, or some kind of secure
messaging system that works inside the local machine.

The protocol works by the client sending requests to the agent, and the
agent responding to these requests.

1.1.  Packet Format

All messages passed to/from the authentication agent have the following
format:

  uint32           length
  byte             type
  data[length -1]  data payload

The following packet types are currently defined:

   /* Messages sent by the client. */
   #define SSH_AGENT_REQUEST_VERSION                        1
   #define SSH_AGENT_ADD_KEY                              202
   #define SSH_AGENT_DELETE_ALL_KEYS                      203
   #define SSH_AGENT_LIST_KEYS                            204
   #define SSH_AGENT_PRIVATE_KEY_OP                       205
   #define SSH_AGENT_FORWARDING_NOTICE                    206
   #define SSH_AGENT_DELETE_KEY                           207
   #define SSH_AGENT_LOCK                                 208
   #define SSH_AGENT_UNLOCK                               209
   #define SSH_AGENT_PING                                 212
   #define SSH_AGENT_RANDOM                               213

   /* Messages sent by the agent. */
   #define SSH_AGENT_SUCCESS                              101
   #define SSH_AGENT_FAILURE                              102
   #define SSH_AGENT_VERSION_RESPONSE                     103
   #define SSH_AGENT_KEY_LIST                             104
   #define SSH_AGENT_OPERATION_COMPLETE                   105
   #define SSH_AGENT_RANDOM_DATA                          106
   #define SSH_AGENT_ALIVE                                150

1.2.  Forwarding Notices

If the agent connection is forwarded through intermediate hosts (using
the SSH Connection Protocol agent forwarding feature (described in
Section ``Agent Forwarding With Secure Shell'' of this document), or
some other means), each intermediate node (Secure Shell client) should
insert the following message into the agent channel before forwarding
any other messages.  The real agent will then receive these messages in
sequence the nearest node first, and can determine whether the
connection is from a local machine and if not, can log the path where
the connection came from.  These messages must be wrapped in the
appropriate header.

  byte      SSH_AGENT_FORWARDING_NOTICE
  string    remote host name  (as typed by the user, preferably)
  string    remote host ip
  uint32    remote host port

1.3.  Requesting Version Number

When the client opens a connection, it must send the following message
to the server.  This must be the first message sent.  The real agent
will receive this after zero or more forwarding notice messages.
  byte      SSH_AGENT_REQUEST_VERSION
  string    version string of the application sending the request
            (optional)

If the agent follows this protocol, it will respond with

  byte      SSH_AGENT_VERSION_RESPONSE
  uint32    version number, 2 for this protocol

If the version number request is ever sent to the Secure Shell 1.x
agent, it will interpret it as a request to list identities.  It will
then respond with a message whose first byte is 2.  This can be used to
determine the version of the agent if compatibility with Secure Shell
1.x is desired.

If the version string query arrives without trailing string identifying
the client software version, it can be translated list identities
request sent by Secure Shell 1.x and handled accordingly.  If agent
software does not support the agent protocol of Secure Shell 1.x, it MAY
also interpret this query as valid SSH_AGENT_REQUEST_VERSION packet.

1.4.  Adding Keys to the Agent

The client can add a new private key to the agent with the following
message.

  byte      SSH_AGENT_ADD_KEY
  string    private key blob with empty passphrase
  string    public key and/or certificates for it
  string    description of the key
  ... 0, 1 or several constraints follow

All constraints are pairs of following format:

  byte      SSH_AGENT_CONSTRAINT_*
  variable  argument for the constraint

The type of the argument is dependent on the constraint type.  Following
constraint types are currently defined:

   /* Constraints 50-99 have a uint32 argument */

   /* Argument is uint32 defining key expiration time-out in
      seconds. After this timeout expires, the key can't be used.
      0 == no timeout */
   #define SSH_AGENT_CONSTRAINT_TIMEOUT                 50

   /* Argument is uint32 defining the number of operations that can
      be performed with this key.  0xffffffff == no limit */
   #define SSH_AGENT_CONSTRAINT_USE_LIMIT               51

   /* Argument is uint32 defining the number of forwarding steps that
      this key can be forwarded.  0xffffffff == no limit */
   #define SSH_AGENT_CONSTRAINT_FORWARDING_STEPS        52
   /* Constraints 100-149 have a string argument */

   /* Argument is string defining the allowed forwarding steps for
      this key. XXX define this. */
   #define SSH_AGENT_CONSTRAINT_FORWARDING_PATH        100

   /* Constraints 150-199 have a boolean argument */

   /* Argument is a boolean telling whether the key can be used
      in Secure Shell 1.x compatibility operations. */

   #define SSH_AGENT_CONSTRAINT_SSH1_COMPAT            150

   /* Argument is a boolean telling whether operations performed
      with this key should  be confirmed interactively by the user
      or not. */
   #define SSH_AGENT_CONSTRAINT_NEED_USER_VERIFICATION 151

Message can contain zero, one or multiple constraints.

If the operation is successful, the agent will respond with the
following message.

   byte      SSH_AGENT_SUCCESS

If the operation fails for some reason, the following message will be
returned instead.

   byte      SSH_AGENT_FAILURE
   uint32    error code

The error code is one of the following:

   #define SSH_AGENT_ERROR_TIMEOUT               1
   #define SSH_AGENT_ERROR_KEY_NOT_FOUND         2
   #define SSH_AGENT_ERROR_DECRYPT_FAILED        3
   #define SSH_AGENT_ERROR_SIZE_ERROR            4
   #define SSH_AGENT_ERROR_KEY_NOT_SUITABLE      5
   #define SSH_AGENT_ERROR_DENIED                6
   #define SSH_AGENT_ERROR_FAILURE               7
   #define SSH_AGENT_ERROR_UNSUPPORTED_OP        8

1.5.  Deleting Keys from the Agent

All keys that are in possession of the agent can be deleted with the
following message.  (The client is allowed to ignore this for some keys
if desired.)

   byte      SSH_AGENT_DELETE_ALL_KEYS

The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.

1.6.  Deleting specific key from the Agent

The client can delete a specific key with given public key with
following message.

   byte      SSH_AGENT_DELETE_KEY
   string    public key and/or certificates for it
   string    description of the key

The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.

1.7.  Listing the Keys that the Agent Can Use

The following message requests a list of all keys that the agent can
use.

   byte      SSH_AGENT_LIST_KEYS

The agent will respond with the following message.

   byte      SSH_AGENT_KEY_LIST
   uint32    number_of_keys
   repeats number_of_keys times:
    string    public key blob or certificates
    string    description

2.  Performing Private Key Operations

The real purpose of the agent is to perform private key operations.
Such operations are performed with the following message.

   byte      SSH_AGENT_PRIVATE_KEY_OP
   string    operation name
   string    key or certificates, as returned in SSH_AGENT_KEY_LIST
   ... operation-specific data follows

The operation to be performed is identified by a name (string).  Custom
operations can be added by suffixing the operation name by the fully
qualified domain name of the person/organization adding the new
operation.

When the operation is complete, the agent will respond with either
SSH_AGENT_FAILURE or with the following message if the operation is
successful:

   byte      SSH_AGENT_OPERATION_COMPLETE
   string    resulting data

If an operation is attempted that is not supported by the agent, the
agent will respond with SSH_AGENT_FAILURE with error code set to
SSH_AGENT_ERROR_UNSUPPORTED_OP.

The standard operations are defined below.

2.1.  Signing

The agent can be used to create a digital signature using a key held by
the agent.  The operation name is "sign", and data in is a hash
(suitable for the key) that is to be signed.  This normally performs the
raw private key operation, without hashing data first.  The resulting
data will be a binary representation of the output of the private key
operation.  The exact details of the operations to be performed depend
on the key being used.

The operation-specific data has the following format:

   string    data to be signed

Alternatively, it is possible to give the actual data to be signed to
the agent.  This is done using the operation "hash-and-sign".  This is
otherwise equal, but performs key-dependent hashing before signing.

If the requested operation is not legal for the key, SSH_AGENT_FAILURE
will be returned with error code set to
SSH_AGENT_ERROR_KEY_NOT_SUITABLE.

2.2.  Decrypting

The agent can be used to decrypt a public key encrypted message with the
operation "decrypt".  This takes in raw public-key encrypted data, and
returns the resulting decrypted data.

This may also fail.  If the requested operation is not legal for the
key, error code is set to SSH_AGENT_ERROR_KEY_NOT_SUITABLE.

The operation-specific data has the following format:

   string    data to be decrypted

2.3.  Secure Shell Challenge-Response Authentication

Performs Secure Shell challenge-response authentication.  This operation
has the name "ssh1-challenge-response".

This operation works by first decrypting the challenge, then computing
MD5 of the concatenation of the decrypted challenge and the session id
(in this order), and returns the resulting 16 byte hash.  The operation-
specific data is in the following format:

   string    challenge encrypted using the public key
   string    session id

Normally, the length of the challenge before encryption will be 32 bytes
and the length of the session id 16 bytes.  The length of the encrypted
challenge depends on the key and algorithm used.

3.  Administrative Messages

There are also a number of messages that are only used to administer the
agent.  These might e.g. be used by a user interface for the agent.  The
agent should only allow these messages from local connection (i.e., if
no forwarding notice messages were received before the version number
request).

3.1.  Locking and unlocking the agent

The agent can be temporarily locked by message:

   byte      SSH_AGENT_LOCK
   string    locking password

The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
Particularily SSH_AGENT_FAILURE is sent, if agent is already locked.
After this message, agent responds to all commands with
SSH_AGENT_FAILURE until it receives a following command.

   byte      SSH_AGENT_UNLOCK
   string    locking password

The agent responds with either SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
Particularily SSH_AGENT_FAILURE is sent, if agent is not locked or if
the submitted password does not match with one given with SSH_AGENT_LOCK
message.

3.2.  Miscellaneous Agent Commands

   byte      SSH_AGENT_PING
   ... arbitrary padding data

Any agent or client receiving this message, should respond with

   byte      SSH_AGENT_ALIVE
   ... padding data from the SSH_AGENT_PING request

where the padding data is identical to the data sent with
SSH_AGENT_PING.

   byte      SSH_AGENT_RANDOM
   uint32    the length of the requested random buffer

Client can request random data from the agent by this message.  Agent
responds either with SSH_AGENT_RANDOM_DATA or SSH_AGENT_FAILURE message.

   byte      SSH_AGENT_RANDOM_DATA
   string    random data

This message is a successful response to SSH_AGENT_RANDOM message.
Message contains the random string of requested length.

4.  Agent Forwarding With Secure Shell

The key pairs used agent connection is typically forwarded over a Secure Shell
connection. This requires small additions to the SSH Connection Protocol
[SSH-CONN].

4.1.  Requesting Agent Forwarding

Agent forwarding may be requested for a session by sending

  byte      SSH_MSG_CHANNEL_REQUEST
  uint32    recipient channel
  string    "auth-agent-req"
  boolean   want reply

This will, on success, create an agent listener to the
   host A remote end.

4.2.  Agent Forwarding Channels

When a connection comes to B and the host B forwarded agent listener, a channel is
opened to C forward the connection maybe to the same but this is other side.

  byte      SSH_MSG_CHANNEL_OPEN
  string    "auth-agent"
  uint32    sender channel
  uint32    initial window size
  uint32    maximum packet size

Implementations MUST reject these messages unless they have previously
requested agent forwarding.

Forwarded agent channels are independent of any sessions, and closing a
session channel does not always in any way imply that forwarded connections
should be closed.

5.  Security Considerations

The authentication agent is used to control security-sensitive
operations, and is used to implement single sign-on.

Anyone with access to the authentication agent can perform private key
operations with the case. agent.  This presents is a security risk since power equivalent to possession of
the users private key(s) must be
   stored on host B which is likely key as long as the connection to be a host the end user key is maintained.  It
is not in
   control of even though they do trust it. possible to retrieve the key from the agent.

It is likely recommended that agent implementations allow and perform some form
of logging and access control.  This access control may utilize
information about the
   private keys on host A path through which the connection was received (as
collected with SSH_AGENT_FORWARDING_NOTICE messages; however, the path
is reliable only up to and host B are stored in an encrypted format,
   this means including the user has at least two passwords first unreliable machine.).
Implementations should also allow restricting the operations that can be
performed with keys - e.g., limiting them to challenge-response only.

One should note that a local superuser will be able to enter obtain access to make
agents running on the
   connection from A local machine.  This cannot be prevented; in most
operating systems, a user with sufficient privileges will be able to C.

   Ideally
read the private keys from the physical memory.

The authentication agent should remain not be run or forwarded to machine whose
integrity is not trusted, as security on such machines might be
compromised and might allow an attacker to obtain unauthorized access to
the agent.

6.  Intellectual Property

The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to pertain
to the implementation or use of the technology described in this
document or the extent to which any license under such rights might or
might not be available; neither does it represent that it has made any
effort to identify any such rights.  Information on a device in the direct
   control of the end user (host A IETF's
procedures with respect to rights in this example) and all encryption standards-track and signing operations involving the private key should standards-
related documentation can be performed
   on this device, regardless found in BCP-11.  Copies of the location claims of the entity requesting
   the operation.

1.1 Agent Operations

   The following interactions with the agent are requried: ADD, DELETE,
   LIST, SIGN.

   An agent implementation MUST support requests
rights made available for publication and any assurances of licenses to forward operations
   using all public key types, defined in [SSH-USERAUTH] even those that
be made available, or the implementation doesn't support natively.

2. Security Considerations

   This protocol is designed only result of an attempt made to run as obtain a channel general
license or permission for the use of such proprietary rights by
implementers or users of this specification can be obtained from the SSH
   protocol.
IETF Secretariat.

The goal IETF has been notified of this extension is intellectual property rights claimed in
regard to ensure that the users private keys
   never leave some or all of the machine they are physically at.  Ideally specification contained in this document.
For more information consult the private
   keys should be stored on a password protected removable media such as
   a smartcard.

3. online list of claimed rights.

7.  Additional Information

The current document editor is: Darren.Moffat@Sun.COM. Sami Lehtinen <sjl@ssh.com>.  Comments
on this internet draft Internet-Draft should be sent to the IETF SECSH working group,
details at: http://ietf.org/html.charters/secsh-charter.html

8.  References

   [FIPS-186]      Federal Information Processing Standards Publication,
                   ., "FIPS PUB 186, Digital Signature Standard", May
                   1994.

   [SSH-ARCH]      Ylonen, T., "SSH Protocol Architecture", I-D draft-
                   ietf-architecture-11.txt, July 2001.

   [SSH-TRANS]

[SECSH-CONNECT] Ylonen, T., "SSH Transport Layer Protocol", I-D
                   draft-ietf-transport-11.txt, July 2001.

   [SSH-USERAUTH]  Ylonen, T., "SSH Authentication Protocol", I-D draft-
                   ietf-userauth-13.txt, July 2001.

   [SSH-CONNECT]   Ylonen, T., "SSH et al: "Secure Shell Connection Protocol", I-D draft-
                   ietf-connect-14.txt, July 2001.

Author's
Internet-Draft, draft-ietf-secsh-connect-16.txt

9.  Address

   Darren J Moffat
   Sun Microsystems
   901 San Antonio Road
   Palo Alto  94303
   USA

   EMail: Darren.Moffat@Sun.COM

Full Copyright Statement

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society. Authors

   Tatu Ylonen
    SSH Communications Security Corp
    Fredrikinkatu 42
    FIN-00100 HELSINKI
    Finland
    E-mail: ylo@ssh.com

   Timo J. Rinne
    SSH Communications Security Corp
    Fredrikinkatu 42
    FIN-00100 HELSINKI
    Finland
    E-mail: tri@ssh.com

   Sami Lehtinen
    SSH Communications Security Corp
    Fredrikinkatu 42
    FIN-00100 HELSINKI
    Finland
    E-mail: sjl@ssh.com