Annotation of src/usr.bin/ssh/RFC.nroff, Revision 1.1
1.1 ! deraadt 1: .\" -*- nroff -*-
! 2: .\"
! 3: .\" $Id: RFC.nroff,v 1.2 1999/05/04 11:58:21 bg Exp $
! 4: .\"
! 5: .pl 10.0i
! 6: .po 0
! 7: .ll 7.2i
! 8: .lt 7.2i
! 9: .nr LL 7.2i
! 10: .nr LT 7.2i
! 11: .ds LF Ylonen
! 12: .ds RF FORMFEED[Page %]
! 13: .ds CF
! 14: .ds LH Internet-Draft
! 15: .ds RH 15 November 1995
! 16: .ds CH SSH (Secure Shell) Remote Login Protocol
! 17: .na
! 18: .hy 0
! 19: .in 0
! 20: Network Working Group T. Ylonen
! 21: Internet-Draft Helsinki University of Technology
! 22: draft-ylonen-ssh-protocol-00.txt 15 November 1995
! 23: Expires: 15 May 1996
! 24:
! 25: .in 3
! 26:
! 27: .ce
! 28: The SSH (Secure Shell) Remote Login Protocol
! 29:
! 30: .ti 0
! 31: Status of This Memo
! 32:
! 33: This document is an Internet-Draft. Internet-Drafts are working
! 34: documents of the Internet Engineering Task Force (IETF), its areas,
! 35: and its working groups. Note that other groups may also distribute
! 36: working documents as Internet-Drafts.
! 37:
! 38: Internet-Drafts are draft documents valid for a maximum of six
! 39: months and may be updated, replaced, or obsoleted by other docu-
! 40: ments at any time. It is inappropriate to use Internet-Drafts as
! 41: reference material or to cite them other than as ``work in pro-
! 42: gress.''
! 43:
! 44: To learn the current status of any Internet-Draft, please check the
! 45: ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow
! 46: Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
! 47: munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
! 48: ftp.isi.edu (US West Coast).
! 49:
! 50: The distribution of this memo is unlimited.
! 51:
! 52: .ti 0
! 53: Introduction
! 54:
! 55: SSH (Secure Shell) is a program to log into another computer over a
! 56: network, to execute commands in a remote machine, and to move files
! 57: from one machine to another. It provides strong authentication and
! 58: secure communications over insecure networks. Its features include
! 59: the following:
! 60: .IP o
! 61: Closes several security holes (e.g., IP, routing, and DNS spoofing).
! 62: New authentication methods: .rhosts together with RSA [RSA] based host
! 63: authentication, and pure RSA authentication.
! 64: .IP o
! 65: All communications are automatically and transparently encrypted.
! 66: Encryption is also used to protect integrity.
! 67: .IP o
! 68: X11 connection forwarding provides secure X11 sessions.
! 69: .IP o
! 70: Arbitrary TCP/IP ports can be redirected over the encrypted channel
! 71: in both directions.
! 72: .IP o
! 73: Client RSA-authenticates the server machine in the beginning of every
! 74: connection to prevent trojan horses (by routing or DNS spoofing) and
! 75: man-in-the-middle attacks, and the server RSA-authenticates the client
! 76: machine before accepting .rhosts or /etc/hosts.equiv authentication
! 77: (to prevent DNS, routing, or IP spoofing).
! 78: .IP o
! 79: An authentication agent, running in the user's local workstation or
! 80: laptop, can be used to hold the user's RSA authentication keys.
! 81: .RT
! 82:
! 83: The goal has been to make the software as easy to use as possible for
! 84: ordinary users. The protocol has been designed to be as secure as
! 85: possible while making it possible to create implementations that
! 86: are easy to use and install. The sample implementation has a number
! 87: of convenient features that are not described in this document as they
! 88: are not relevant for the protocol.
! 89:
! 90:
! 91: .ti 0
! 92: Overview of the Protocol
! 93:
! 94: The software consists of a server program running on a server machine,
! 95: and a client program running on a client machine (plus a few auxiliary
! 96: programs). The machines are connected by an insecure IP [RFC0791]
! 97: network (that can be monitored, tampered with, and spoofed by hostile
! 98: parties).
! 99:
! 100: A connection is always initiated by the client side. The server
! 101: listens on a specific port waiting for connections. Many clients may
! 102: connect to the same server machine.
! 103:
! 104: The client and the server are connected via a TCP/IP [RFC0793] socket
! 105: that is used for bidirectional communication. Other types of
! 106: transport can be used but are currently not defined.
! 107:
! 108: When the client connects the server, the server accepts the connection
! 109: and responds by sending back its version identification string. The
! 110: client parses the server's identification, and sends its own
! 111: identification. The purpose of the identification strings is to
! 112: validate that the connection was to the correct port, declare the
! 113: protocol version number used, and to declare the software version used
! 114: on each side (for debugging purposes). The identification strings are
! 115: human-readable. If either side fails to understand or support the
! 116: other side's version, it closes the connection.
! 117:
! 118: After the protocol identification phase, both sides switch to a packet
! 119: based binary protocol. The server starts by sending its host key
! 120: (every host has an RSA key used to authenticate the host), server key
! 121: (an RSA key regenerated every hour), and other information to the
! 122: client. The client then generates a 256 bit session key, encrypts it
! 123: using both RSA keys (see below for details), and sends the encrypted
! 124: session key and selected cipher type to the server. Both sides then
! 125: turn on encryption using the selected algorithm and key. The server
! 126: sends an encrypted confirmation message to the client.
! 127:
! 128: The client then authenticates itself using any of a number of
! 129: authentication methods. The currently supported authentication
! 130: methods are .rhosts or /etc/hosts.equiv authentication (disabled by
! 131: default), the same with RSA-based host authentication, RSA
! 132: authentication, and password authentication.
! 133:
! 134: After successful authentication, the client makes a number of requests
! 135: to prepare for the session. Typical requests include allocating a
! 136: pseudo tty, starting X11 [X11] or TCP/IP port forwarding, starting
! 137: authentication agent forwarding, and executing the shell or a command.
! 138:
! 139: When a shell or command is executed, the connection enters interactive
! 140: session mode. In this mode, data is passed in both directions,
! 141: new forwarded connections may be opened, etc. The interactive session
! 142: normally terminates when the server sends the exit status of the
! 143: program to the client.
! 144:
! 145:
! 146: The protocol makes several reservations for future extensibility.
! 147: First of all, the initial protocol identification messages include the
! 148: protocol version number. Second, the first packet by both sides
! 149: includes a protocol flags field, which can be used to agree on
! 150: extensions in a compatible manner. Third, the authentication and
! 151: session preparation phases work so that the client sends requests to
! 152: the server, and the server responds with success or failure. If the
! 153: client sends a request that the server does not support, the server
! 154: simply returns failure for it. This permits compatible addition of
! 155: new authentication methods and preparation operations. The
! 156: interactive session phase, on the other hand, works asynchronously and
! 157: does not permit the use of any extensions (because there is no easy
! 158: and reliable way to signal rejection to the other side and problems
! 159: would be hard to debug). Any compatible extensions to this phase must
! 160: be agreed upon during any of the earlier phases.
! 161:
! 162: .ti 0
! 163: The Binary Packet Protocol
! 164:
! 165: After the protocol identification strings, both sides only send
! 166: specially formatted packets. The packet layout is as follows:
! 167: .IP o
! 168: Packet length: 32 bit unsigned integer, coded as four 8-bit bytes, msb
! 169: first. Gives the length of the packet, not including the length field
! 170: and padding. The maximum length of a packet (not including the length
! 171: field and padding) is 262144 bytes.
! 172: .IP o
! 173: Padding: 1-8 bytes of random data (or zeroes if not encrypting). The
! 174: amount of padding is (8 - (length % 8)) bytes (where % stands for the
! 175: modulo operator). The rationale for always having some random padding
! 176: at the beginning of each packet is to make known plaintext attacks
! 177: more difficult.
! 178: .IP o
! 179: Packet type: 8-bit unsigned byte. The value 255 is reserved for
! 180: future extension.
! 181: .IP o
! 182: Data: binary data bytes, depending on the packet type. The number of
! 183: data bytes is the "length" field minus 5.
! 184: .IP o
! 185: Check bytes: 32-bit crc, four 8-bit bytes, msb first. The crc is the
! 186: Cyclic Redundancy Check, with the polynomial 0xedb88320, of the
! 187: Padding, Packet type, and Data fields. The crc is computed before
! 188: any encryption.
! 189: .RT
! 190:
! 191: The packet, except for the length field, may be encrypted using any of
! 192: a number of algorithms. The length of the encrypted part (Padding +
! 193: Type + Data + Check) is always a multiple of 8 bytes. Typically the
! 194: cipher is used in a chained mode, with all packets chained together as
! 195: if it was a single data stream (the length field is never included in
! 196: the encryption process). Details of encryption are described below.
! 197:
! 198: When the session starts, encryption is turned off. Encryption is
! 199: enabled after the client has sent the session key. The encryption
! 200: algorithm to use is selected by the client.
! 201:
! 202:
! 203: .ti 0
! 204: Packet Compression
! 205:
! 206: If compression is supported (it is an optional feature, see
! 207: SSH_CMSG_REQUEST_COMPRESSION below), the packet type and data fields
! 208: of the packet are compressed using the gzip deflate algorithm [GZIP].
! 209: If compression is in effect, the packet length field indicates the
! 210: length of the compressed data, plus 4 for the crc. The amount of
! 211: padding is computed from the compressed data, so that the amount of
! 212: data to be encrypted becomes a multiple of 8 bytes.
! 213:
! 214: When compressing, the packets (type + data portions) in each direction
! 215: are compressed as if they formed a continuous data stream, with only the
! 216: current compression block flushed between packets. This corresponds
! 217: to the GNU ZLIB library Z_PARTIAL_FLUSH option. The compression
! 218: dictionary is not flushed between packets. The two directions are
! 219: compressed independently of each other.
! 220:
! 221:
! 222: .ti 0
! 223: Packet Encryption
! 224:
! 225: The protocol supports several encryption methods. During session
! 226: initialization, the server sends a bitmask of all encryption methods
! 227: that it supports, and the client selects one of these methods. The
! 228: client also generates a 256-bit random session key (32 8-bit bytes) and
! 229: sends it to the server.
! 230:
! 231: The encryption methods supported by the current implementation, and
! 232: their codes are:
! 233: .TS
! 234: center;
! 235: l r l.
! 236: SSH_CIPHER_NONE 0 No encryption
! 237: SSH_CIPHER_IDEA 1 IDEA in CFB mode
! 238: SSH_CIPHER_DES 2 DES in CBC mode
! 239: SSH_CIPHER_3DES 3 Triple-DES in CBC mode
! 240: SSH_CIPHER_TSS 4 An experimental stream cipher
! 241: SSH_CIPHER_RC4 5 RC4
! 242: .TE
! 243:
! 244: All implementations are required to support SSH_CIPHER_DES and
! 245: SSH_CIPHER_3DES. Supporting SSH_CIPHER_IDEA, SSH_CIPHER_RC4, and
! 246: SSH_CIPHER_NONE is recommended. Support for SSH_CIPHER_TSS is
! 247: optional (and it is not described in this document). Other ciphers
! 248: may be added at a later time; support for them is optional.
! 249:
! 250: For encryption, the encrypted portion of the packet is considered a
! 251: linear byte stream. The length of the stream is always a multiple of
! 252: 8. The encrypted portions of consecutive packets (in the same
! 253: direction) are encrypted as if they were a continuous buffer (that is,
! 254: any initialization vectors are passed from the previous packet to the
! 255: next packet). Data in each direction is encrypted independently.
! 256: .IP SSH_CIPHER_DES
! 257: The key is taken from the first 8 bytes of the session key. The least
! 258: significant bit of each byte is ignored. This results in 56 bits of
! 259: key data. DES [DES] is used in CBC mode. The iv (initialization vector) is
! 260: initialized to all zeroes.
! 261: .IP SSH_CIPHER_3DES
! 262: The variant of triple-DES used here works as follows: there are three
! 263: independent DES-CBC ciphers, with independent initialization vectors.
! 264: The data (the whole encrypted data stream) is first encrypted with the
! 265: first cipher, then decrypted with the second cipher, and finally
! 266: encrypted with the third cipher. All these operations are performed
! 267: in CBC mode.
! 268:
! 269: The key for the first cipher is taken from the first 8 bytes of the
! 270: session key; the key for the next cipher from the next 8 bytes, and
! 271: the key for the third cipher from the following 8 bytes. All three
! 272: initialization vectors are initialized to zero.
! 273:
! 274: (Note: the variant of 3DES used here differs from some other
! 275: descriptions.)
! 276: .IP SSH_CIPHER_IDEA
! 277: The key is taken from the first 16 bytes of the session key. IDEA
! 278: [IDEA] is used in CFB mode. The initialization vector is initialized
! 279: to all zeroes.
! 280: .IP SSH_CIPHER_TSS
! 281: All 32 bytes of the session key are used as the key.
! 282:
! 283: There is no reference available for the TSS algorithm; it is currently
! 284: only documented in the sample implementation source code. The
! 285: security of this cipher is unknown (but it is quite fast). The cipher
! 286: is basically a stream cipher that uses MD5 as a random number
! 287: generator and takes feedback from the data.
! 288: .IP SSH_CIPHER_RC4
! 289: The first 16 bytes of the session key are used as the key for the
! 290: server to client direction. The remaining 16 bytes are used as the
! 291: key for the client to server direction. This gives independent
! 292: 128-bit keys for each direction.
! 293:
! 294: This algorithm is the alleged RC4 cipher posted to the Usenet in 1995.
! 295: It is widely believed to be equivalent with the original RSADSI RC4
! 296: cipher. This is a very fast algorithm.
! 297: .RT
! 298:
! 299:
! 300: .ti 0
! 301: Data Type Encodings
! 302:
! 303: The Data field of each packet contains data encoded as described in
! 304: this section. There may be several data items; each item is coded as
! 305: described here, and their representations are concatenated together
! 306: (without any alignment or padding).
! 307:
! 308: Each data type is stored as follows:
! 309: .IP "8-bit byte"
! 310: The byte is stored directly as a single byte.
! 311: .IP "32-bit unsigned integer"
! 312: Stored in 4 bytes, msb first.
! 313: .IP "Arbitrary length binary string"
! 314: First 4 bytes are the length of the string, msb first (not including
! 315: the length itself). The following "length" bytes are the string
! 316: value. There are no terminating null characters.
! 317: .IP "Multiple-precision integer"
! 318: First 2 bytes are the number of bits in the integer, msb first (for
! 319: example, the value 0x00012345 would have 17 bits). The value zero has
! 320: zero bits. It is permissible that the number of bits be larger than the
! 321: real number of bits.
! 322:
! 323: The number of bits is followed by (bits + 7) / 8 bytes of binary data,
! 324: msb first, giving the value of the integer.
! 325: .RT
! 326:
! 327:
! 328: .ti 0
! 329: TCP/IP Port Number and Other Options
! 330:
! 331: The server listens for connections on TCP/IP port 22.
! 332:
! 333: The client may connect the server from any port. However, if the
! 334: client wishes to use any form of .rhosts or /etc/hosts.equiv
! 335: authentication, it must connect from a privileged port (less than
! 336: 1024).
! 337:
! 338: For the IP Type of Service field [RFC0791], it is recommended that
! 339: interactive sessions (those having a user terminal or forwarding X11
! 340: connections) use the IPTOS_LOWDELAY, and non-interactive connections
! 341: use IPTOS_THROUGHPUT.
! 342:
! 343: It is recommended that keepalives are used, because otherwise programs
! 344: on the server may never notice if the other end of the connection is
! 345: rebooted.
! 346:
! 347:
! 348: .ti 0
! 349: Protocol Version Identification
! 350:
! 351: After the socket is opened, the server sends an identification string,
! 352: which is of the form
! 353: "SSH-<protocolmajor>.<protocolminor>-<version>\\n", where
! 354: <protocolmajor> and <protocolminor> are integers and specify the
! 355: protocol version number (not software distribution version).
! 356: <version> is server side software version string (max 40 characters);
! 357: it is not interpreted by the remote side but may be useful for
! 358: debugging.
! 359:
! 360: The client parses the server's string, and sends a corresponding
! 361: string with its own information in response. If the server has lower
! 362: version number, and the client contains special code to emulate it,
! 363: the client responds with the lower number; otherwise it responds with
! 364: its own number. The server then compares the version number the
! 365: client sent with its own, and determines whether they can work
! 366: together. The server either disconnects, or sends the first packet
! 367: using the binary packet protocol and both sides start working
! 368: according to the lower of the protocol versions.
! 369:
! 370: By convention, changes which keep the protocol compatible with
! 371: previous versions keep the same major protocol version; changes that
! 372: are not compatible increment the major version (which will hopefully
! 373: never happen). The version described in this document is 1.3.
! 374:
! 375: The client will
! 376:
! 377: .ti 0
! 378: Key Exchange and Server Host Authentication
! 379:
! 380: The first message sent by the server using the packet protocol is
! 381: SSH_SMSG_PUBLIC_KEY. It declares the server's host key, server public
! 382: key, supported ciphers, supported authentication methods, and flags
! 383: for protocol extensions. It also contains a 64-bit random number
! 384: (cookie) that must be returned in the client's reply (to make IP
! 385: spoofing more difficult). No encryption is used for this message.
! 386:
! 387: Both sides compute a session id as follows. The modulus of the server
! 388: key is interpreted as a byte string (without explicit length field,
! 389: with minimum length able to hold the whole value), most significant
! 390: byte first. This string is concatenated with the server host key
! 391: interpreted the same way. Additionally, the cookie is concatenated
! 392: with this. Both sides compute MD5 of the resulting string. The
! 393: resulting 16 bytes (128 bits) are stored by both parties and are
! 394: called the session id.
! 395:
! 396: The client responds with a SSH_CMSG_SESSION_KEY message, which
! 397: contains the selected cipher type, a copy of the 64-bit cookie sent by
! 398: the server, client's protocol flags, and a session key encrypted
! 399: with both the server's host key and server key. No encryption is used
! 400: for this message.
! 401:
! 402: The session key is 32 8-bit bytes (a total of 256 random bits
! 403: generated by the client). The client first xors the 16 bytes of the
! 404: session id with the first 16 bytes of the session key. The resulting
! 405: string is then encrypted using the smaller key (one with smaller
! 406: modulus), and the result is then encrypted using the other key. The
! 407: number of bits in the public modulus of the two keys must differ by at
! 408: least 128 bits.
! 409:
! 410: At each encryption step, a multiple-precision integer is constructed
! 411: from the data to be encrypted as follows (the integer is here
! 412: interpreted as a sequence of bytes, msb first; the number of bytes is
! 413: the number of bytes needed to represent the modulus).
! 414:
! 415: The most significant byte (which is only partial as the value must be
! 416: less than the public modulus, which is never a power of two) is zero.
! 417:
! 418: The next byte contains the value 2 (which stands for public-key
! 419: encrypted data in the PKCS standard [PKCS#1]). Then, there are
! 420: non-zero random bytes to fill any unused space, a zero byte, and the
! 421: data to be encrypted in the least significant bytes, the last byte of
! 422: the data in the least significant byte.
! 423:
! 424: This algorithm is used twice. First, it is used to encrypt the 32
! 425: random bytes generated by the client to be used as the session key
! 426: (xored by the session id). This value is converted to an integer as
! 427: described above, and encrypted with RSA using the key with the smaller
! 428: modulus. The resulting integer is converted to a byte stream, msb
! 429: first. This byte stream is padded and encrypted identically using the
! 430: key with the larger modulus.
! 431:
! 432: After the client has sent the session key, it starts to use the
! 433: selected algorithm and key for decrypting any received packets, and
! 434: for encrypting any sent packets. Separate ciphers are used for
! 435: different directions (that is, both directions have separate
! 436: initialization vectors or other state for the ciphers).
! 437:
! 438: When the server has received the session key message, and has turned
! 439: on encryption, it sends a SSH_SMSG_SUCCESS message to the client.
! 440:
! 441: The recommended size of the host key is 1024 bits, and 768 bits for
! 442: the server key. The minimum size is 512 bits for the smaller key.
! 443:
! 444:
! 445: .ti 0
! 446: Declaring the User Name
! 447:
! 448: The client then sends a SSH_CMSG_USER message to the server. This
! 449: message specifies the user name to log in as.
! 450:
! 451: The server validates that such a user exists, checks whether
! 452: authentication is needed, and responds with either SSH_SMSG_SUCCESS or
! 453: SSH_SMSG_FAILURE. SSH_SMSG_SUCCESS indicates that no authentication
! 454: is needed for this user (no password), and authentication phase has
! 455: now been completed. SSH_SMSG_FAILURE indicates that authentication is
! 456: needed (or the user does not exist).
! 457:
! 458: If the user does not exist, it is recommended that this returns
! 459: failure, but the server keeps reading messages from the client, and
! 460: responds to any messages (except SSH_MSG_DISCONNECT, SSH_MSG_IGNORE,
! 461: and SSH_MSG_DEBUG) with SSH_SMSG_FAILURE. This way the client cannot
! 462: be certain whether the user exists.
! 463:
! 464:
! 465: .ti 0
! 466: Authentication Phase
! 467:
! 468: Provided the server didn't immediately accept the login, an
! 469: authentication exchange begins. The client sends messages to the
! 470: server requesting different types of authentication in arbitrary order as
! 471: many times as desired (however, the server may close the connection
! 472: after a timeout). The server always responds with SSH_SMSG_SUCCESS if
! 473: it has accepted the authentication, and with SSH_SMSG_FAILURE if it has
! 474: denied authentication with the requested method or it does not
! 475: recognize the message. Some authentication methods cause an exchange
! 476: of further messages before the final result is sent. The
! 477: authentication phase ends when the server responds with success.
! 478:
! 479: The recommended value for the authentication timeout (timeout before
! 480: disconnecting if no successful authentication has been made) is 5
! 481: minutes.
! 482:
! 483: The following authentication methods are currently supported:
! 484: .TS
! 485: center;
! 486: l r l.
! 487: SSH_AUTH_RHOSTS 1 .rhosts or /etc/hosts.equiv
! 488: SSH_AUTH_RSA 2 pure RSA authentication
! 489: SSH_AUTH_PASSWORD 3 password authentication
! 490: SSH_AUTH_RHOSTS_RSA 4 .rhosts with RSA host authentication
! 491: .TE
! 492: .IP SSH_AUTH_RHOSTS
! 493:
! 494: This is the authentication method used by rlogin and rsh [RFC1282].
! 495:
! 496: The client sends SSH_CMSG_AUTH_RHOSTS with the client-side user name
! 497: as an argument.
! 498:
! 499: The server checks whether to permit authentication. On UNIX systems,
! 500: this is usually done by checking /etc/hosts.equiv, and .rhosts in the
! 501: user's home directory. The connection must come from a privileged
! 502: port.
! 503:
! 504: It is recommended that the server checks that there are no IP options
! 505: (such as source routing) specified for the socket before accepting
! 506: this type of authentication. The client host name should be
! 507: reverse-mapped and then forward mapped to ensure that it has the
! 508: proper IP-address.
! 509:
! 510: This authentication method trusts the remote host (root on the remote
! 511: host can pretend to be any other user on that host), the name
! 512: services, and partially the network: anyone who can see packets coming
! 513: out from the server machine can do IP-spoofing and pretend to be any
! 514: machine; however, the protocol prevents blind IP-spoofing (which used
! 515: to be possible with rlogin).
! 516:
! 517: Many sites probably want to disable this authentication method because
! 518: of the fundamental insecurity of conventional .rhosts or
! 519: /etc/hosts.equiv authentication when faced with spoofing. It is
! 520: recommended that this method not be supported by the server by
! 521: default.
! 522: .IP SSH_AUTH_RHOSTS_RSA
! 523:
! 524: In addition to conventional .rhosts and hosts.equiv authentication,
! 525: this method additionally requires that the client host be
! 526: authenticated using RSA.
! 527:
! 528: The client sends SSH_CMSG_AUTH_RHOSTS_RSA specifying the client-side
! 529: user name, and the public host key of the client host.
! 530:
! 531: The server first checks if normal .rhosts or /etc/hosts.equiv
! 532: authentication would be accepted, and if not, responds with
! 533: SSH_SMSG_FAILURE. Otherwise, it checks whether it knows the host key
! 534: for the client machine (using the same name for the host that was used
! 535: for checking the .rhosts and /etc/hosts.equiv files). If it does not
! 536: know the RSA key for the client, access is denied and SSH_SMSG_FAILURE
! 537: is sent.
! 538:
! 539: If the server knows the host key of the client machine, it verifies
! 540: that the given host key matches that known for the client. If not,
! 541: access is denied and SSH_SMSG_FAILURE is sent.
! 542:
! 543: The server then sends a SSH_SMSG_AUTH_RSA_CHALLENGE message containing
! 544: an encrypted challenge for the client. The challenge is 32 8-bit
! 545: random bytes (256 bits). When encrypted, the highest (partial) byte
! 546: is left as zero, the next byte contains the value 2, the following are
! 547: non-zero random bytes, followed by a zero byte, and the challenge put
! 548: in the remaining bytes. This is then encrypted using RSA with the
! 549: client host's public key. (The padding and encryption algorithm is
! 550: the same as that used for the session key.)
! 551:
! 552: The client decrypts the challenge using its private host key,
! 553: concatenates this with the session id, and computes an MD5 checksum
! 554: of the resulting 48 bytes. The MD5 output is returned as 16 bytes in
! 555: a SSH_CMSG_AUTH_RSA_RESPONSE message. (MD5 is used to deter chosen
! 556: plaintext attacks against RSA; the session id binds it to a specific
! 557: session).
! 558:
! 559: The server verifies that the MD5 of the decrypted challenge returned by
! 560: the client matches that of the original value, and sends SSH_SMSG_SUCCESS if
! 561: so. Otherwise it sends SSH_SMSG_FAILURE and refuses the
! 562: authentication attempt.
! 563:
! 564: This authentication method trusts the client side machine in that root
! 565: on that machine can pretend to be any user on that machine.
! 566: Additionally, it trusts the client host key. The name and/or IP
! 567: address of the client host is only used to select the public host key.
! 568: The same host name is used when scanning .rhosts or /etc/hosts.equiv
! 569: and when selecting the host key. It would in principle be possible to
! 570: eliminate the host name entirely and substitute it directly by the
! 571: host key. IP and/or DNS [RFC1034] spoofing can only be used
! 572: to pretend to be a host for which the attacker has the private host
! 573: key.
! 574: .IP SSH_AUTH_RSA
! 575:
! 576: The idea behind RSA authentication is that the server recognizes the
! 577: public key offered by the client, generates a random challenge, and
! 578: encrypts the challenge with the public key. The client must then
! 579: prove that it has the corresponding private key by decrypting the
! 580: challenge.
! 581:
! 582: The client sends SSH_CMSG_AUTH_RSA with public key modulus (n) as an
! 583: argument.
! 584:
! 585: The server may respond immediately with SSH_SMSG_FAILURE if it does
! 586: not permit authentication with this key. Otherwise it generates a
! 587: challenge, encrypts it using the user's public key (stored on the
! 588: server and identified using the modulus), and sends
! 589: SSH_SMSG_AUTH_RSA_CHALLENGE with the challenge (mp-int) as an
! 590: argument.
! 591:
! 592: The challenge is 32 8-bit random bytes (256 bits). When encrypted,
! 593: the highest (partial) byte is left as zero, the next byte contains the
! 594: value 2, the following are non-zero random bytes, followed by a zero
! 595: byte, and the challenge put in the remaining bytes. This is then
! 596: encrypted with the public key. (The padding and encryption algorithm
! 597: is the same as that used for the session key.)
! 598:
! 599: The client decrypts the challenge using its private key, concatenates
! 600: it with the session id, and computes an MD5 checksum of the resulting
! 601: 48 bytes. The MD5 output is returned as 16 bytes in a
! 602: SSH_CMSG_AUTH_RSA_RESPONSE message. (Note that the MD5 is necessary
! 603: to avoid chosen plaintext attacks against RSA; the session id binds it
! 604: to a specific session.)
! 605:
! 606: The server verifies that the MD5 of the decrypted challenge returned
! 607: by the client matches that of the original value, and sends
! 608: SSH_SMSG_SUCCESS if so. Otherwise it sends SSH_SMSG_FAILURE and
! 609: refuses the authentication attempt.
! 610:
! 611: This authentication method does not trust the remote host, the
! 612: network, name services, or anything else. Authentication is based
! 613: solely on the possession of the private identification keys. Anyone
! 614: in possession of the private keys can log in, but nobody else.
! 615:
! 616: The server may have additional requirements for a successful
! 617: authentiation. For example, to limit damage due to a compromised RSA
! 618: key, a server might restrict access to a limited set of hosts.
! 619: .IP SSH_AUTH_PASSWORD
! 620:
! 621: The client sends a SSH_CMSG_AUTH_PASSWORD message with the plain text
! 622: password. (Note that even though the password is plain text inside
! 623: the message, it is normally encrypted by the packet mechanism.)
! 624:
! 625: The server verifies the password, and sends SSH_SMSG_SUCCESS if
! 626: authentication was accepted and SSH_SMSG_FAILURE otherwise.
! 627:
! 628: Note that the password is read from the user by the client; the user
! 629: never interacts with a login program.
! 630:
! 631: This authentication method does not trust the remote host, the
! 632: network, name services or anything else. Authentication is based
! 633: solely on the possession of the password. Anyone in possession of the
! 634: password can log in, but nobody else.
! 635: .RT
! 636:
! 637: .ti 0
! 638: Preparatory Operations
! 639:
! 640: After successful authentication, the server waits for a request from
! 641: the client, processes the request, and responds with SSH_SMSG_SUCCESS
! 642: whenever a request has been successfully processed. If it receives a
! 643: message that it does not recognize or it fails to honor a request, it
! 644: returns SSH_SMSG_FAILURE. It is expected that new message types might
! 645: be added to this phase in future.
! 646:
! 647: The following messages are currently defined for this phase.
! 648: .IP SSH_CMSG_REQUEST_COMPRESSION
! 649: Requests that compression be enabled for this session. A
! 650: gzip-compatible compression level (1-9) is passed as an argument.
! 651: .IP SSH_CMSG_REQUEST_PTY
! 652: Requests that a pseudo terminal device be allocated for this session.
! 653: The user terminal type and terminal modes are supplied as arguments.
! 654: .IP SSH_CMSG_X11_REQUEST_FORWARDING
! 655: Requests forwarding of X11 connections from the remote machine to the
! 656: local machine over the secure channel. Causes an internet-domain
! 657: socket to be allocated and the DISPLAY variable to be set on the server.
! 658: X11 authentication data is automatically passed to the server, and the
! 659: client may implement spoofing of authentication data for added
! 660: security. The authentication data is passed as arguments.
! 661: .IP SSH_CMSG_PORT_FORWARD_REQUEST
! 662: Requests forwarding of a TCP/IP port on the server host over the
! 663: secure channel. What happens is that whenever a connection is made to
! 664: the port on the server, a connection will be made from the client end
! 665: to the specified host/port. Any user can forward unprivileged ports;
! 666: only the root can forward privileged ports (as determined by
! 667: authentication done earlier).
! 668: .IP SSH_CMSG_AGENT_REQUEST_FORWARDING
! 669: Requests forwarding of the connection to the authentication agent.
! 670: .IP SSH_CMSG_EXEC_SHELL
! 671: Starts a shell (command interpreter) for the user, and moves into
! 672: interactive session mode.
! 673: .IP SSH_CMSG_EXEC_CMD
! 674: Executes the given command (actually "<shell> -c <command>" or
! 675: equivalent) for the user, and moves into interactive session mode.
! 676: .RT
! 677:
! 678:
! 679: .ti 0
! 680: Interactive Session and Exchange of Data
! 681:
! 682: During the interactive session, any data written by the shell or
! 683: command running on the server machine is forwarded to stdin or
! 684: stderr on the client machine, and any input available from stdin on
! 685: the client machine is forwarded to the program on the server machine.
! 686:
! 687: All exchange is asynchronous; either side can send at any time, and
! 688: there are no acknowledgements (TCP/IP already provides reliable
! 689: transport, and the packet protocol protects against tampering or IP
! 690: spoofing).
! 691:
! 692: When the client receives EOF from its standard input, it will send
! 693: SSH_CMSG_EOF; however, this in no way terminates the exchange. The
! 694: exchange terminates and interactive mode is left when the server sends
! 695: SSH_SMSG_EXITSTATUS to indicate that the client program has
! 696: terminated. Alternatively, either side may disconnect at any time by
! 697: sending SSH_MSG_DISCONNECT or closing the connection.
! 698:
! 699: The server may send any of the following messages:
! 700: .IP SSH_SMSG_STDOUT_DATA
! 701: Data written to stdout by the program running on the server. The data
! 702: is passed as a string argument. The client writes this data to
! 703: stdout.
! 704: .IP SSH_SMSG_STDERR_DATA
! 705: Data written to stderr by the program running on the server. The data
! 706: is passed as a string argument. The client writes this data to
! 707: stderr. (Note that if the program is running on a tty, it is not
! 708: possible to separate stdout and stderr data, and all data will be sent
! 709: as stdout data.)
! 710: .IP SSH_SMSG_EXITSTATUS
! 711: Indicates that the shell or command has exited. Exit status is passed
! 712: as an integer argument. This message causes termination of the
! 713: interactive session.
! 714: .IP SSH_SMSG_AGENT_OPEN
! 715: Indicates that someone on the server side is requesting a connection
! 716: to the authentication agent. The server-side channel number is passed
! 717: as an argument. The client must respond with either
! 718: SSH_CHANNEL_OPEN_CONFIRMATION or SSH_CHANNEL_OPEN_FAILURE.
! 719: .IP SSH_SMSG_X11_OPEN
! 720: Indicates that a connection has been made to the X11 socket on the
! 721: server side and should be forwarded to the real X server. An integer
! 722: argument indicates the channel number allocated for this connection on
! 723: the server side. The client should send back either
! 724: SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE with
! 725: the same server side channel number.
! 726: .IP SSH_MSG_PORT_OPEN
! 727: Indicates that a connection has been made to a port on the server side
! 728: for which forwarding has been requested. Arguments are server side
! 729: channel number, host name to connect to, and port to connect to. The
! 730: client should send back either
! 731: SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE with
! 732: the same server side channel number.
! 733: .IP SSH_MSG_CHANNEL_OPEN_CONFIRMATION
! 734: This is sent by the server to indicate that it has opened a connection
! 735: as requested in a previous message. The first argument indicates the
! 736: client side channel number, and the second argument is the channel number
! 737: that the server has allocated for this connection.
! 738: .IP SSH_MSG_CHANNEL_OPEN_FAILURE
! 739: This is sent by the server to indicate that it failed to open a
! 740: connection as requested in a previous message. The client-side
! 741: channel number is passed as an argument. The client will close the
! 742: descriptor associated with the channel and free the channel.
! 743: .IP SSH_MSG_CHANNEL_DATA
! 744: This packet contains data for a channel from the server. The first
! 745: argument is the client-side channel number, and the second argument (a
! 746: string) is the data.
! 747: .IP SSH_MSG_CHANNEL_CLOSE
! 748: This is sent by the server to indicate that whoever was in the other
! 749: end of the channel has closed it. The argument is the client side channel
! 750: number. The client will let all buffered data in the channel to
! 751: drain, and when ready, will close the socket, free the channel, and
! 752: send the server a SSH_MSG_CHANNEL_CLOSE_CONFIRMATION message for the
! 753: channel.
! 754: .IP SSH_MSG_CHANNEL_CLOSE_CONFIRMATION
! 755: This is send by the server to indicate that a channel previously
! 756: closed by the client has now been closed on the server side as well.
! 757: The argument indicates the client channel number. The client frees
! 758: the channel.
! 759: .RT
! 760:
! 761: The client may send any of the following messages:
! 762: .IP SSH_CMSG_STDIN_DATA
! 763: This is data to be sent as input to the program running on the server.
! 764: The data is passed as a string.
! 765: .IP SSH_CMSG_EOF
! 766: Indicates that the client has encountered EOF while reading standard
! 767: input. The server will allow any buffered input data to drain, and
! 768: will then close the input to the program.
! 769: .IP SSH_CMSG_WINDOW_SIZE
! 770: Indicates that window size on the client has been changed. The server
! 771: updates the window size of the tty and causes SIGWINCH to be sent to
! 772: the program. The new window size is passed as four integer arguments:
! 773: row, col, xpixel, ypixel.
! 774: .IP SSH_MSG_PORT_OPEN
! 775: Indicates that a connection has been made to a port on the client side
! 776: for which forwarding has been requested. Arguments are client side
! 777: channel number, host name to connect to, and port to connect to. The
! 778: server should send back either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
! 779: SSH_MSG_CHANNEL_OPEN_FAILURE with the same client side channel number.
! 780: .IP SSH_MSG_CHANNEL_OPEN_CONFIRMATION
! 781: This is sent by the client to indicate that it has opened a connection
! 782: as requested in a previous message. The first argument indicates the
! 783: server side channel number, and the second argument is the channel
! 784: number that the client has allocated for this connection.
! 785: .IP SSH_MSG_CHANNEL_OPEN_FAILURE
! 786: This is sent by the client to indicate that it failed to open a
! 787: connection as requested in a previous message. The server side
! 788: channel number is passed as an argument. The server will close the
! 789: descriptor associated with the channel and free the channel.
! 790: .IP SSH_MSG_CHANNEL_DATA
! 791: This packet contains data for a channel from the client. The first
! 792: argument is the server side channel number, and the second argument (a
! 793: string) is the data.
! 794: .IP SSH_MSG_CHANNEL_CLOSE
! 795: This is sent by the client to indicate that whoever was in the other
! 796: end of the channel has closed it. The argument is the server channel
! 797: number. The server will allow buffered data to drain, and when ready,
! 798: will close the socket, free the channel, and send the client a
! 799: SSH_MSG_CHANNEL_CLOSE_CONFIRMATION message for the channel.
! 800: .IP SSH_MSG_CHANNEL_CLOSE_CONFIRMATION
! 801: This is send by the client to indicate that a channel previously
! 802: closed by the server has now been closed on the client side as well.
! 803: The argument indicates the server channel number. The server frees
! 804: the channel.
! 805: .RT
! 806:
! 807: Any unsupported messages during interactive mode cause the connection
! 808: to be terminated with SSH_MSG_DISCONNECT and an error message.
! 809: Compatible protocol upgrades should agree about any extensions during
! 810: the preparation phase or earlier.
! 811:
! 812:
! 813: .ti 0
! 814: Termination of the Connection
! 815:
! 816: Normal termination of the connection is always initiated by the server
! 817: by sending SSH_SMSG_EXITSTATUS after the program has exited. The
! 818: client responds to this message by sending SSH_CMSG_EXIT_CONFIRMATION
! 819: and closes the socket; the server then closes the socket. There are
! 820: two purposes for the confirmation: some systems may lose previously
! 821: sent data when the socket is closed, and closing the client side first
! 822: causes any TCP/IP TIME_WAIT [RFC0793] waits to occur on the client side, not
! 823: consuming server resources.
! 824:
! 825: If the program terminates due to a signal, the server will send
! 826: SSH_MSG_DISCONNECT with an appropriate message. If the connection is
! 827: closed, all file descriptors to the program will be closed and the
! 828: server will exit. If the program runs on a tty, the kernel sends it
! 829: the SIGHUP signal when the pty master side is closed.
! 830:
! 831: .ti 0
! 832: Protocol Flags
! 833:
! 834: Both the server and the client pass 32 bits of protocol flags to the
! 835: other side. The flags are intended for compatible protocol extension;
! 836: the server first announces which added capabilities it supports, and
! 837: the client then sends the capabilities that it supports.
! 838:
! 839: The following flags are currently defined (the values are bit masks):
! 840: .IP "1 SSH_PROTOFLAG_SCREEN_NUMBER"
! 841: This flag can only be sent by the client. It indicates that the X11
! 842: forwarding requests it sends will include the screen number.
! 843: .IP "2 SSH_PROTOFLAG_HOST_IN_FWD_OPEN"
! 844: If both sides specify this flag, SSH_SMSG_X11_OPEN and
! 845: SSH_MSG_PORT_OPEN messages will contain an additional field containing
! 846: a description of the host at the other end of the connection.
! 847: .RT
! 848:
! 849: .ti 0
! 850: Detailed Description of Packet Types and Formats
! 851:
! 852: The supported packet types and the corresponding message numbers are
! 853: given in the following table. Messages with _MSG_ in their name may
! 854: be sent by either side. Messages with _CMSG_ are only sent by the
! 855: client, and messages with _SMSG_ only by the server.
! 856:
! 857: A packet may contain additional data after the arguments specified
! 858: below. Any such data should be ignored by the receiver. However, it
! 859: is recommended that no such data be stored without good reason. (This
! 860: helps build compatible extensions.)
! 861: .IP "0 SSH_MSG_NONE"
! 862: This code is reserved. This message type is never sent.
! 863: .IP "1 SSH_MSG_DISCONNECT"
! 864: .TS
! 865: ;
! 866: l l.
! 867: string Cause of disconnection
! 868: .TE
! 869: This message may be sent by either party at any time. It causes the
! 870: immediate disconnection of the connection. The message is intended to
! 871: be displayed to a human, and describes the reason for disconnection.
! 872: .IP "2 SSH_SMSG_PUBLIC_KEY"
! 873: .TS
! 874: ;
! 875: l l.
! 876: 8 bytes anti_spoofing_cookie
! 877: 32-bit int server_key_bits
! 878: mp-int server_key_public_exponent
! 879: mp-int server_key_public_modulus
! 880: 32-bit int host_key_bits
! 881: mp-int host_key_public_exponent
! 882: mp-int host_key_public_modulus
! 883: 32-bit int protocol_flags
! 884: 32-bit int supported_ciphers_mask
! 885: 32-bit int supported_authentications_mask
! 886: .TE
! 887: Sent as the first message by the server. This message gives the
! 888: server's host key, server key, protocol flags (intended for compatible
! 889: protocol extension), supported_ciphers_mask (which is the
! 890: bitwise or of (1 << cipher_number), where << is the left shift
! 891: operator, for all supported ciphers), and
! 892: supported_authentications_mask (which is the bitwise or of (1 <<
! 893: authentication_type) for all supported authentication types). The
! 894: anti_spoofing_cookie is 64 random bytes, and must be sent back
! 895: verbatim by the client in its reply. It is used to make IP-spoofing
! 896: more difficult (encryption and host keys are the real defense against
! 897: spoofing).
! 898: .IP "3 SSH_CMSG_SESSION_KEY"
! 899: .TS
! 900: ;
! 901: l l.
! 902: 1 byte cipher_type (must be one of the supported values)
! 903: 8 bytes anti_spoofing_cookie (must match data sent by the server)
! 904: mp-int double-encrypted session key
! 905: 32-bit int protocol_flags
! 906: .TE
! 907: Sent by the client as the first message in the session. Selects the
! 908: cipher to use, and sends the encrypted session key to the server. The
! 909: anti_spoofing_cookie must be the same bytes that were sent by the
! 910: server. Protocol_flags is intended for negotiating compatible
! 911: protocol extensions.
! 912: .IP "4 SSH_CMSG_USER"
! 913: .TS
! 914: ;
! 915: l l.
! 916: string user login name on server
! 917: .TE
! 918: Sent by the client to begin authentication. Specifies the user name
! 919: on the server to log in as. The server responds with SSH_SMSG_SUCCESS
! 920: if no authentication is needed for this user, or SSH_SMSG_FAILURE if
! 921: authentication is needed (or the user does not exist). [Note to the
! 922: implementator: the user name is of arbitrary size. The implementation
! 923: must be careful not to overflow internal buffers.]
! 924: .IP "5 SSH_CMSG_AUTH_RHOSTS"
! 925: .TS
! 926: ;
! 927: l l.
! 928: string client-side user name
! 929: .TE
! 930: Requests authentication using /etc/hosts.equiv and .rhosts (or
! 931: equivalent mechanisms). This authentication method is normally
! 932: disabled in the server because it is not secure (but this is the
! 933: method used by rsh and rlogin). The server responds with
! 934: SSH_SMSG_SUCCESS if authentication was successful, and
! 935: SSH_SMSG_FAILURE if access was not granted. The server should check
! 936: that the client side port number is less than 1024 (a privileged
! 937: port), and immediately reject authentication if it is not. Supporting
! 938: this authentication method is optional. This method should normally
! 939: not be enabled in the server because it is not safe. (However, not
! 940: enabling this only helps if rlogind and rshd are disabled.)
! 941: .IP "6 SSH_CMSG_AUTH_RSA"
! 942: .TS
! 943: ;
! 944: l l.
! 945: mp-int identity_public_modulus
! 946: .TE
! 947: Requests authentication using pure RSA authentication. The server
! 948: checks if the given key is permitted to log in, and if so, responds
! 949: with SSH_SMSG_AUTH_RSA_CHALLENGE. Otherwise, it responds with
! 950: SSH_SMSG_FAILURE. The client often tries several different keys in
! 951: sequence until one supported by the server is found. Authentication
! 952: is accepted if the client gives the correct response to the challenge.
! 953: The server is free to add other criteria for authentication, such as a
! 954: requirement that the connection must come from a certain host. Such
! 955: additions are not visible at the protocol level. Supporting this
! 956: authentication method is optional but recommended.
! 957: .IP "7 SSH_SMSG_AUTH_RSA_CHALLENGE"
! 958: .TS
! 959: ;
! 960: l l.
! 961: mp-int encrypted challenge
! 962: .TE
! 963: Presents an RSA authentication challenge to the client. The challenge
! 964: is a 256-bit random value encrypted as described elsewhere in this
! 965: document. The client must decrypt the challenge using the RSA private
! 966: key, compute MD5 of the challenge plus session id, and send back the
! 967: resulting 16 bytes using SSH_CMSG_AUTH_RSA_RESPONSE.
! 968: .IP "8 SSH_CMSG_AUTH_RSA_RESPONSE"
! 969: .TS
! 970: ;
! 971: l l.
! 972: 16 bytes MD5 of decrypted challenge
! 973: .TE
! 974: This message is sent by the client in response to an RSA challenge.
! 975: The MD5 checksum is returned instead of the decrypted challenge to
! 976: deter known-plaintext attacks against the RSA key. The server
! 977: responds to this message with either SSH_SMSG_SUCCESS or
! 978: SSH_SMSG_FAILURE.
! 979: .IP "9 SSH_CMSG_AUTH_PASSWORD"
! 980: .TS
! 981: ;
! 982: l l.
! 983: string plain text password
! 984: .TE
! 985: Requests password authentication using the given password. Note that
! 986: even though the password is plain text inside the packet, the whole
! 987: packet is normally encrypted by the packet layer. It would not be
! 988: possible for the client to perform password encryption/hashing,
! 989: because it cannot know which kind of encryption/hashing, if any, the
! 990: server uses. The server responds to this message with
! 991: SSH_SMSG_SUCCESS or SSH_SMSG_FAILURE.
! 992: .IP "10 SSH_CMSG_REQUEST_PTY"
! 993: .TS
! 994: ;
! 995: l l.
! 996: string TERM environment variable value (e.g. vt100)
! 997: 32-bit int terminal height, rows (e.g., 24)
! 998: 32-bit int terminal width, columns (e.g., 80)
! 999: 32-bit int terminal width, pixels (0 if no graphics) (e.g., 480)
! 1000: 32-bit int terminal height, pixels (0 if no graphics) (e.g., 640)
! 1001: n bytes tty modes encoded in binary
! 1002: .TE
! 1003: Requests a pseudo-terminal to be allocated for this command. This
! 1004: message can be used regardless of whether the session will later
! 1005: execute the shell or a command. If a pty has been requested with this
! 1006: message, the shell or command will run on a pty. Otherwise it will
! 1007: communicate with the server using pipes, sockets or some other similar
! 1008: mechanism.
! 1009:
! 1010: The terminal type gives the type of the user's terminal. In the UNIX
! 1011: environment it is passed to the shell or command in the TERM
! 1012: environment variable.
! 1013:
! 1014: The width and height values give the initial size of the user's
! 1015: terminal or window. All values can be zero if not supported by the
! 1016: operating system. The server will pass these values to the kernel if
! 1017: supported.
! 1018:
! 1019: Terminal modes are encoded into a byte stream in a portable format.
! 1020: The exact format is described later in this document.
! 1021:
! 1022: The server responds to the request with either SSH_SMSG_SUCCESS or
! 1023: SSH_SMSG_FAILURE. If the server does not have the concept of pseudo
! 1024: terminals, it should return success if it is possible to execute a
! 1025: shell or a command so that it looks to the client as if it was running
! 1026: on a pseudo terminal.
! 1027: .IP "11 SSH_CMSG_WINDOW_SIZE"
! 1028: .TS
! 1029: ;
! 1030: l l.
! 1031: 32-bit int terminal height, rows
! 1032: 32-bit int terminal width, columns
! 1033: 32-bit int terminal width, pixels
! 1034: 32-bit int terminal height, pixels
! 1035: .TE
! 1036: This message can only be sent by the client during the interactive
! 1037: session. This indicates that the size of the user's window has
! 1038: changed, and provides the new size. The server will update the
! 1039: kernel's notion of the window size, and a SIGWINCH signal or
! 1040: equivalent will be sent to the shell or command (if supported by the
! 1041: operating system).
! 1042: .IP "12 SSH_CMSG_EXEC_SHELL"
! 1043:
! 1044: (no arguments)
! 1045:
! 1046: Starts a shell (command interpreter), and enters interactive session
! 1047: mode.
! 1048: .IP "13 SSH_CMSG_EXEC_CMD"
! 1049: .TS
! 1050: ;
! 1051: l l.
! 1052: string command to execute
! 1053: .TE
! 1054: Starts executing the given command, and enters interactive session
! 1055: mode. On UNIX, the command is run as "<shell> -c <command>", where
! 1056: <shell> is the user's login shell.
! 1057: .IP "14 SSH_SMSG_SUCCESS"
! 1058:
! 1059: (no arguments)
! 1060:
! 1061: This message is sent by the server in response to the session key, a
! 1062: successful authentication request, and a successfully completed
! 1063: preparatory operation.
! 1064: .IP "15 SSH_SMSG_FAILURE"
! 1065:
! 1066: (no arguments)
! 1067:
! 1068: This message is sent by the server in response to a failed
! 1069: authentication operation to indicate that the user has not yet been
! 1070: successfully authenticated, and in response to a failed preparatory
! 1071: operation. This is also sent in response to an authentication or
! 1072: preparatory operation request that is not recognized or supported.
! 1073: .IP "16 SSH_CMSG_STDIN_DATA"
! 1074: .TS
! 1075: ;
! 1076: l l.
! 1077: string data
! 1078: .TE
! 1079: Delivers data from the client to be supplied as input to the shell or
! 1080: program running on the server side. This message can only be used in
! 1081: the interactive session mode. No acknowledgement is sent for this
! 1082: message.
! 1083: .IP "17 SSH_SMSG_STDOUT_DATA"
! 1084: .TS
! 1085: ;
! 1086: l l.
! 1087: string data
! 1088: .TE
! 1089: Delivers data from the server that was read from the standard output of
! 1090: the shell or program running on the server side. This message can
! 1091: only be used in the interactive session mode. No acknowledgement is
! 1092: sent for this message.
! 1093: .IP "18 SSH_SMSG_STDERR_DATA"
! 1094: .TS
! 1095: ;
! 1096: l l.
! 1097: string data
! 1098: .TE
! 1099: Delivers data from the server that was read from the standard error of
! 1100: the shell or program running on the server side. This message can
! 1101: only be used in the interactive session mode. No acknowledgement is
! 1102: sent for this message.
! 1103: .IP "19 SSH_CMSG_EOF"
! 1104:
! 1105: (no arguments)
! 1106:
! 1107: This message is sent by the client to indicate that EOF has been
! 1108: reached on the input. Upon receiving this message, and after all
! 1109: buffered input data has been sent to the shell or program, the server
! 1110: will close the input file descriptor to the program. This message can
! 1111: only be used in the interactive session mode. No acknowledgement is
! 1112: sent for this message.
! 1113: .IP "20 SSH_SMSG_EXITSTATUS"
! 1114: .TS
! 1115: ;
! 1116: l l.
! 1117: 32-bit int exit status of the command
! 1118: .TE
! 1119: Returns the exit status of the shell or program after it has exited.
! 1120: The client should respond with SSH_CMSG_EXIT_CONFIRMATION when it has
! 1121: received this message. This will be the last message sent by the
! 1122: server. If the program being executed dies with a signal instead of
! 1123: exiting normally, the server should terminate the session with
! 1124: SSH_MSG_DISCONNECT (which can be used to pass a human-readable string
! 1125: indicating that the program died due to a signal) instead of using
! 1126: this message.
! 1127: .IP "21 SSH_MSG_CHANNEL_OPEN_CONFIRMATION"
! 1128: .TS
! 1129: ;
! 1130: l l.
! 1131: 32-bit int remote_channel
! 1132: 32-bit int local_channel
! 1133: .TE
! 1134: This is sent in response to any channel open request if the channel
! 1135: has been successfully opened. Remote_channel is the channel number
! 1136: received in the initial open request; local_channel is the channel
! 1137: number the side sending this message has allocated for the channel.
! 1138: Data can be transmitted on the channel after this message.
! 1139: .IP "22 SSH_MSG_CHANNEL_OPEN_FAILURE"
! 1140: .TS
! 1141: ;
! 1142: l l.
! 1143: 32-bit int remote_channel
! 1144: .TE
! 1145: This message indicates that an earlier channel open request by the
! 1146: other side has failed or has been denied. Remote_channel is the
! 1147: channel number given in the original request.
! 1148: .IP "23 SSH_MSG_CHANNEL_DATA"
! 1149: .TS
! 1150: ;
! 1151: l l.
! 1152: 32-bit int remote_channel
! 1153: string data
! 1154: .TE
! 1155: Data is transmitted in a channel in these messages. A channel is
! 1156: bidirectional, and both sides can send these messages. There is no
! 1157: acknowledgement for these messages. It is possible that either side
! 1158: receives these messages after it has sent SSH_MSG_CHANNEL_CLOSE for
! 1159: the channel. These messages cannot be received after the party has
! 1160: sent or received SSH_MSG_CHANNEL_CLOSE_CONFIRMATION.
! 1161: .IP "24 SSH_MSG_CHANNEL_CLOSE"
! 1162: .TS
! 1163: ;
! 1164: l l.
! 1165: 32-bit int remote_channel
! 1166: .TE
! 1167: When a channel is closed at one end of the connection, that side sends
! 1168: this message. Upon receiving this message, the channel should be
! 1169: closed. When this message is received, if the channel is already
! 1170: closed (the receiving side has sent this message for the same channel
! 1171: earlier), the channel is freed and no further action is taken;
! 1172: otherwise the channel is freed and SSH_MSG_CHANNEL_CLOSE_CONFIRMATION
! 1173: is sent in response. (It is possible that the channel is closed
! 1174: simultaneously at both ends.)
! 1175: .IP "25 SSH_MSG_CHANNEL_CLOSE_CONFIRMATION"
! 1176: .TS
! 1177: ;
! 1178: l l.
! 1179: 32-bit int remote_channel
! 1180: .TE
! 1181: This message is sent in response to SSH_MSG_CHANNEL_CLOSE unless the
! 1182: channel was already closed. When this message is sent or received,
! 1183: the channel is freed.
! 1184: .IP "26 (OBSOLETED; was unix-domain X11 forwarding)
! 1185: .IP "27 SSH_SMSG_X11_OPEN"
! 1186: .TS
! 1187: ;
! 1188: l l.
! 1189: 32-bit int local_channel
! 1190: string originator_string (see below)
! 1191: .TE
! 1192: This message can be sent by the server during the interactive session
! 1193: mode to indicate that a client has connected the fake X server.
! 1194: Local_channel is the channel number that the server has allocated for
! 1195: the connection. The client should try to open a connection to the
! 1196: real X server, and respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
! 1197: SSH_MSG_CHANNEL_OPEN_FAILURE.
! 1198:
! 1199: The field originator_string is present if both sides
! 1200: specified SSH_PROTOFLAG_HOST_IN_FWD_OPEN in the protocol flags. It
! 1201: contains a description of the host originating the connection.
! 1202: .IP "28 SSH_CMSG_PORT_FORWARD_REQUEST"
! 1203: .TS
! 1204: ;
! 1205: l l.
! 1206: 32-bit int server_port
! 1207: string host_to_connect
! 1208: 32-bit int port_to_connect
! 1209: .TE
! 1210: Sent by the client in the preparatory phase, this message requests
! 1211: that server_port on the server machine be forwarded over the secure
! 1212: channel to the client machine, and from there to the specified host
! 1213: and port. The server should start listening on the port, and send
! 1214: SSH_MSG_PORT_OPEN whenever a connection is made to it. Supporting
! 1215: this message is optional, and the server is free to reject any forward
! 1216: request. For example, it is highly recommended that unless the user
! 1217: has been authenticated as root, forwarding any privileged port numbers
! 1218: (below 1024) is denied.
! 1219: .IP "29 SSH_MSG_PORT_OPEN"
! 1220: .TS
! 1221: ;
! 1222: l l.
! 1223: 32-bit int local_channel
! 1224: string host_name
! 1225: 32-bit int port
! 1226: string originator_string (see below)
! 1227: .TE
! 1228: Sent by either party in interactive session mode, this message
! 1229: indicates that a connection has been opened to a forwarded TCP/IP
! 1230: port. Local_channel is the channel number that the sending party has
! 1231: allocated for the connection. Host_name is the host the connection
! 1232: should be be forwarded to, and the port is the port on that host to
! 1233: connect. The receiving party should open the connection, and respond
! 1234: with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
! 1235: SSH_MSG_CHANNEL_OPEN_FAILURE. It is recommended that the receiving
! 1236: side check the host_name and port for validity to avoid compromising
! 1237: local security by compromised remote side software. Particularly, it
! 1238: is recommended that the client permit connections only to those ports
! 1239: for which it has requested forwarding with SSH_CMSG_PORT_FORWARD_REQUEST.
! 1240:
! 1241: The field originator_string is present if both sides
! 1242: specified SSH_PROTOFLAG_HOST_IN_FWD_OPEN in the protocol flags. It
! 1243: contains a description of the host originating the connection.
! 1244: .IP "30 SSH_CMSG_AGENT_REQUEST_FORWARDING"
! 1245:
! 1246: (no arguments)
! 1247:
! 1248: Requests that the connection to the authentication agent be forwarded
! 1249: over the secure channel. The method used by clients to contact the
! 1250: authentication agent within each machine is implementation and machine
! 1251: dependent. If the server accepts this request, it should arrange that
! 1252: any clients run from this session will actually contact the server
! 1253: program when they try to contact the authentication agent. The server
! 1254: should then send a SSH_SMSG_AGENT_OPEN to open a channel to the agent,
! 1255: and the client should forward the connection to the real
! 1256: authentication agent. Supporting this message is optional.
! 1257: .IP "31 SSH_SMSG_AGENT_OPEN"
! 1258: .TS
! 1259: ;
! 1260: l l.
! 1261: 32-bit int local_channel
! 1262: .TE
! 1263: Sent by the server in interactive session mode, this message requests
! 1264: opening a channel to the authentication agent. The client should open
! 1265: a channel, and respond with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION
! 1266: or SSH_MSG_CHANNEL_OPEN_FAILURE.
! 1267: .IP "32 SSH_MSG_IGNORE"
! 1268: .TS
! 1269: ;
! 1270: l l.
! 1271: string data
! 1272: .TE
! 1273: Either party may send this message at any time. This message, and the
! 1274: argument string, is silently ignored. This message might be used in
! 1275: some implementations to make traffic analysis more difficult. This
! 1276: message is not currently sent by the implementation, but all
! 1277: implementations are required to recognize and ignore it.
! 1278: .IP "33 SSH_CMSG_EXIT_CONFIRMATION"
! 1279:
! 1280: (no arguments)
! 1281:
! 1282: Sent by the client in response to SSH_SMSG_EXITSTATUS. This is the
! 1283: last message sent by the client.
! 1284: .IP "34 SSH_CMSG_X11_REQUEST_FORWARDING"
! 1285: .TS
! 1286: ;
! 1287: l l.
! 1288: string x11_authentication_protocol
! 1289: string x11_authentication_data
! 1290: 32-bit int screen number (if SSH_PROTOFLAG_SCREEN_NUMBER)
! 1291: .TE
! 1292: Sent by the client during the preparatory phase, this message requests
! 1293: that the server create a fake X11 display and set the DISPLAY
! 1294: environment variable accordingly. An internet-domain display is
! 1295: preferable. The given authentication protocol and the associated data
! 1296: should be recorded by the server so that it is used as authentication
! 1297: on connections (e.g., in .Xauthority). The authentication protocol
! 1298: must be one of the supported X11 authentication protocols, e.g.,
! 1299: "MIT-MAGIC-COOKIE-1". Authentication data must be a lowercase hex
! 1300: string of even length. Its interpretation is protocol dependent.
! 1301: The data is in a format that can be used with e.g. the xauth program.
! 1302: Supporting this message is optional.
! 1303:
! 1304: The client is permitted (and recommended) to generate fake
! 1305: authentication information and send fake information to the server.
! 1306: This way, a corrupt server will not have access to the user's terminal
! 1307: after the connection has terminated. The correct authorization codes
! 1308: will also not be left hanging around in files on the server (many
! 1309: users keep the same X session for months, thus protecting the
! 1310: authorization data becomes important).
! 1311:
! 1312: X11 authentication spoofing works by initially sending fake (random)
! 1313: authentication data to the server, and interpreting the first packet
! 1314: sent by the X11 client after the connection has been opened. The
! 1315: first packet contains the client's authentication. If the packet
! 1316: contains the correct fake data, it is replaced by the client by the
! 1317: correct authentication data, and then sent to the X server.
! 1318: .IP "35 SSH_CMSG_AUTH_RHOSTS_RSA"
! 1319: .TS
! 1320: ;
! 1321: l l.
! 1322: string clint-side user name
! 1323: 32-bit int client_host_key_bits
! 1324: mp-int client_host_key_public_exponent
! 1325: mp-int client_host_key_public_modulus
! 1326: .TE
! 1327: Requests authentication using /etc/hosts.equiv and .rhosts (or
! 1328: equivalent) together with RSA host authentication. The server should
! 1329: check that the client side port number is less than 1024 (a privileged
! 1330: port), and immediately reject authentication if it is not. The server
! 1331: responds with SSH_SMSG_FAILURE or SSH_SMSG_AUTH_RSA_CHALLENGE. The
! 1332: client must respond to the challenge with the proper
! 1333: SSH_CMSG_AUTH_RSA_RESPONSE. The server then responds with success if
! 1334: access was granted, or failure if the client gave a wrong response.
! 1335: Supporting this authentication method is optional but recommended in
! 1336: most environments.
! 1337: .IP "36 SSH_MSG_DEBUG"
! 1338: .TS
! 1339: ;
! 1340: l l.
! 1341: string debugging message sent to the other side
! 1342: .TE
! 1343: This message may be sent by either party at any time. It is used to
! 1344: send debugging messages that may be informative to the user in
! 1345: solving various problems. For example, if authentication fails
! 1346: because of some configuration error (e.g., incorrect permissions for
! 1347: some file), it can be very helpful for the user to make the cause of
! 1348: failure available. On the other hand, one should not make too much
! 1349: information available for security reasons. It is recommended that
! 1350: the client provides an option to display the debugging information
! 1351: sent by the sender (the user probably does not want to see it by default).
! 1352: The server can log debugging data sent by the client (if any). Either
! 1353: party is free to ignore any received debugging data. Every
! 1354: implementation must be able to receive this message, but no
! 1355: implementation is required to send these.
! 1356: .IP "37 SSH_CMSG_REQUEST_COMPRESSION"
! 1357: .TS
! 1358: ;
! 1359: l l.
! 1360: 32-bit int gzip compression level (1-9)
! 1361: .TE
! 1362: This message can be sent by the client in the preparatory operations
! 1363: phase. The server responds with SSH_SMSG_FAILURE if it does not
! 1364: support compression or does not want to compress; it responds with
! 1365: SSH_SMSG_SUCCESS if it accepted the compression request. In the
! 1366: latter case the response to this packet will still be uncompressed,
! 1367: but all further packets in either direction will be compressed by gzip.
! 1368: .RT
! 1369:
! 1370:
! 1371: .ti 0
! 1372: Encoding of Terminal Modes
! 1373:
! 1374: Terminal modes (as passed in SSH_CMSG_REQUEST_PTY) are encoded into a
! 1375: byte stream. It is intended that the coding be portable across
! 1376: different environments.
! 1377:
! 1378: The tty mode description is a stream of bytes. The stream consists of
! 1379: opcode-argument pairs. It is terminated by opcode TTY_OP_END (0).
! 1380: Opcodes 1-127 have one-byte arguments. Opcodes 128-159 have 32-bit
! 1381: integer arguments (stored msb first). Opcodes 160-255 are not yet
! 1382: defined, and cause parsing to stop (they should only be used after any
! 1383: other data).
! 1384:
! 1385: The client puts in the stream any modes it knows about, and the server
! 1386: ignores any modes it does not know about. This allows some degree of
! 1387: machine-independence, at least between systems that use a POSIX-like
! 1388: [POSIX] tty interface. The protocol can support other systems as
! 1389: well, but the client may need to fill reasonable values for a number
! 1390: of parameters so the server pty gets set to a reasonable mode (the
! 1391: server leaves all unspecified mode bits in their default values, and
! 1392: only some combinations make sense).
! 1393:
! 1394: The following opcodes have been defined. The naming of opcodes mostly
! 1395: follows the POSIX terminal mode flags.
! 1396: .IP "0 TTY_OP_END"
! 1397: Indicates end of options.
! 1398: .IP "1 VINTR"
! 1399: Interrupt character; 255 if none. Similarly for the other characters.
! 1400: Not all of these characters are supported on all systems.
! 1401: .IP "2 VQUIT"
! 1402: The quit character (sends SIGQUIT signal on UNIX systems).
! 1403: .IP "3 VERASE"
! 1404: Erase the character to left of the cursor.
! 1405: .IP "4 VKILL"
! 1406: Kill the current input line.
! 1407: .IP "5 VEOF "
! 1408: End-of-file character (sends EOF from the terminal).
! 1409: .IP "6 VEOL "
! 1410: End-of-line character in addition to carriage return and/or linefeed.
! 1411: .IP "7 VEOL2"
! 1412: Additional end-of-line character.
! 1413: .IP "8 VSTART"
! 1414: Continues paused output (normally ^Q).
! 1415: .IP "9 VSTOP"
! 1416: Pauses output (^S).
! 1417: .IP "10 VSUSP"
! 1418: Suspends the current program.
! 1419: .IP "11 VDSUSP"
! 1420: Another suspend character.
! 1421: .IP "12 VREPRINT"
! 1422: Reprints the current input line.
! 1423: .IP "13 VWERASE"
! 1424: Erases a word left of cursor.
! 1425: .IP "14 VLNEXT"
! 1426: More special input characters; these are probably not supported on
! 1427: most systems.
! 1428: .IP "15 VFLUSH"
! 1429: .IP "16 VSWTCH"
! 1430: .IP "17 VSTATUS"
! 1431: .IP "18 VDISCARD"
! 1432:
! 1433: .IP "30 IGNPAR"
! 1434: The ignore parity flag. The next byte should be 0 if this flag is not
! 1435: set, and 1 if it is set.
! 1436: .IP "31 PARMRK"
! 1437: More flags. The exact definitions can be found in the POSIX standard.
! 1438: .IP "32 INPCK"
! 1439: .IP "33 ISTRIP"
! 1440: .IP "34 INLCR"
! 1441: .IP "35 IGNCR"
! 1442: .IP "36 ICRNL"
! 1443: .IP "37 IUCLC"
! 1444: .IP "38 IXON"
! 1445: .IP "39 IXANY"
! 1446: .IP "40 IXOFF"
! 1447: .IP "41 IMAXBEL"
! 1448:
! 1449: .IP "50 ISIG"
! 1450: .IP "51 ICANON"
! 1451: .IP "52 XCASE"
! 1452: .IP "53 ECHO"
! 1453: .IP "54 ECHOE"
! 1454: .IP "55 ECHOK"
! 1455: .IP "56 ECHONL"
! 1456: .IP "57 NOFLSH"
! 1457: .IP "58 TOSTOP"
! 1458: .IP "59 IEXTEN"
! 1459: .IP "60 ECHOCTL"
! 1460: .IP "61 ECHOKE"
! 1461: .IP "62 PENDIN"
! 1462:
! 1463: .IP "70 OPOST"
! 1464: .IP "71 OLCUC"
! 1465: .IP "72 ONLCR"
! 1466: .IP "73 OCRNL"
! 1467: .IP "74 ONOCR"
! 1468: .IP "75 ONLRET"
! 1469:
! 1470: .IP "90 CS7"
! 1471: .IP "91 CS8"
! 1472: .IP "92 PARENB"
! 1473: .IP "93 PARODD"
! 1474:
! 1475: .IP "192 TTY_OP_ISPEED"
! 1476: Specifies the input baud rate in bits per second.
! 1477: .IP "193 TTY_OP_OSPEED"
! 1478: Specifies the output baud rate in bits per second.
! 1479: .RT
! 1480:
! 1481:
! 1482: .ti 0
! 1483: The Authentication Agent Protocol
! 1484:
! 1485: The authentication agent is a program that can be used to hold RSA
! 1486: authentication keys for the user (in future, it might hold data for
! 1487: other authentication types as well). An authorized program can send
! 1488: requests to the agent to generate a proper response to an RSA
! 1489: challenge. How the connection is made to the agent (or its
! 1490: representative) inside a host and how access control is done inside a
! 1491: host is implementation-dependent; however, how it is forwarded and how
! 1492: one interacts with it is specified in this protocol. The connection
! 1493: to the agent is normally automatically forwarded over the secure
! 1494: channel.
! 1495:
! 1496: A program that wishes to use the agent first opens a connection to its
! 1497: local representative (typically, the agent itself or an SSH server).
! 1498: It then writes a request to the connection, and waits for response.
! 1499: It is recommended that at least five minutes of timeout are provided
! 1500: waiting for the agent to respond to an authentication challenge (this
! 1501: gives sufficient time for the user to cut-and-paste the challenge to a
! 1502: separate machine, perform the computation there, and cut-and-paste the
! 1503: result back if so desired).
! 1504:
! 1505: Messages sent to and by the agent are in the following format:
! 1506: .TS
! 1507: ;
! 1508: l l.
! 1509: 4 bytes Length, msb first. Does not include length itself.
! 1510: 1 byte Packet type. The value 255 is reserved for future extensions.
! 1511: data Any data, depending on packet type. Encoding as in the ssh packet
! 1512: protocol.
! 1513: .TE
! 1514:
! 1515: The following message types are currently defined:
! 1516: .IP "1 SSH_AGENTC_REQUEST_RSA_IDENTITIES"
! 1517:
! 1518: (no arguments)
! 1519:
! 1520: Requests the agent to send a list of all RSA keys for which it can
! 1521: answer a challenge.
! 1522: .IP "2 SSH_AGENT_RSA_IDENTITIES_ANSWER"
! 1523: .TS
! 1524: ;
! 1525: l l.
! 1526: 32-bit int howmany
! 1527: howmany times:
! 1528: 32-bit int bits
! 1529: mp-int public exponent
! 1530: mp-int public modulus
! 1531: string comment
! 1532: .TE
! 1533: The agent sends this message in response to the to
! 1534: SSH_AGENTC_REQUEST_RSA_IDENTITIES. The answer lists all RSA keys for
! 1535: which the agent can answer a challenge. The comment field is intended
! 1536: to help identify each key; it may be printed by an application to
! 1537: indicate which key is being used. If the agent is not holding any
! 1538: keys, howmany will be zero.
! 1539: .IP "3 SSH_AGENTC_RSA_CHALLENGE
! 1540: .TS
! 1541: ;
! 1542: l l.
! 1543: 32-bit int bits
! 1544: mp-int public exponent
! 1545: mp-int public modulus
! 1546: mp-int challenge
! 1547: 16 bytes session_id
! 1548: 32-bit int response_type
! 1549: .TE
! 1550: Requests RSA decryption of random challenge to authenticate the other
! 1551: side. The challenge will be decrypted with the RSA private key
! 1552: corresponding to the given public key.
! 1553:
! 1554: The decrypted challenge must contain a zero in the highest (partial)
! 1555: byte, 2 in the next byte, followed by non-zero random bytes, a zero
! 1556: byte, and then the real challenge value in the lowermost bytes. The
! 1557: real challenge must be 32 8-bit bytes (256 bits).
! 1558:
! 1559: Response_type indicates the format of the response to be returned.
! 1560: Currently the only supported value is 1, which means to compute MD5 of
! 1561: the real challenge plus session id, and return the resulting 16 bytes
! 1562: in a SSH_AGENT_RSA_RESPONSE message.
! 1563: .IP "4 SSH_AGENT_RSA_RESPONSE"
! 1564: .TS
! 1565: ;
! 1566: l l.
! 1567: 16 bytes MD5 of decrypted challenge
! 1568: .TE
! 1569: Answers an RSA authentication challenge. The response is 16 bytes:
! 1570: the MD5 checksum of the 32-byte challenge.
! 1571: .IP "5 SSH_AGENT_FAILURE"
! 1572:
! 1573: (no arguments)
! 1574:
! 1575: This message is sent whenever the agent fails to answer a request
! 1576: properly. For example, if the agent cannot answer a challenge (e.g.,
! 1577: no longer has the proper key), it can respond with this. The agent
! 1578: also responds with this message if it receives a message it does not
! 1579: recognize.
! 1580: .IP "6 SSH_AGENT_SUCCESS"
! 1581:
! 1582: (no arguments)
! 1583:
! 1584: This message is sent by the agent as a response to certain requests
! 1585: that do not otherwise cause a message be sent. Currently, this is
! 1586: only sent in response to SSH_AGENTC_ADD_RSA_IDENTITY and
! 1587: SSH_AGENTC_REMOVE_RSA_IDENTITY.
! 1588: .IP "7 SSH_AGENTC_ADD_RSA_IDENTITY"
! 1589: .TS
! 1590: ;
! 1591: l l.
! 1592: 32-bit int bits
! 1593: mp-int public modulus
! 1594: mp-int public exponent
! 1595: mp-int private exponent
! 1596: mp-int multiplicative inverse of p mod q
! 1597: mp-int p
! 1598: mp-int q
! 1599: string comment
! 1600: .TE
! 1601: Registers an RSA key with the agent. After this request, the agent can
! 1602: use this RSA key to answer requests. The agent responds with
! 1603: SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
! 1604: .IP "8 SSH_AGENT_REMOVE_RSA_IDENTITY"
! 1605: .TS
! 1606: ;
! 1607: l l.
! 1608: 32-bit int bits
! 1609: mp-int public exponent
! 1610: mp-int public modulus
! 1611: .TE
! 1612: Removes an RSA key from the agent. The agent will no longer accept
! 1613: challenges for this key and will not list it as a supported identity.
! 1614: The agent responds with SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE.
! 1615: .RT
! 1616:
! 1617: If the agent receives a message that it does not understand, it
! 1618: responds with SSH_AGENT_FAILURE. This permits compatible future
! 1619: extensions.
! 1620:
! 1621: It is possible that several clients have a connection open to the
! 1622: authentication agent simultaneously. Each client will use a separate
! 1623: connection (thus, any SSH connection can have multiple agent
! 1624: connections active simultaneously).
! 1625:
! 1626:
! 1627: .ti 0
! 1628: References
! 1629:
! 1630: .IP "[DES] "
! 1631: FIPS PUB 46-1: Data Encryption Standard. National Bureau of
! 1632: Standards, January 1988. FIPS PUB 81: DES Modes of Operation.
! 1633: National Bureau of Standards, December 1980. Bruce Schneier: Applied
! 1634: Cryptography. John Wiley & Sons, 1994. J. Seberry and J. Pieprzyk:
! 1635: Cryptography: An Introduction to Computer Security. Prentice-Hall,
! 1636: 1989.
! 1637: .IP "[GZIP] "
! 1638: The GNU GZIP program; available for anonymous ftp at prep.ai.mit.edu.
! 1639: Please let me know if you know a paper describing the algorithm.
! 1640: .IP "[IDEA] "
! 1641: Xuejia Lai: On the Design and Security of Block Ciphers, ETH Series in
! 1642: Information Processing, vol. 1, Hartung-Gorre Verlag, Konstanz,
! 1643: Switzerland, 1992. Bruce Schneier: Applied Cryptography, John Wiley &
! 1644: Sons, 1994. See also the following patents: PCT/CH91/00117, EP 0 482
! 1645: 154 B1, US Pat. 5,214,703.
! 1646: .IP [PKCS#1]
! 1647: PKCS #1: RSA Encryption Standard. Version 1.5, RSA Laboratories,
! 1648: November 1993. Available for anonymous ftp at ftp.rsa.com.
! 1649: .IP [POSIX]
! 1650: Portable Operating System Interface (POSIX) - Part 1: Application
! 1651: Program Interface (API) [C language], ISO/IEC 9945-1, IEEE Std 1003.1,
! 1652: 1990.
! 1653: .IP [RFC0791]
! 1654: J. Postel: Internet Protocol, RFC 791, USC/ISI, September 1981.
! 1655: .IP [RFC0793]
! 1656: J. Postel: Transmission Control Protocol, RFC 793, USC/ISI, September
! 1657: 1981.
! 1658: .IP [RFC1034]
! 1659: P. Mockapetris: Domain Names - Concepts and Facilities, RFC 1034,
! 1660: USC/ISI, November 1987.
! 1661: .IP [RFC1282]
! 1662: B. Kantor: BSD Rlogin, RFC 1258, UCSD, December 1991.
! 1663: .IP "[RSA] "
! 1664: Bruce Schneier: Applied Cryptography. John Wiley & Sons, 1994. See
! 1665: also R. Rivest, A. Shamir, and L. M. Adleman: Cryptographic
! 1666: Communications System and Method. US Patent 4,405,829, 1983.
! 1667: .IP "[X11] "
! 1668: R. Scheifler: X Window System Protocol, X Consortium Standard, Version
! 1669: 11, Release 6. Massachusetts Institute of Technology, Laboratory of
! 1670: Computer Science, 1994.
! 1671: .RT
! 1672:
! 1673:
! 1674: .ti 0
! 1675: Security Considerations
! 1676:
! 1677: This protocol deals with the very issue of user authentication and
! 1678: security.
! 1679:
! 1680: First of all, as an implementation issue, the server program will have
! 1681: to run as root (or equivalent) on the server machine. This is because
! 1682: the server program will need be able to change to an arbitrary user
! 1683: id. The server must also be able to create a privileged TCP/IP port.
! 1684:
! 1685: The client program will need to run as root if any variant of .rhosts
! 1686: authentication is to be used. This is because the client program will
! 1687: need to create a privileged port. The client host key is also usually
! 1688: stored in a file which is readable by root only. The client needs the
! 1689: host key in .rhosts authentication only. Root privileges can be
! 1690: dropped as soon as the privileged port has been created and the host
! 1691: key has been read.
! 1692:
! 1693: The SSH protocol offers major security advantages over existing telnet
! 1694: and rlogin protocols.
! 1695: .IP o
! 1696: IP spoofing is restricted to closing a connection (by encryption, host
! 1697: keys, and the special random cookie). If encryption is not used, IP
! 1698: spoofing is possible for those who can hear packets going out from the
! 1699: server.
! 1700: .IP o
! 1701: DNS spoofing is made ineffective (by host keys).
! 1702: .IP o
! 1703: Routing spoofing is made ineffective (by host keys).
! 1704: .IP o
! 1705: All data is encrypted with strong algorithms to make eavesdropping as
! 1706: difficult as possible. This includes encrypting any authentication
! 1707: information such as passwords. The information for decrypting session
! 1708: keys is destroyed every hour.
! 1709: .IP o
! 1710: Strong authentication methods: .rhosts combined with RSA host
! 1711: authentication, and pure RSA authentication.
! 1712: .IP o
! 1713: X11 connections and arbitrary TCP/IP ports can be forwarded securely.
! 1714: .IP o
! 1715: Man-in-the-middle attacks are deterred by using the server host key to
! 1716: encrypt the session key.
! 1717: .IP o
! 1718: Trojan horses to catch a password by routing manipulation are deterred
! 1719: by checking that the host key of the server machine matches that
! 1720: stored on the client host.
! 1721: .RT
! 1722:
! 1723: The security of SSH against man-in-the-middle attacks and the security
! 1724: of the new form of .rhosts authentication, as well as server host
! 1725: validation, depends on the integrity of the host key and the files
! 1726: containing known host keys.
! 1727:
! 1728: The host key is normally stored in a root-readable file. If the host
! 1729: key is compromised, it permits attackers to use IP, DNS and routing
! 1730: spoofing as with current rlogin and rsh. It should never be any worse
! 1731: than the current situation.
! 1732:
! 1733: The files containing known host keys are not sensitive. However, if an
! 1734: attacker gets to modify the known host key files, it has the same
! 1735: consequences as a compromised host key, because the attacker can then
! 1736: change the recorded host key.
! 1737:
! 1738: The security improvements obtained by this protocol for X11 are of
! 1739: particular significance. Previously, there has been no way to protect
! 1740: data communicated between an X server and a client running on a remote
! 1741: machine. By creating a fake display on the server, and forwarding all
! 1742: X11 requests over the secure channel, SSH can be used to run any X11
! 1743: applications securely without any cooperation with the vendors of the
! 1744: X server or the application.
! 1745:
! 1746: Finally, the security of this program relies on the strength of the
! 1747: underlying cryptographic algorithms. The RSA algorithm is used for
! 1748: authentication key exchange. It is widely believed to be secure. Of
! 1749: the algorithms used to encrypt the session, DES has a rather small key
! 1750: these days, probably permitting governments and organized criminals to
! 1751: break it in very short time with specialized hardware. 3DES is
! 1752: probably safe (but slower). IDEA is widely believed to be secure.
! 1753: People have varying degrees of confidence in the other algorithms.
! 1754: This program is not secure if used with no encryption at all.
! 1755:
! 1756:
! 1757: .ti 0
! 1758: Additional Information
! 1759:
! 1760: Additional information (especially on the implementation and mailing
! 1761: lists) is available via WWW at http://www.cs.hut.fi/ssh.
! 1762:
! 1763: Comments should be sent to Tatu Ylonen <ylo@cs.hut.fi> or the SSH
! 1764: Mailing List <ssh@clinet.fi>.
! 1765:
! 1766: .ti 0
! 1767: Author's Address
! 1768:
! 1769: .TS
! 1770: ;
! 1771: l.
! 1772: Tatu Ylonen
! 1773: Helsinki University of Technology
! 1774: Otakaari 1
! 1775: FIN-02150 Espoo, Finland
! 1776:
! 1777: Phone: +358-0-451-3374
! 1778: Fax: +358-0-451-3293
! 1779: EMail: ylo@cs.hut.fi
! 1780: .TE
![[BACK]](/icons/back.gif){kind=icon}
Return to RFC.nroff CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh