crypto/openssh/HPN-README

   1 Notes:
   2
   3 MULTI-THREADED CIPHER:
   4 The AES cipher in CTR mode has been multithreaded (MTR-AES-CTR). This will allow ssh installations
   5 on hosts with multiple cores to use more than one processing core during encryption.
   6 Tests have show significant throughput performance increases when using MTR-AES-CTR up
   7 to and including a full gigabit per second on quad core systems. It should be possible to
   8 achieve full line rate on dual core systems but OS and data management overhead makes this
   9 more difficult to achieve. The cipher stream from MTR-AES-CTR is entirely compatible with single
  10 thread AES-CTR (ST-AES-CTR) implementations and should be 100% backward compatible. Optimal
  11 performance requires the MTR-AES-CTR mode be enabled on both ends of the connection.
  12 The MTR-AES-CTR replaces ST-AES-CTR and is used in exactly the same way with the same
  13 nomenclature.
  14 Use examples:   ssh -caes128-ctr you@host.com
  15                 scp -oCipher=aes256-ctr file you@host.com:~/file
  16
  17 NONE CIPHER:
  18 To use the NONE option you must have the NoneEnabled switch set on the server and
  19 you *must* have *both* NoneEnabled and NoneSwitch set to yes on the client. The NONE
  20 feature works with ALL ssh subsystems (as far as we can tell) *AS LONG AS* a tty is not
  21 spawned. If a user uses the -T switch to prevent a tty being created the NONE cipher will
  22 be disabled.
  23
  24 The performance increase will only be as good as the network and TCP stack tuning
  25 on the reciever side of the connection allows. As a rule of thumb a user will need
  26 at least 10Mb/s connection with a 100ms RTT to see a doubling of performance. The
  27 HPN-SSH home page describes this in greater detail.
  28
  29 http://www.psc.edu/networking/projects/hpn-ssh
  30
  31 BUFFER SIZES:
  32
  33 If HPN is disabled the receive buffer size will be set to the
  34 OpenSSH default of 64K.
  35
  36 If an HPN system connects to a nonHPN system the receive buffer will
  37 be set to the HPNBufferSize value. The default is 2MB but user adjustable.
  38
  39 If an HPN to HPN connection is established a number of different things might
  40 happen based on the user options and conditions.
  41
  42 Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll enabled, TCPRcvBuf NOT Set
  43 HPN Buffer Size = up to 64MB
  44 This is the default state. The HPN buffer size will grow to a maximum of 64MB
  45 as the TCP receive buffer grows. The maximum HPN Buffer size of 64MB is
  46 geared towards 10GigE transcontinental connections.
  47
  48 Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll disabled, TCPRcvBuf NOT Set
  49 HPN Buffer Size = TCP receive buffer value.
  50 Users on non-autotuning systesm should disable TCPRcvBufPoll in the
  51 ssh_cofig and sshd_config
  52
  53 Conditions: HPNBufferSize SET, TCPRcvBufPoll disabled, TCPRcvBuf NOT Set
  54 HPN Buffer Size = minmum of TCP receive buffer and HPNBufferSize.
  55 This would be the system defined TCP receive buffer (RWIN).
  56
  57 Conditions: HPNBufferSize SET, TCPRcvBufPoll disabled, TCPRcvBuf SET
  58 HPN Buffer Size = minmum of TCPRcvBuf and HPNBufferSize.
  59 Generally there is no need to set both.
  60
  61 Conditions: HPNBufferSize SET, TCPRcvBufPoll enabled, TCPRcvBuf NOT Set
  62 HPN Buffer Size = grows to HPNBufferSize
  63 The buffer will grow up to the maximum size specified here.
  64
  65 Conditions: HPNBufferSize SET, TCPRcvBufPoll enabled, TCPRcvBuf SET
  66 HPN Buffer Size = minmum of TCPRcvBuf and HPNBufferSize.
  67 Generally there is no need to set both of these, especially on autotuning
  68 systems. However, if the users wishes to override the autotuning this would be
  69 one way to do it.
  70
  71 Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll enabled, TCPRcvBuf SET
  72 HPN Buffer Size = TCPRcvBuf.
  73 This will override autotuning and set the TCP recieve buffer to the user defined
  74 value.
  75
  76
  77 HPN Specific Configuration options
  78
  79 TcpRcvBuf=[int]KB client
  80       set the TCP socket receive buffer to n Kilobytes. It can be set up to the
  81 maximum socket size allowed by the system. This is useful in situations where
  82 the tcp receive window is set low but the maximum buffer size is set
  83 higher (as is typical). This works on a per TCP connection basis. You can also
  84 use this to artifically limit the transfer rate of the connection. In these
  85 cases the throughput will be no more than n/RTT. The minimum buffer size is 1KB.
  86 Default is the current system wide tcp receive buffer size.
  87
  88 TcpRcvBufPoll=[yes/no] client/server
  89       enable of disable the polling of the tcp receive buffer through the life
  90 of the connection. You would want to make sure that this option is enabled
  91 for systems making use of autotuning kernels (linux 2.4.24+, 2.6, MS Vista)
  92 default is yes.
  93
  94 NoneEnabled=[yes/no] client/server
  95       enable or disable the use of the None cipher. Care must always be used
  96 when enabling this as it will allow users to send data in the clear. However,
  97 it is important to note that authentication information remains encrypted
  98 even if this option is enabled. Set to no by default.
  99
 100 NoneSwitch=[yes/no] client
 101      Switch the encryption cipher being used to the None cipher after
 102 authentication takes place. NoneEnabled must be enabled on both the client
 103 and server side of the connection. When the connection switches to the NONE
 104 cipher a warning is sent to STDERR. The connection attempt will fail with an
 105 error if a client requests a NoneSwitch from the server that does not explicitly
 106 have NoneEnabled set to yes. Note: The NONE cipher cannot be used in
 107 interactive (shell) sessions and it will fail silently. Set to no by default.
 108
 109 HPNDisabled=[yes/no] client/server
 110      In some situations, such as transfers on a local area network, the impact
 111 of the HPN code produces a net decrease in performance. In these cases it is
 112 helpful to disable the HPN functionality. By default HPNDisabled is set to no.
 113
 114 HPNBufferSize=[int]KB client/server
 115      This is the default buffer size the HPN functionality uses when interacting
 116 with nonHPN SSH installations. Conceptually this is similar to the TcpRcvBuf
 117 option as applied to the internal SSH flow control. This value can range from
 118 1KB to 64MB (1-65536). Use of oversized or undersized buffers can cause performance
 119 problems depending on the length of the network path. The default size of this buffer
 120 is 2MB.
 121
 122
 123 Credits: This patch was conceived, designed, and led by Chris Rapier (rapier@psc.edu)
 124          The majority of the actual coding for versions up to HPN12v1 was performed
 125          by Michael Stevens (mstevens@andrew.cmu.edu). The MT-AES-CTR cipher was
 126          implemented by Ben Bennet (ben@psc.edu). This work was financed, in part,
 127          by Cisco System, Inc., the National Library of Medicine,
 128          and the National Science Foundation.