home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_q_t / draft-ietf-tls-ssh-00.txt < prev    next >
Text File  |  1996-06-15  |  44KB  |  1,122 lines
  1.  
  2.  
  3. Network Working Group                           Tatu Ylonen <ylo@ssh.fi>
  4. INTERNET-DRAFT                               SSH Communications Security
  5. draft-ietf-tls-ssh-00.txt                                  June 13, 1996
  6. Expires: December 1st, 1996
  7.  
  8.  
  9.                       SSH Transport Layer Protocol
  10.  
  11. Status of This memo
  12.  
  13. This document is an Internet-Draft. Internet-Drafts are working
  14. documents of the Internet Engineering Task Force (IETF), its areas,
  15. and its working groups. Note that other groups may also distribute
  16. working documents as Internet-Drafts.
  17.  
  18. Internet-Drafts are draft documents valid for a maximum of six
  19. months and may be updated, replaced, or obsoleted by other documents
  20. at any time. It is inappropriate to use Internet-Drafts as reference
  21. material or to cite them other than as ``work in progress.''
  22.  
  23. To learn the current status of any Internet-Draft, please check
  24. the ``1id-abstracts.txt'' listing contained in the Internet-Drafts
  25. Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
  26. munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast),
  27. or ftp.isi.edu (US West Coast).
  28.  
  29. Abstract
  30.  
  31. This document describes the SSH transport layer protocol.  The protocol
  32. can be used as a basis for a number of secure network services.  It pro-
  33. vides strong encryption, mutual authentication, and integrity protec-
  34. tion.
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60. Tatu Ylonen <ylo@ssh.fi>                                        [page 1]
  61.  
  62. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  63.  
  64. Table of Contents
  65.  
  66. 1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . .  2
  67. 2.  Data Type Representations Used in the Protocol  . . . . . . . . .  3
  68.   2.1.  vlint32   . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  69.   2.2.  string  . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  70.   2.3.  boolean   . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  71.   2.4.  byte  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  72.   2.5.  uint16  . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  73.   2.6.  uint32  . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  74. 3.  Connection Setup  . . . . . . . . . . . . . . . . . . . . . . . .  4
  75.   3.1.  Use over TCP/IP   . . . . . . . . . . . . . . . . . . . . . .  4
  76.   3.2.  Protocol Version Exchange   . . . . . . . . . . . . . . . . .  4
  77.   3.3.  Compatibility with Old SSH Versions   . . . . . . . . . . . .  4
  78.     3.3.1.  Old Client, New Server  . . . . . . . . . . . . . . . . .  4
  79.     3.3.2.  New Client, Old Server  . . . . . . . . . . . . . . . . .  5
  80. 4.  Binary Packet Protocol  . . . . . . . . . . . . . . . . . . . . .  5
  81.   4.1.  Maximum Packet Length   . . . . . . . . . . . . . . . . . . .  5
  82.   4.2.  Compression   . . . . . . . . . . . . . . . . . . . . . . . .  6
  83.   4.3.  Encryption  . . . . . . . . . . . . . . . . . . . . . . . . .  6
  84.   4.4.  Data Integrity  . . . . . . . . . . . . . . . . . . . . . . .  7
  85. 5.  Key Exchange  . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  86.   5.1.  Sending Supported Algorithm Lists   . . . . . . . . . . . . .  8
  87.   5.2.  RSA-Style Key Exchange  . . . . . . . . . . . . . . . . . . . 11
  88.     5.2.1.  Server Sends Host Key   . . . . . . . . . . . . . . . . . 11
  89.     5.2.2.  Client Sends Double-Encrypted Session Key   . . . . . . . 11
  90.   5.3.  Diffie-Hellman Style Key Exchange   . . . . . . . . . . . . . 12
  91.   5.4.  Deriving Encryption and Integrity Keys  . . . . . . . . . . . 12
  92. 6.  Client Host Authentication  . . . . . . . . . . . . . . . . . . . 13
  93. 7.  Service Request   . . . . . . . . . . . . . . . . . . . . . . . . 14
  94. 8.  Data Exchange   . . . . . . . . . . . . . . . . . . . . . . . . . 14
  95. 9.  Key Re-Exchange   . . . . . . . . . . . . . . . . . . . . . . . . 15
  96. 10.  Additional Messages  . . . . . . . . . . . . . . . . . . . . . . 16
  97.   10.1.  Disconnection Message  . . . . . . . . . . . . . . . . . . . 16
  98.   10.2.  Ignored Data Message   . . . . . . . . . . . . . . . . . . . 16
  99.   10.3.  Reserved Messages  . . . . . . . . . . . . . . . . . . . . . 16
  100. 11.  Summary of Message Numbers   . . . . . . . . . . . . . . . . . . 17
  101. 12.  Public Keys and Public Key Infrastructure  . . . . . . . . . . . 17
  102.   12.1.  SSH_PK_SIMPLE_RSA_PKCS   . . . . . . . . . . . . . . . . . . 17
  103.  
  104.  
  105.  
  106. 1.  Introduction
  107.  
  108. The SSH protocol is a secure transport layer protocol.  It provides
  109. strong encryption, cryptographic host autentication, and integrity
  110. protection.
  111.  
  112. Authentication in this protocol level is host-based; this protocol does
  113. not perform user authentication.  It is expected that a higher level
  114. protocol will be defined on top of this protocol that will perform user
  115. authentication for those services that need it.
  116.  
  117.  
  118.  
  119. Tatu Ylonen <ylo@ssh.fi>                                        [page 2]
  120.  
  121. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  122.  
  123. The protocol has been designed to be simple, flexible, allow parameter
  124. negotiation, and minimize the number of round-trips.  Key exchange
  125. method, public key algorithm, symmetric encryption algorithm, message
  126. authentication algorithm, and hash algorithm are all negotiated.  It is
  127. expected that in most environments, only 1.5 round-trips will be needed
  128. for full key exchange, mutual authentication, service request, and
  129. acceptance notification of service request.  The worst case is 2.5
  130. round-trips for a proper implementation.
  131.  
  132. 2.  Data Type Representations Used in the Protocol
  133.  
  134. 2.1.  vlint32
  135.  
  136. The vlint32 can represent arbitrary 32-bit unsigned integers.  It is
  137. stored as a variable number of bytes (1-5 bytes), depending on the value
  138. being stored.
  139.  
  140. Bits 6-7 of the first byte determine the number of additional bytes that
  141. follow, and are interpreted as follows.
  142.  
  143.   Bit7  Bit6    Number of bytes that follow
  144.    0     0       0
  145.    0     1       1
  146.    1     0       2
  147.    1     1       4
  148.  
  149. Bits 0-6 of the first byte and the following bytes contain the value of
  150. the integer, MSB first.
  151.  
  152. If bits 6-7 are both one, the remaining bits in the first byte are zero
  153. (reserved for future extension).
  154.  
  155. 2.2.  string
  156.  
  157. A string here means an arbitrary length binary string.  Strings are
  158. allowed to contain arbitrary binary data, including null characters and
  159. 8-bit characters.
  160.  
  161. A string is represented as a vlint32 containing its length, followed by
  162. zero or more characters that are the value of the string.
  163.  
  164. 2.3.  boolean
  165.  
  166. A boolean value is represented as a single byte.  The value 0 represents
  167. false, and the value 1 represents true.  All non-zero values are
  168. interpreted as true, but applications should not store values other than
  169. 0 and 1.
  170.  
  171. 2.4.  byte
  172.  
  173. A byte represents an arbitrary 8-bit value.  Fixed length data is
  174. sometimes represented as byte array of bytes, written byte[n], where n
  175. is the number of bytes in the array.
  176.  
  177.  
  178. Tatu Ylonen <ylo@ssh.fi>                                        [page 3]
  179.  
  180. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  181.  
  182. 2.5.  uint16
  183.  
  184. A 16-bit unsigned integer, represented as two bytes, MSB first.
  185.  
  186. 2.6.  uint32
  187.  
  188. A 32-bit unsigned integer, represented as four bytes, MSB first.
  189.  
  190. 3.  Connection Setup
  191.  
  192. SSH works over any 8-bit clean, binary-transparent transport.  The
  193. client initiates the connection, and sets up the binary-transparent
  194. transport.
  195.  
  196. 3.1.  Use over TCP/IP
  197.  
  198. When used over TCP/IP, the server normally listens for connections on
  199. port 22.  This port number has been registered with the IANA (Internet
  200. Assigned Numbers Authority), and has been officially assigned for SSH.
  201.  
  202. 3.2.  Protocol Version Exchange
  203.  
  204. When the connection has been established, both sides send an
  205. identification string of the form "SSH-protoversion-softwareversion
  206. comments", followed by a newline.  The maximum length of the string is
  207. 255 characters, including the newline.  The protocol version described
  208. in this document is 2.0.
  209.  
  210. Key exchange will begin immediately after sending this identifier
  211. (normally without waiting for the identifier from the other side -- see
  212. the next section for compatibility issues).  All packets following the
  213. identification string will use the binary packet protocol, to be
  214. described below.
  215.  
  216. 3.3.  Compatibility with Old SSH Versions
  217.  
  218. During a transition period, it is important to be able to work
  219. compatibly with installed SSH clients and servers using an older version
  220. of the protocol.  Information in this section is only relevant for
  221. implementations supporting compatibility with old versions.
  222.  
  223. 3.3.1.  Old Client, New Server
  224.  
  225. Server implementations should support a configurable "compatibility"
  226. flag that enables compatibility with old versions.  When this flag is
  227. on, the server will not send any further data after its initialization
  228. string until it has received an identification string from the client.
  229. The server can then determine whether the client is using an old
  230. protocol, and can revert to the old protocol if desired.
  231.  
  232. When compatibility with old clients is not needed, the server should
  233. send its initial key exchange data immediately after the identification
  234. string.  This saves a round-trip.
  235.  
  236.  
  237. Tatu Ylonen <ylo@ssh.fi>                                        [page 4]
  238.  
  239. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  240.  
  241. 3.3.2.  New Client, Old Server
  242.  
  243. Since the new client will immediately send additional data after its
  244. identification string (before receiving server's identification), the
  245. old protocol has already been corrupted when the client learns that the
  246. server is old.  When this happens, the client should close the
  247. connection to the server, and reconnect using the old protocol this
  248. time.
  249.  
  250. 4.  Binary Packet Protocol
  251.  
  252. Each packet consists of the following fields:
  253.  
  254.     Length
  255.       The length of the packet (bytes).  This represents the number of
  256.       bytes that follow this value, including the optional MAC.  The
  257.       length is represented as a vlint32.
  258.  
  259.     Padding length
  260.       Length of padding (bytes).  This field is represented as a
  261.       vlint32.
  262.  
  263.     Payload
  264.       The useful contents of the packet.
  265.  
  266.     Padding
  267.       Arbitrary-length padding, such that the total length of
  268.       length+paddinglength+payload+padding is a multiple of 8 bytes.  It
  269.       is recommended that at least four bytes of random padding be
  270.       always used.
  271.  
  272.     MAC
  273.       Message authentication code.  This field is optional, and its
  274.       length depends on the algorithm in use.
  275.  
  276. Note that length of the concatenation of packet length, padding length,
  277. payload, and padding must be a multiple of 8.  This constraint is
  278. enforced even when using stream ciphers.  Note that the packet length
  279. field is also encrypted, and processing it requires special care when
  280. sending/receiving packets.  In particular, one has to be extra careful
  281. when computing the amount of padding, as changing the amount of padding
  282. can also change the size of the length fields.  The minimum size of a
  283. packet is 8 characters (plus MAC); implementations should decrypt the
  284. length after receiving the first 8 bytes of a packet.
  285.  
  286. When the protocol starts, no encryption is in effect, no compression is
  287. used, and no MAC is in use.  During key exchange, an encryption method,
  288. compression method, and a MAC method are selected.  Any further messages
  289. will use the negotiated algorithms.
  290.  
  291. 4.1.  Maximum Packet Length
  292.  
  293. The maximum length of the uncompressed payload is 32768 bytes.  The
  294.  
  295.  
  296. Tatu Ylonen <ylo@ssh.fi>                                        [page 5]
  297.  
  298. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  299.  
  300. maximum size of the entire packet, including length, padding length,
  301. payload, padding, and MAC, is 35000 bytes.  The motivation for this
  302. limit is to keep the protocol easy to implement on 16-bit machines.
  303.  
  304. 4.2.  Compression
  305.  
  306. If compression has been negotiated, the payload field will be compressed
  307. using the negotiated algorithm.  The length field will contain the
  308. compressed length (i.e., that transmitted on the wire).
  309.  
  310. Compressed packets must not exceed the total packet size limit; the
  311. compression algorithm must guarantee that it does not expand the packet
  312. too much.  The uncompressed payload size must not exceed the maximum
  313. payload size (the compressed payload, however, may be bigger than the
  314. maximum payload size, as long as the packet size limit is not exceeded).
  315.  
  316. The following compression methods are currently supported:
  317.  
  318. #define SSH_COMPRESS_NONE  0 /* no compression */
  319. #define SSH_COMPRESS_ZIP   1 /* ZIP compression */
  320.  
  321. SSH_COMPRESS_ZIP is the ZLIB compression.  Its data format is described
  322. in the Internet-Draft draft-deutsch-zlib-spec-04.txt and its references.
  323. Compression level 6 is recommended.
  324.  
  325. The compression context is initialized after key exchange, and is passed
  326. from one packet to the next with only a partial flush being performed at
  327. the end of each packet.  A partial flush means that all data will be
  328. output, but the next packet will continue using compression tables from
  329. the end of the previous packet.
  330.  
  331. Compression is independent in each direction, and the different
  332. compression methods may be used for each direction.
  333. 4.3.  Encryption
  334.  
  335. An encryption algorithm and a key will be negotiated during the key
  336. exchange.  When encryption is in effect, the length, payload and padding
  337. fields of each packet will be encrypted with the given algorithm.
  338.  
  339. The encrypted data in all packets sent in one direction will be
  340. considered a single data stream.  For example, initialization vectors
  341. will be passed from the end of one packet to the beginning of the next
  342. packet.
  343.  
  344. The ciphers in each direction will run independently of each other.
  345. They will typically use a different key, and different ciphers can be
  346. used in each direction.
  347.  
  348. The following ciphers/mode combinations are currently supported:
  349.  
  350. #define SSH_CALG_NONE        0 /* No encryption */
  351. #define SSH_CALG_IDEA_CBC    1 /* IDEA in CBC mode */
  352. #define SSH_CALG_3DES_CBC    2 /* 3DES in CBC mode */
  353.  
  354.  
  355. Tatu Ylonen <ylo@ssh.fi>                                        [page 6]
  356.  
  357. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  358.  
  359. #define SSH_CALG_DES_CBC     3 /* DES in CBC mode (warning: weak!) */
  360. #define SSH_CALG_ARCFOUR     4 /* ARCFOUR stream cipher */
  361.  
  362. The ARCFOUR cipher is compatible with the RC4 cipher; RC4 is a trademark
  363. of RSA Data Security, Inc.
  364.  
  365. 4.4.  Data Integrity
  366.  
  367. Data integrity is protected by including with each packet a message
  368. authentication code (MAC) that is computed from a shared secret, packet
  369. sequence number, and the contents of the packet.
  370.  
  371. The message authentication algorithm and key are negotiated during key
  372. exchange.  Initially, no MAC will be in effect, and its length will be
  373. zero.  After key exchange, the selected MAC will be computed before
  374. encryption from the concatenation of packet data (length, payload, and
  375. padding) and a packet sequence number (stored as a 32-bit integer, MSB
  376. first).  The integrity key is also used in the computation of the MAC,
  377. but the way it is used depends on the MAC algorithm in use.  Note that
  378. the MAC algorithm may be different for each direction.
  379.  
  380. The packet sequence number is only used for integrity checking.  It is
  381. never explicitly transmitted, but it is included in MAC computation to
  382. ensure that no packets are lost.  The sequence number of the first
  383. packet sent is zero; from there on the sequence number is incremented by
  384. one for every packet sent (separately for each direction).  The packet
  385. number is 32 bits and wraps around if 32 bits is not enough for
  386. representing it.  The sequence number is incremented also for packets
  387. that are not encrypted or MACed, and is not reset even if keys are
  388. renegotiated later.
  389.  
  390. The check bytes resulting from the MAC algorithm are transmitted without
  391. encryption as the last part of the packet.  The number of check bytes
  392. depends on the algorithm chosen.
  393.  
  394. The following MAC algorithms are currently defined:
  395.  
  396. #define SSH_MAC_NONE         0 /* No MAC in use (length = 0) */
  397. #define SSH_MAC_HMAC_MD5     1 /* HMAC-MD5 (length = 16) */
  398. #define SSH_MAC_HMAC_SHA     2 /* HMAC-SHA-1 (length = 20) */
  399. #define SSH_MAC_MD5          3 /* MD5 of data+key (length = 16) */
  400.  
  401. The HMAC methods are described in draft-ietf-ipsec-hmac-md5-00.txt.
  402.  
  403. The  SSH_MAC_MD5  method returns the MD5 of the concatenation of the
  404. authenticated data and the key.
  405.  
  406. 5.  Key Exchange
  407.  
  408. Key exchange begins by each side sending lists of supported algorithms.
  409. Each side has a preferred algorithm, and it is assumed that most
  410. implementations at any given time will use the same preferred algorithm.
  411. Each side will make the guess that the other side is using the same
  412.  
  413.  
  414. Tatu Ylonen <ylo@ssh.fi>                                        [page 7]
  415.  
  416. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  417.  
  418. algorithm, and may send an initial key exchange packet according to the
  419. algorithm if the preferred method so dictates.  If the guess is wrong,
  420. they'll ignore each other's first data, select a common algorithm, and
  421. send the initial key exchange packet again, this time for the same
  422. algorithm.
  423.  
  424. At this time, there are two styles of key exchanges, RSA-style exchange
  425. and Diffie-Hellman style exchange (several methods may be available in
  426. each group).  RSA-style exchange is based on the server sending two
  427. encryption public keys (host key and server key), the client generating
  428. a session key, sending it encrypted by the public keys, and server
  429. decrypting it with private keys.  In Diffie-Hellman style exchange the
  430. parties derive a shared secret via a message exchange, and then check
  431. against man-in-the-middle attacks with a signature of the exchange.
  432.  
  433. Currently, the following key exchange methods have been defined:
  434.  
  435.           #define SSH_KEX_RSA_SHA 1 /* RSA key exchange with SHA-1 */
  436.           #define SSH_KEX_DH_SHA  2 /* Diffie-Hellman kex with SHA-1 */
  437.  
  438. 5.1.  Sending Supported Algorithm Lists
  439.  
  440. Each side sends the following packet (this is the part that goes inside
  441. the payload):
  442.  
  443.             vlint32   SSH_MSG_KEXINIT
  444.             byte[16]  cookie (random bytes)
  445.             string    kex_algorithms
  446.             string    host_key_algorithms
  447.             string    public_key_algorithms
  448.             string    encryption_algorithms_client_to_server
  449.             string    encryption_algorithms_server_to_client
  450.             string    mac_algorithms_client_to_server
  451.             string    mac_algorithms_server_to_client
  452.             string    compression_algorithms_client_to_server
  453.             string    compression_algorithms_server_to_client
  454.             string    hash_algorithms
  455.             boolean   first_kex_packet_follows
  456.             byte[4]   0 (reserved for future extension)
  457.  
  458. Each of the algorithms strings contains algorithm numbers, one per byte.
  459. Each supported (allowed) algorithm should be listed, in order of
  460. preference.  Each string must contain at least one value.  The value
  461. "NONE" is not automatically allowed; if a party permits connections with
  462. NONE as one of the algorithms, it should list that as an algorithm.
  463.  
  464.     cookie
  465.       The cookies are random values generated by each side.  They are
  466.       used when deriving keys from the shared secret.  Their purpose is
  467.       to make it impossible for either side to fully determine the keys
  468.       (which might open possibilities for passing certain
  469.       signatures/authentications to third parties).
  470.  
  471.  
  472.  
  473. Tatu Ylonen <ylo@ssh.fi>                                        [page 8]
  474.  
  475. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  476.  
  477.     kex_algorithms
  478.       Key exchange algorithms were defined above.  The first algorithm
  479.       is the preferred (and guessed) algorithm.  If both sides make the
  480.       same guess, that algorithm is used.  Otherwise, the following
  481.       algorithm is used to choose a key exchange method: iterate over
  482.       client's kex algorithms, one at a time.  Choose the first
  483.       algorithm that satisfies the following conditions: 1) the server
  484.       also supports the algorithm 2) if the algorithm requires an
  485.       encryption-capable host key, there is an encryption-capable
  486.       algorithm on the server's  host_key_algorithms that is also
  487.       supported by the client 3) if the algorithm requires a signature-
  488.       capable host key, there is a signature-capable algorithm on the
  489.       server's  host_key_algorithms  that is also supported by the
  490.       client.  If no algorithm satisfying all these conditions can be
  491.       found, connection fails.
  492.  
  493.       The available algorithm numbers were listed above.
  494.     host_key_algorithms
  495.       Lists the public key algorithms/formats for which the host has a
  496.       valid host key.  (There can be multiple host keys for a host,
  497.       possibly with different algorithm.)  Some host keys may not
  498.       support both signatures and encryption (this can be determined
  499.       from the algorithm), and thus not all host keys are valid for all
  500.       key exchange methods.  Algorithms listed in this field must also
  501.       be present in public_key_algorithms.
  502.  
  503.       See Section ``Public Key Formats'' for information on the
  504.       algorithm numbers.
  505.  
  506.     public_key_algorithms
  507.       Lists the public key algorithms supported by the host.  See
  508.       Section ``Public Key Formats'' for information on the algorithm
  509.       numbers.
  510.  
  511.     encryption_algorithms
  512.       Lists the acceptable symmetric encryption algorithms in order of
  513.       preference.  The chosen encryption algorithm will be the first
  514.       algorithm on the client's list that is also on the server's list.
  515.       If there is no such algorithm, connection fails.
  516.  
  517.       Note that SSH_CALG_NONE must be explicitly listed if it is to be
  518.       acceptable.  The available algorithm numbers are listed in Section
  519.       ``Encryption''.
  520.  
  521.       The algorithm to use is negotiated separately for each direction,
  522.       and different algorithms may be chosen.
  523.  
  524.     mac_algorithms
  525.       Lists the acceptable MAC algorithms in order of preference.  The
  526.       chosen MAC algorithm will be the first algorithm on the client's
  527.       list that is also on the server's list.  If there is no such
  528.       algorithm, connection fails.
  529.  
  530.  
  531.  
  532. Tatu Ylonen <ylo@ssh.fi>                                        [page 9]
  533.  
  534. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  535.  
  536.       Note that SSH_MAC_NONE must be explicitly listed if it is to be
  537.       acceptable.  The available MAC algorithm numbers are listed in
  538.       Section ``Data Integrity''.
  539.  
  540.       The algorithm to use is negotiated separately for each direction,
  541.       and different algorithms may be chosen.
  542.  
  543.     compression_algorithms
  544.       Lists the acceptable compression algorithms in order of
  545.       preference.  The chosen compression algorithm will be the first
  546.       algorithm on the client's list that is also on the server's list.
  547.       If there is no such algorithm, connection fails.
  548.  
  549.       Note that SSH_COMPRESS_NONE must be explicitly listed if it is to
  550.       be acceptable.  The available compression algorithm numbers are
  551.       listed in Section ``Compression''.
  552.  
  553.       The algorithm to use is negotiated separately for each direction,
  554.       and different algorithms may be chosen.
  555.  
  556.     hash_algorithms
  557.       Lists the acceptable hash algorithms in order of preference.  The
  558.       chosen hash algorithm will be the first algorithm on the client's
  559.       list that is also on the server's list.  If there is no such
  560.       algorithm, connection fails.
  561.  
  562.       Implementations should only permit algorithms that they consider
  563.       to be fairly secure, as the hash function will be used e.g. for
  564.       deriving various keys from the shared secret.  All hash algorithms
  565.       must produce at least 16 bytes of output.
  566.  
  567.       Currently, the following hash functions are defined:
  568.  
  569.              #define SSH_HASH_SHA        1 /* returns 20 bytes */
  570.              #define SSH_HASH_MD5        2 /* returns 16 bytes */
  571.  
  572.     first_kex_packet_follows
  573.       Each side makes a guess of the negotiated key exchange method.
  574.       This is based on the assumption that at any particular time there
  575.       will be a single key exchange method and host key algorithm
  576.       combination that dominates the installed base.  Making a guess
  577.       about the algorithm will save a round-trip in the typical case,
  578.       and will incur little extra cost in the other cases.
  579.  
  580.       Each side will determine if they are supposed to send an initial
  581.       packet in their guessed key exchange method.  If they are, they
  582.       will set this field to true and follow this packet by the first
  583.       key exchange packet.
  584.  
  585.       After receiving the SSH_MSG_KEXINIT packet from the other side,
  586.       each party will know whether their guess was right.  If the guess
  587.       was wrong, and this field is true, the next packet will be
  588.       silently ignored, and each side will then act as determined by the
  589.  
  590.  
  591. Tatu Ylonen <ylo@ssh.fi>                                       [page 10]
  592.  
  593. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  594.  
  595.       negotiated key exchange method.  If the guess was right, key
  596.       exchange will immediately continue.
  597.  
  598. 5.2.  RSA-Style Key Exchange
  599.  
  600. RSA-style key exchange requires that the server host key supports
  601. encryption.  The idea is that the server sends its public host key and a
  602. periodically changing key (called the server key).  The client then
  603. verifies that it is the correct key for the server, generates a session
  604. key, encrypts the session key using both the server host key and the
  605. server key, and sends the encrypted session key to the server.
  606.  
  607. The server key and host keys must both support encryption, and their
  608. sizes must be compatible in such a way that the result of encrypting a
  609. value with one of them can be encrypted with the other.  The smaller of
  610. the keys must be able to encrypt at least 48 bytes.
  611.  
  612. The host key should be larger than the server key, because this causes
  613. the server key encryption to be done first, and prevents an outside
  614. attacker from replacing the outer layer of encryption by an active man-
  615. in-the-middle attack.  Such an attack would not directly compromise
  616. security, but would allow the attacker to later decrypt intercepted
  617. sessions if he somehow obtains the private host key.
  618.  
  619. 5.2.1.  Server Sends Host Key
  620.  
  621. First, the server sends its public host and server keys in the following
  622. packet:
  623.  
  624.             vlint32   SSH_MSG_KEXRSA_HOSTKEY
  625.             string    public host key
  626.             string    public server key
  627.  
  628. The host key and server key are stored in binary representation as
  629. described in Section ``Public Key Formats''.
  630.  
  631. 5.2.2.  Client Sends Double-Encrypted Session Key
  632.  
  633. After receiving the public keys, the client validates that the host key
  634. really belongs to the intended server.  How this verification happens is
  635. not specified in this protocol.  Currently it may be checked against a
  636. database of known name-key mappings; in future it will probably be
  637. validated using an Internet public key infrastructure.
  638.  
  639. If the client is not willing to trust the server host key, it simply
  640. closes the connection and the protocol terminates.
  641.  
  642. Otherwise, the client chooses an encryption algorithm that is supported
  643. by both parties.  It also chooses a MAC algorithm and a compression
  644. algorithm that are supported by both parties.
  645.  
  646. To authenticate that no-one has been manipulating the key exchange with
  647. the server, the client also computes an SHA-1 hash of the concatenated
  648.  
  649.  
  650. Tatu Ylonen <ylo@ssh.fi>                                       [page 11]
  651.  
  652. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  653.  
  654. payloads of (in this order): client's SSH_MSG_KEXINIT, server's
  655. SSH_MSG_KEXINIT, and server's SSH_MSG_KEXRSA_HOSTKEY message.
  656.  
  657. The client then generates a 256 bit random session key.  A message to be
  658. passed to the server is formed by concatenating the following (in this
  659. order): six zero bytes (reserved for future), first 10 bytes of the
  660. SHA-1 hash of the key exchange, session key.  This results in a total of
  661. 48 bytes of data to be passed to the server.  Note that the negotiated
  662. algorithms are not explicitly passed, as the algorithms given in Section
  663. ``Sending Supported Algorithm Lists'' fully determine the algorithms.
  664.  
  665. Note that the use of SHA-1 was hard-coded here.  This is used to
  666. authenticate the key exchange, and using HASH here would lead to all
  667. sorts of potential problems in verifying the security of the protocol.
  668. Using a fixed hash short-circuits verification to the properties of the
  669. hash.  Should the need ever arise, the only way to switch to another
  670. algorithm here is to define a new key exchange algorithm (which, in
  671. fact, is not very difficult).
  672.  
  673. The resulting data is encrypted with the smaller of host key and server
  674. key, and the result then with the larger of them.  The resulting double-
  675. encrypted session key is then sent to the server for verification.  Note
  676. that public-key encryption probably involves padding, depending on the
  677. algorithm.
  678.  
  679.             vlint32   SSH_MSG_KEXRSA_SESSIONKEY
  680.             string    double-encrypted session key
  681.  
  682. Upon receiving this message, the server uses its private host and server
  683. keys to decrypt the session key.  It computes a corresponding SHA hash,
  684. and compares the hash values.  If the hash does not match, the server
  685. disconnects.  Otherwise, encryption, compression, and integrity
  686. protection are taken into effect immediately after this message.
  687.  
  688. The server does not acknowledge this message in any way.  The client may
  689. continue by sending further protocol requests using the negotiated
  690. encryption.  If the server was not able to decrypt the session key, it
  691. won't be able to determine what the futher requests are or to respond to
  692. them.
  693.  
  694. 5.3.  Diffie-Hellman Style Key Exchange
  695.  
  696. XXX To be defined later.
  697.  
  698. 5.4.  Deriving Encryption and Integrity Keys
  699.  
  700. As a result of the key exchange, the parties have a 256-bit shared
  701. secret.
  702.  
  703. Various keys are computed from this secret and from the cookies
  704. exchanged during algorithm negotiation.  The cookies are used to make it
  705. impossible for either party to alone determine the keys.
  706.  
  707.  
  708.  
  709. Tatu Ylonen <ylo@ssh.fi>                                       [page 12]
  710.  
  711. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  712.  
  713. Each key is computed as HASH of the concatenation of client's cookie,
  714. server's cookie, and 16 bytes of secret data.  The secret data is
  715. different for each key, and is taken from the 32-byte shared secret as
  716. follows:
  717.  
  718. o  Initial IV client to server: bytes 0-15
  719.  
  720. o  Initial IV server to client: bytes 1-16
  721.  
  722. o  Encryption key client to server: bytes 5-20
  723.  
  724. o  Encryption key server to client: bytes 8-23
  725.  
  726. o  Integrity key client to server: bytes 13-28
  727.  
  728. o  Integrity key server to client: bytes 16-31
  729.  
  730. Each key is at least 16 bytes (128 bits).  For some algorithms, only
  731. part of this amount is actually used.  If a longer key is needed for
  732. some algorithm, the key is extended by computing HASH of the entire key
  733. so far, and appending the resulting bytes (as many as HASH outputs) to
  734. the key.  This process is repeated until enough key material is
  735. available.
  736.  
  737. 6.  Client Host Authentication
  738.  
  739. Next, the client can (but is not required to) send its own host
  740. authentication message.  If this message is not sent, the server will
  741. consider the client unnamed for authentication purposes.  It is expected
  742. that many servers will refuse to talk to clients that do not first
  743. authenticate themselves.
  744.  
  745. Note that this message passes the host name, and can be used to
  746. authenticate hosts on the other side of a firewall.
  747.  
  748. To authenticate itself, the client computes HASH of the
  749. concatenatenation of (in this order) the client host name, client's
  750. cookie, and server's cookie.  It then signs this hash using its private
  751. host key (one that uses an algorithm which is supported by the server),
  752. and sends the following value to the server:
  753.  
  754.             vlint32   SSH_MSG_HOSTAUTH
  755.             string    client host name
  756.             string    client public host key
  757.             string    signature of host name+client cookie+server cookie
  758.  
  759. The host key is stored in binary representation as described in Section
  760. ``Public Key Formats''.
  761.  
  762. The server will verify that the client host name is really associated
  763. with the given key.  If the name-key association cannot be verified, the
  764. server may at its option either disconnect or ignore the client host
  765. authentication.
  766.  
  767.  
  768. Tatu Ylonen <ylo@ssh.fi>                                       [page 13]
  769.  
  770. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  771.  
  772. If the name-key association can be verified, the signature is checked.
  773. If it is incorrect, the connection is closed.  Otherwise, the server
  774. updates its state to the fact that the client has been cryptographically
  775. authenticated.
  776.  
  777. The server may also attempt to validate whether the host name supplied
  778. by the client matches with a name obtained from network protocol headers
  779. or other sources (e.g., it may require the supplied name to match a DNS
  780. reverse mapped name, unless the reverse mapped name is a firewall host).
  781. However, such validation is not always possible, and is not required by
  782. this protocol.  If the server finds a mismatch between the client-
  783. supplied name and the name obtained from the network protocols, the
  784. server may disconnect.
  785.  
  786. Some servers may refuse to continue the dialog with the client unless
  787. the client is able to authenticate itself cryptographically.  Likewise,
  788. some servers may refuse to talk to certain clients, and may disconnect
  789. at this point.  It is recommended that such disconnections use
  790. SSH_MSG_DISCONNECT and explain the reason for disconnecting.
  791.  
  792. 7.  Service Request
  793.  
  794. After the various authentications, the client requests a service.  The
  795. service is identified by a name, which must consists of alphanumeric
  796. characters, hyphens ('-'), and underscores ('_').  The name must not be
  797. longer than 64 characters.
  798.  
  799.             vlint32   SSH_MSG_SERVICE_REQUEST
  800.             string    service name
  801.  
  802. Most server implementations will have a table of services that are
  803. supported, specifying what to do for each service.
  804.  
  805. If the server rejects the service request, it either disconnects or
  806. (preferably) sends a SSH_MSG_DISCONNECT message.
  807.  
  808. If the server supports the service (and permits the client to use it),
  809. it responds with
  810.  
  811.             vlint32   SSH_MSG_SERVICE_ACCEPT
  812.  
  813. The client is permitted to send further packets without waiting for the
  814. this message; those packets will go the selected service if the server
  815. accepts the service request.
  816.  
  817. 8.  Data Exchange
  818.  
  819. Once a service has been selected, data is transmitted in each direction
  820. asynchronously.  The data is packetized using the following format:
  821.  
  822.             vlint32   SSH_MSG_DATA
  823.             string    data
  824.  
  825.  
  826.  
  827. Tatu Ylonen <ylo@ssh.fi>                                       [page 14]
  828.  
  829. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  830.  
  831. For stream-based services data is passed directly to the application.
  832. Packet-based applications may have their own packet structure embedded
  833. within each data packet.
  834.  
  835. When a service closes its output (i.e., will not send more data), the
  836. following message is sent to the other side:
  837.  
  838.             vlint32   SSH_MSG_EOF
  839.  
  840. When this message is received, the service will be notified of the end-
  841. of-file status on input.  Output from the service is still accepted, and
  842. sent to the other side.
  843.  
  844. When the service on either side exits (i.e., will no longer accept
  845. input, and will not generate more output), the following message is sent
  846. after any other data sent by the application.  After this message, the
  847. connection will be closed.  An EOF is not necessarily sent before this
  848. message.
  849.  
  850.             vlint32   SSH_MSG_CLOSE
  851.  
  852. 9.  Key Re-Exchange
  853.  
  854. Either side may request re-exchange of keys at any time after the
  855. initial exchange (and outside other key exchanges).  The re-exchange is
  856. not visible to the service, and will take place using the same algorithm
  857. that was used in the original key exchange.
  858.  
  859. Key re-exchange is started by sending a SSH_MSG_KEXINIT packet
  860. (described in Section ``Sending Supported Algorithm Lists'').  When this
  861. message is received, a party must respond with its own SSH_MSG_KEXINIT
  862. message.  Either party may initiate the re-exchange, but roles are not
  863. changed (i.e., the server remains the server, and the client remains the
  864. client).
  865.  
  866. Key re-exchange is performed under whatever encryption was in effect
  867. when the exchange was started.  Encryption, compression, and MAC methods
  868. are changed when the key exchange is complete (as in the initial key
  869. exchange).  Re-exchange is processed identically to the initial key
  870. exchange, except that it is not necessary to validate that the host key
  871. really belongs to the server.  It is permissible to change the
  872. encryption, compression, and MAC algorithms during the re-exchange.  All
  873. keys are recomputed after the exchange.  Compression and encryption
  874. contexts are reset.  The packet sequence number is not reset.
  875.  
  876. It is recommended that keys be changed after each gigabyte of
  877. transmitted data and after each hour of connection time, whichever comes
  878. sooner.
  879.  
  880. It is also possible to use the key re-exchange mechanism to switch to
  881. faster algorithms after authentication, or to avoid double processing
  882. for pre-encrypted or pre-authenticated data.  However, since the re-
  883. exchange is a public key operation, it requires a fair amount of
  884.  
  885.  
  886. Tatu Ylonen <ylo@ssh.fi>                                       [page 15]
  887.  
  888. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  889.  
  890. processing power and should not be performed too often.
  891.  
  892. 10.  Additional Messages
  893.  
  894. Either party may send any of the following messages at any time.
  895.  
  896. 10.1.  Disconnection Message
  897.  
  898.             vlint32   SSH_MSG_DISCONNECT
  899.             vlint32   error code
  900.             string    description
  901.  
  902. This message causes immediate termination of the connection.  The
  903. description field gives the reason for disconnecting in human-readable
  904. form.  The error code gives the reason in a machine-readable format, and
  905. can have the following values:
  906.  
  907. #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT      1
  908. #define SSH_DISCONNECT_PROTOCOL_ERROR                   2
  909. #define SSH_DISCONNECT_INCOMPATIBLE_HOST_KEY            3
  910. #define SSH_DISCONNECT_INCOMPATIBLE_PUBLIC_KEY_ALG      4
  911. #define SSH_DISCONNECT_INCOMPATIBLE_CRYPTO_ALG          5
  912. #define SSH_DISCONNECT_INCOMPATIBLE_MAC_ALG             6
  913. #define SSH_DISCONNECT_INCOMPATIBLE_COMPRESSION_ALG     7
  914. #define SSH_DISCONNECT_INCOMPATIBLE_HASH_ALG            8
  915. #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED              9
  916. #define SSH_DISCONNECT_HOST_AUTHENTICATION_FAILED       10
  917. #define SSH_DISCONNECT_MAC_ERROR                        11
  918. #define SSH_DISCONNECT_COMPRESSION_ERROR                12
  919. #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE            13
  920. #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED   14
  921. #define SSH_DISCONNECT_OPERATION_PROHIBITED             15
  922.  
  923. 10.2.  Ignored Data Message
  924.  
  925.             vlint32   SSH_MSG_IGNORE
  926.             string    data
  927.  
  928. All implementations must understand (and ignore) this message.  No
  929. implementation is required to ever send them.
  930.  
  931. 10.3.  Reserved Messages
  932.  
  933. An implementation must respond to all unrecognized messages with an
  934. SSH_MSG_UNIMPLEMENTED message.  Later protocol versions may define other
  935. meanings for these message types.
  936.  
  937.             vlint32   SSH_MSG_UNIMPLEMENTED
  938.             uint32    packet sequence number of rejected message
  939.  
  940. Message numbers below 1000 are reserved for "official" extensions.
  941. Other extensions and experimental code should use message numbers above
  942. this.
  943.  
  944.  
  945. Tatu Ylonen <ylo@ssh.fi>                                       [page 16]
  946.  
  947. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  948.  
  949. 11.  Summary of Message Numbers
  950.  
  951. The following message numbers have been defined in this protocol.
  952.  
  953.           #define SSH_MSG_DISCONNECT             1
  954.           #define SSH_MSG_IGNORE                 2
  955.           #define SSH_MSG_UNIMPLEMENTED          3
  956.           #define SSH_MSG_KEXINIT               10
  957.           #define SSH_MSG_KEXRSA_HOSTKEY        11
  958.           #define SSH_MSG_KEXRSA_SESSIONKEY     12
  959.           #define SSH_MSG_HOSTAUTH              30
  960.           #define SSH_MSG_SERVICE_REQUEST       40
  961.           #define SSH_MSG_SERVICE_ACCEPT        41
  962.           #define SSH_MSG_DATA                  42
  963.           #define SSH_MSG_EOF                   43
  964.           #define SSH_MSG_CLOSE                 44
  965.  
  966. 12.  Public Keys and Public Key Infrastructure
  967.  
  968. This protocol is intentionally open on public key formats, as well as
  969. signature and encryption formats.  There is currently no generally
  970. accepted public key infrastructure on the Internet, and there are
  971. several competing key formats, and more formats are likely to appear.
  972. It will probably take several years until the situation is resolved.  In
  973. particular, it is not clear that X.509 would be the solution, although
  974. that is also a possibility.
  975.  
  976. There are several aspects to a public key type:
  977.  
  978. o  Key format: how is the key coded, and how are certificates
  979.    represented.  The key blobs in this protocol may (but are not
  980.    required to) contain certificates in addition to keys.
  981.  
  982. o  Signature and/or encryption algorithms.  Some algorithms may not
  983.    support both encryption and decryption.
  984.  
  985. o  Encoding for signatures and encrypted data.  This includes but is not
  986.    limited to padding, byte order, and data formats.
  987.  
  988. o  Computation of unique key id.
  989.  
  990.           #define SSH_PK_SIMPLE_RSA_PKCS    1
  991.  
  992. Note that the key type is negotiated at the beginning of the key
  993. exchange, and is not included in the key blob itself.
  994.  
  995. 12.1.  SSH_PK_SIMPLE_RSA_PKCS
  996.  
  997. This key type defines an RSA public key, with (mostly) PKCS compatible
  998. signature and encryption formats.  It supports both signatures and
  999. encryption.
  1000.  
  1001. Public keys of this type are represented as follows:
  1002.  
  1003.  
  1004. Tatu Ylonen <ylo@ssh.fi>                                       [page 17]
  1005.  
  1006. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  1007.  
  1008.             byte[4]       0 (reserved)
  1009.             uint32        number of bits in the modulus
  1010.             uint16        number bits in the secret exponent
  1011.             bytes[n]      exponent, MSB first, n = floor((bits+7)/8)
  1012.             uint16        number of bits in the modulus
  1013.             bytes[n]      modulus, MSB first, n = floor((bits+7)/8)
  1014.  
  1015. It is permissible that there be other data (e.g., certificates)
  1016. following this; however, such data is not yet defined.
  1017.  
  1018. Note that private key formats are not defined here, and are
  1019. implementation-specific.
  1020.  
  1021. The key id for this key type is of the format "SSH-PKCS-1-RSA-xxxxxxxx",
  1022. where the "xxxxxxxx" stands for an SHA-1 hash of the data listed above,
  1023. in hexadecimal (a total of 40 lowercase hex characters).  Any data
  1024. following the above (e.g., certificates) is not included in the key id
  1025. calculation.
  1026.  
  1027. An encrypted message is formed as follows.
  1028.  
  1029. o  The data to be encrypted is padded into a long integer of the same
  1030.    number of bits as the modulus as follows:
  1031.  
  1032.               MSB             .  .  .                LSB
  1033.  
  1034.                0   2   RND(n bytes)   0   encrypted_data
  1035.  
  1036. The RND bytes represent non-zero random bytes.
  1037.  
  1038. o  To encrypt, this integer is raised to the public exponent, modulo the
  1039.    modulus.
  1040.  
  1041. o  The result is converted to a byte string of floor((bits+7)/8) bytes
  1042.    (where bits is the number of bits in the modulus), MSB first.  This
  1043.    byte string (without any length or terminating characters) is the
  1044.    result of the encryption.
  1045.  
  1046. A signature is formed as follows.
  1047.  
  1048. o  The data to be signed (typically a message digest, but not required
  1049.    to be such) is padded into a long integer of the same number of bits
  1050.    as the modulus as follows:
  1051.  
  1052.               MSB             .  .  .             LSB
  1053.  
  1054.                0   1   RND(n bytes)   0   signed_data
  1055.  
  1056. The RND bytes represent non-zero random bytes.  Note that this differs
  1057. from the PKCS standard, where 0xFF bytes are specified for padding.
  1058.  
  1059. o  To sign, this integer is raised to the private exponent, modulo the
  1060.    modulus.
  1061.  
  1062.  
  1063. Tatu Ylonen <ylo@ssh.fi>                                       [page 18]
  1064.  
  1065. INTERNET-DRAFT         SSH Transport Layer Protocol        June 13, 1996
  1066.  
  1067. o  The result is converted to a byte string of floor((bits+7)/8) bytes
  1068.    (where bits is the number of bits in the modulus), MSB first.  This
  1069.    byte string (without any length or terminating characters) is the
  1070.    signature.  Applications may add other data outside this value.
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121. Tatu Ylonen <ylo@ssh.fi>                                       [page 19]
  1122.