draft-ietf-secsh-agent-01.txt   draft-ietf-secsh-agent-02.txt 
Network Working Group Tatu Ylonen Network Working Group Tatu Ylonen
INTERNET-DRAFT Timo J. Rinne INTERNET-DRAFT Timo J. Rinne
draft-ietf-secsh-agent-01.txt Sami Lehtinen draft-ietf-secsh-agent-02.txt Sami Lehtinen
Expires in six months SSH Communications Security Expires: July 30, 2004 SSH Communications Security
20 November, 2002 30 January, 2004
Secure Shell Authentication Agent Protocol Secure Shell Authentication Agent Protocol
Status of This Memo Status of This Memo
This document is an Internet-Draft and is in full conformance This document is an Internet-Draft and is in full conformance
with all provisions of Section 10 of RFC2026. with all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 2, line 8 skipping to change at page 2, line 8
This document describes the Secure Shell authentication agent protocol This document describes the Secure Shell authentication agent protocol
(i.e., the protocol used between a client requesting authentication and (i.e., the protocol used between a client requesting authentication and
the authentication agent). This protocol usually runs in a machine-spe- the authentication agent). This protocol usually runs in a machine-spe-
cific local channel or over a forwarded authentication channel. It is cific local channel or over a forwarded authentication channel. It is
assumed that the channel is trusted, so no protection for the communica- assumed that the channel is trusted, so no protection for the communica-
tions channel is provided by this protocol. tions channel is provided by this protocol.
Table of Contents Table of Contents
1. Authentication Agent Protocol . . . . . . . . . . . . . . . . . 2 1. Authentication Agent Protocol . . . . . . . . . . . . . . . . . 2
1.1. Packet Format . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Packet Format . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Forwarding Notices . . . . . . . . . . . . . . . . . . . . . 3 1.2. Forwarding Notices . . . . . . . . . . . . . . . . . . . . . 3
1.3. Requesting Version Number . . . . . . . . . . . . . . . . . 3 1.3. Requesting Version Number . . . . . . . . . . . . . . . . . 4
1.4. Adding Keys to the Agent . . . . . . . . . . . . . . . . . . 4 1.4. Adding Keys to the Agent . . . . . . . . . . . . . . . . . . 4
1.5. Deleting Keys from the Agent . . . . . . . . . . . . . . . . 5 1.4.1. Key types . . . . . . . . . . . . . . . . . . . . . . . 5
1.6. Deleting specific key from the Agent . . . . . . . . . . . . 5 1.4.2. Forwarding constraints . . . . . . . . . . . . . . . . . 5
1.7. Listing the Keys that the Agent Can Use . . . . . . . . . . 6 1.5. Deleting Keys from the Agent . . . . . . . . . . . . . . . . 7
2. Performing Private Key Operations . . . . . . . . . . . . . . . 6 1.6. Deleting specific key from the Agent . . . . . . . . . . . . 7
2.1. Signing . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.7. Listing the Keys that the Agent Can Use . . . . . . . . . . 7
2.2. Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . 7 2. Performing Private Key Operations . . . . . . . . . . . . . . . 7
2.3. Secure Shell Challenge-Response Authentication . . . . . . . 7 2.1. Signing . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. Administrative Messages . . . . . . . . . . . . . . . . . . . . 7 2.2. Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1. Locking and unlocking the agent . . . . . . . . . . . . . . 8 2.3. Secure Shell Challenge-Response Authentication . . . . . . . 8
3.2. Miscellaneous Agent Commands . . . . . . . . . . . . . . . . 8 3. Administrative Messages . . . . . . . . . . . . . . . . . . . . 9
4. Agent Forwarding With Secure Shell . . . . . . . . . . . . . . . 9 3.1. Locking and unlocking the agent . . . . . . . . . . . . . . 9
4.1. Requesting Agent Forwarding . . . . . . . . . . . . . . . . 9 3.2. Miscellaneous Agent Commands . . . . . . . . . . . . . . . . 9
4.2. Agent Forwarding Channels . . . . . . . . . . . . . . . . . 9 4. Agent Forwarding With Secure Shell . . . . . . . . . . . . . . . 10
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 9 4.1. Requesting Agent Forwarding . . . . . . . . . . . . . . . . 10
6. Intellectual Property . . . . . . . . . . . . . . . . . . . . . 10 4.2. Agent Forwarding Channels . . . . . . . . . . . . . . . . . 10
7. Additional Information . . . . . . . . . . . . . . . . . . . . . 10 5. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . . . 10
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 11
9. Address of Authors . . . . . . . . . . . . . . . . . . . . . . . 10 7. Intellectual Property . . . . . . . . . . . . . . . . . . . . . 12
8. Additional Information . . . . . . . . . . . . . . . . . . . . . 12
9. Changes from previous versions . . . . . . . . . . . . . . . . . 12
9.1. Changes between versions 3 and 2 . . . . . . . . . . . . . . 12
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
11. Address of Authors . . . . . . . . . . . . . . . . . . . . . . 13
1. Authentication Agent Protocol 1. Authentication Agent Protocol
The authentication agent is a piece of software that runs in a user's 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 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 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 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 allows the keys to be kept on a smartcard or other special hardware that
can perform cryptographic operations. can perform cryptographic operations.
skipping to change at page 3, line 24 skipping to change at page 3, line 29
#define SSH_AGENT_DELETE_ALL_KEYS 203 #define SSH_AGENT_DELETE_ALL_KEYS 203
#define SSH_AGENT_LIST_KEYS 204 #define SSH_AGENT_LIST_KEYS 204
#define SSH_AGENT_PRIVATE_KEY_OP 205 #define SSH_AGENT_PRIVATE_KEY_OP 205
#define SSH_AGENT_FORWARDING_NOTICE 206 #define SSH_AGENT_FORWARDING_NOTICE 206
#define SSH_AGENT_DELETE_KEY 207 #define SSH_AGENT_DELETE_KEY 207
#define SSH_AGENT_LOCK 208 #define SSH_AGENT_LOCK 208
#define SSH_AGENT_UNLOCK 209 #define SSH_AGENT_UNLOCK 209
#define SSH_AGENT_PING 212 #define SSH_AGENT_PING 212
#define SSH_AGENT_RANDOM 213 #define SSH_AGENT_RANDOM 213
#define SSH_AGENT_EXTENSION 301
/* Messages sent by the agent. */ /* Messages sent by the agent. */
#define SSH_AGENT_SUCCESS 101 #define SSH_AGENT_SUCCESS 101
#define SSH_AGENT_FAILURE 102 #define SSH_AGENT_FAILURE 102
#define SSH_AGENT_VERSION_RESPONSE 103 #define SSH_AGENT_VERSION_RESPONSE 103
#define SSH_AGENT_KEY_LIST 104 #define SSH_AGENT_KEY_LIST 104
#define SSH_AGENT_OPERATION_COMPLETE 105 #define SSH_AGENT_OPERATION_COMPLETE 105
#define SSH_AGENT_RANDOM_DATA 106 #define SSH_AGENT_RANDOM_DATA 106
#define SSH_AGENT_ALIVE 150 #define SSH_AGENT_ALIVE 150
1.2. Forwarding Notices 1.2. Forwarding Notices
skipping to change at page 3, line 56 skipping to change at page 4, line 10
byte SSH_AGENT_FORWARDING_NOTICE byte SSH_AGENT_FORWARDING_NOTICE
string remote host name (as typed by the user, preferably) string remote host name (as typed by the user, preferably)
string remote host ip string remote host ip
uint32 remote host port uint32 remote host port
1.3. Requesting Version Number 1.3. Requesting Version Number
When the client opens a connection, it must send the following message 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 to the server. This must be the first message sent. The real agent
will receive this after zero or more forwarding notice messages. will receive this after zero or more forwarding notice messages.
byte SSH_AGENT_REQUEST_VERSION byte SSH_AGENT_REQUEST_VERSION
string version string of the application sending the request string version string of the application sending the request
(optional) (optional)
If the agent follows this protocol, it will respond with If the agent follows this protocol, it will respond with
byte SSH_AGENT_VERSION_RESPONSE byte SSH_AGENT_VERSION_RESPONSE
uint32 version number, 2 for this protocol uint32 version number, 3 for this protocol
<extension data>
If the version number request is ever sent to the Secure Shell 1.x 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 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 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 determine the version of the agent if compatibility with Secure Shell
1.x is desired. 1.x is desired.
If the version string query arrives without trailing string identifying If the version string query arrives without trailing string identifying
the client software version, it can be translated list identities the client software version, it can be translated list identities
request sent by Secure Shell 1.x and handled accordingly. If agent 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 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. also interpret this query as valid SSH_AGENT_REQUEST_VERSION packet.
The extension data in the SSH_AGENT_VERSION_RESPONSE may be empty, or
may be a sequence of
string extension_name
string extension_data
pairs (both strings MUST always be present if one is, but the `exten-
sion_data' string may be of zero length). If present, these strings
indicate extensions to the baseline protocol. The `extension_name'
field(s) identify the name of the extension. The name should be of the
form "name@domain", where the domain is the DNS domain name of the orga-
nization defining the extension. Additional names that are not of this
format may be defined later by the IETF. Implementations MUST silently
ignore any extensions whose name they do not recognize.
1.4. Adding Keys to the Agent 1.4. Adding Keys to the Agent
The client can add a new private key to the agent with the following The client can add a new private key to the agent with the following
message. message. Using this message over the net has security implications, and
the implementation SHOULD warn the user before decryption or sending the
private key. (XXX how does ssh-add detect this condition?)
byte SSH_AGENT_ADD_KEY byte SSH_AGENT_ADD_KEY
string private key blob with empty passphrase string private key encoding
string private key blob
string public key encoding
string public key and/or certificates for it string public key and/or certificates for it
string description of the key string description of the key
... 0, 1 or several constraints follow ... 0, 1 or several constraints follow
1.4.1. Key types
Key blobs are preceeded by the encoding field, which defines how the
blob should be interpreted. Defined values for public key encoding are
"ssh-dss" and "ssh-rsa". Additional key types may be defined as
specified in [SECSH-ARCH], under Section IANA Considerations (Section
8).
"ssh-dss" and "ssh-rsa" public key format encodings are defined in
[SECSH-TRANS].
The "ssh-dss" private key format has the following specific encoding:
string "ssh-dss"
mpint p
mpint q
mpint g
mpint y
mpint x
The "ssh-rsa" private key format has the following specific encoding:
string "ssh-rsa"
mpint e
mpint d
mpint n
mpint u
mpint p
mpint q
XXX Additional key-types (for private keys), for example "ssh-rsa-
encrypted"?
1.4.2. Forwarding constraints
All constraints are pairs of following format: All constraints are pairs of following format:
byte SSH_AGENT_CONSTRAINT_* byte SSH_AGENT_CONSTRAINT_*
variable argument for the constraint variable argument for the constraint
The type of the argument is dependent on the constraint type. Following The type of the argument is dependent on the constraint type. Following
constraint types are currently defined: constraint types are currently defined:
/* Constraints 50-99 have a uint32 argument */ /* Constraints 50-99 have a uint32 argument */
skipping to change at page 5, line 34 skipping to change at page 6, line 44
If the operation is successful, the agent will respond with the If the operation is successful, the agent will respond with the
following message. following message.
byte SSH_AGENT_SUCCESS byte SSH_AGENT_SUCCESS
If the operation fails for some reason, the following message will be If the operation fails for some reason, the following message will be
returned instead. returned instead.
byte SSH_AGENT_FAILURE byte SSH_AGENT_FAILURE
uint32 error code uint32 error code
string additional textual information (ISO-10646 UTF-8
[RFC-2279])
string language tag (as defined in [RFC-1766])
The last two fields are optional; they don't need to be present in
SSH_AGENT_FAILURE message. However, both MUST be provided if they are to
be used. If client is version 2, the agent SHOULD NOT use these fields.
The error code is one of the following: The error code is one of the following:
#define SSH_AGENT_ERROR_TIMEOUT 1 #define SSH_AGENT_ERROR_TIMEOUT 1
#define SSH_AGENT_ERROR_KEY_NOT_FOUND 2 #define SSH_AGENT_ERROR_KEY_NOT_FOUND 2
#define SSH_AGENT_ERROR_DECRYPT_FAILED 3 #define SSH_AGENT_ERROR_DECRYPT_FAILED 3
#define SSH_AGENT_ERROR_SIZE_ERROR 4 #define SSH_AGENT_ERROR_SIZE_ERROR 4
#define SSH_AGENT_ERROR_KEY_NOT_SUITABLE 5 #define SSH_AGENT_ERROR_KEY_NOT_SUITABLE 5
#define SSH_AGENT_ERROR_DENIED 6 #define SSH_AGENT_ERROR_DENIED 6
#define SSH_AGENT_ERROR_FAILURE 7 #define SSH_AGENT_ERROR_FAILURE 7
skipping to change at page 9, line 40 skipping to change at page 11, line 5
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
Implementations MUST reject these messages unless they have previously Implementations MUST reject these messages unless they have previously
requested agent forwarding. requested agent forwarding.
Forwarded agent channels are independent of any sessions, and closing a Forwarded agent channels are independent of any sessions, and closing a
session channel does not in any way imply that forwarded connections session channel does not in any way imply that forwarded connections
should be closed. should be closed.
5. Security Considerations 5. Vendor-Specific Extensions
The SSH_AGENT_EXTENSION request provides a generic extension mechanism
for adding vendor-specific commands. The request has the following
format:
byte SSH_AGENT_EXTENSION
string extension_id
... extension-specific data follows ...
`extension_id' is a string of the format "name@domain", where domain is
an internet domain name of the vendor defining the request. The rest of
the request is completely vendor-specific, and servers should only
attempt to interpret it if they recognize the `extension_id' name.
These messages can be sent to either direction. However, the agent MUST
send these messages only as responses to the client's requests. As an
implementation note, the agent should use the standard responses if at
all possible.
If the agent sees an extension message it doesn't understand, it should
respond with SSH_AGENT_FAILURE with error
SSH_AGENT_ERROR_UNSUPPORTED_OP.
6. Security Considerations
The authentication agent is used to control security-sensitive The authentication agent is used to control security-sensitive
operations, and is used to implement single sign-on. operations, and is used to implement single sign-on.
Anyone with access to the authentication agent can perform private key Anyone with access to the authentication agent can perform private key
operations with the agent. This is a power equivalent to possession of operations with the agent. This is a power equivalent to possession of
the private key as long as the connection to the key is maintained. It the private key as long as the connection to the key is maintained. It
is not possible to retrieve the key from the agent. is not possible to retrieve the key from the agent.
It is recommended that agent implementations allow and perform some form It is recommended that agent implementations allow and perform some form
skipping to change at page 10, line 15 skipping to change at page 11, line 56
One should note that a local superuser will be able to obtain access to One should note that a local superuser will be able to obtain access to
agents running on the local machine. This cannot be prevented; in most agents running on the local machine. This cannot be prevented; in most
operating systems, a user with sufficient privileges will be able to operating systems, a user with sufficient privileges will be able to
read the keys from the physical memory. read the keys from the physical memory.
The authentication agent should not be run or forwarded to machine whose The authentication agent should not be run or forwarded to machine whose
integrity is not trusted, as security on such machines might be integrity is not trusted, as security on such machines might be
compromised and might allow an attacker to obtain unauthorized access to compromised and might allow an attacker to obtain unauthorized access to
the agent. the agent.
6. Intellectual Property Adding a key with SSH_AGENT_ADD_KEY over the net (especially over the
Internet) is generally not recommended, because at present the private
key has to be moved unencrypted. Implementations SHOULD warn the user of
the implications. Even moving the key in encrypted form could be
considered unwise.
7. Intellectual Property
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to pertain intellectual property or other rights that might be claimed to pertain
to the implementation or use of the technology described in this to the implementation or use of the technology described in this
document or the extent to which any license under such rights might or 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 might not be available; neither does it represent that it has made any
effort to identify any such rights. Information on the IETF's effort to identify any such rights. Information on the IETF's
procedures with respect to rights in standards-track and standards- procedures with respect to rights in standards-track and standards-
related documentation can be found in BCP-11. Copies of claims of related documentation can be found in BCP-11. Copies of claims of
rights made available for publication and any assurances of licenses to rights made available for publication and any assurances of licenses to
be made available, or the result of an attempt made to obtain a general be made available, or the result of an attempt made to obtain a general
license or permission for the use of such proprietary rights by license or permission for the use of such proprietary rights by
implementers or users of this specification can be obtained from the implementers or users of this specification can be obtained from the
IETF Secretariat. IETF Secretariat.
The IETF has been notified of intellectual property rights claimed in The IETF has been notified of intellectual property rights claimed in
regard to some or all of the specification contained in this document. regard to some or all of the specification contained in this document.
For more information consult the online list of claimed rights. For more information consult the online list of claimed rights.
7. Additional Information 8. Additional Information
The current document editor is: Sami Lehtinen <sjl@ssh.com>. Comments The current document editor is: Sami Lehtinen <sjl@ssh.com>. Comments
on this Internet-Draft should be sent to the IETF SECSH working group, on this Internet-Draft should be sent to the IETF SECSH working group,
details at: http://ietf.org/html.charters/secsh-charter.html details at: http://ietf.org/html.charters/secsh-charter.html
8. References 9. Changes from previous versions
9.1. Changes between versions 3 and 2
o Added error message and language tag to SSH_AGENT_FAILURE.
o Added SSH_AGENT_EXTENSION.
o Added extension data to SSH_AGENT_VERSION_RESPONSE.
o Defined SSH_AGENT_ADD_KEY message better (previous version was
underspecified).
10. References
Normative:
[SECSH-CONNECT] Ylonen, T., et al: "Secure Shell Connection Protocol", [SECSH-CONNECT] Ylonen, T., et al: "Secure Shell Connection Protocol",
Internet-Draft, draft-ietf-secsh-connect-16.txt Internet-Draft, draft-ietf-secsh-connect-16.txt
9. Address of Authors [SECSH-TRANS] Ylonen, T., et al: "Secure Shell Transport Layer
Protocol", Internet-Draft, draft-ietf-secsh-transport-10.txt
[RFC-2279] Yergeau, F: "UTF-8, a transformation format of ISO 10646",
January 1998.
[RFC-1766] Alvestrand, H: "Tags for the Identification of Languages",
March 1995.
Informative:
11. Address of Authors
Tatu Ylonen Tatu Ylonen
SSH Communications Security Corp SSH Communications Security Corp
Fredrikinkatu 42 Fredrikinkatu 42
FIN-00100 HELSINKI FIN-00100 HELSINKI
Finland Finland
E-mail: ylo@ssh.com E-mail: ylo@ssh.com
Timo J. Rinne Timo J. Rinne
SSH Communications Security Corp SSH Communications Security Corp
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/