j-hpn-ssh/HPN-README

Notes:

MULTI-THREADED CIPHER:
The AES cipher in CTR mode has been multithreaded (MTR-AES-CTR). This will allow ssh installations
on hosts with multiple cores to use more than one processing core during encryption.
Tests have show significant throughput performance increases when using MTR-AES-CTR up
to and including a full gigabit per second on quad core systems. It should be possible to
achieve full line rate on dual core systems but OS and data management overhead makes this
more difficult to achieve. The cipher stream from MTR-AES-CTR is entirely compatible with single
thread AES-CTR (ST-AES-CTR) implementations and should be 100% backward compatible. Optimal
performance requires the MTR-AES-CTR mode be enabled on both ends of the connection.
The MTR-AES-CTR replaces ST-AES-CTR and is used in exactly the same way with the same
nomenclature.
Use examples:
		ssh -caes128-ctr you@host.com
		scp -oCipher=aes256-ctr file you@host.com:~/file

NONE CIPHER:
To use the NONE option you must have the NoneEnabled switch set on the server and
you *must* have *both* NoneEnabled and NoneSwitch set to yes on the client. The NONE
feature works with ALL ssh subsystems (as far as we can tell) *AS LONG AS* a tty is not
spawned. If a user uses the -T switch to prevent a tty being created the NONE cipher will
be disabled.

The performance increase will only be as good as the network and TCP stack tuning
on the reciever side of the connection allows. As a rule of thumb a user will need
at least 10Mb/s connection with a 100ms RTT to see a doubling of performance. The
HPN-SSH home page describes this in greater detail.

http://www.psc.edu/networking/projects/hpn-ssh

NONE MAC:
Starting with HPN 15v1 users will have the option to disable HMAC (message
authentication ciphers) when using the NONE cipher. You must enable the following:
NoneEnabled, NoneSwitch, and NoneMacEnabled. If all three are not enabled the None MAC
will be automatically disabled. In tests the use of the None MAC improved throuput by
more than 30%. 

ex: scp -oNoneSwitch=yes -oNoneEnabled=yes -oNoneMacEnabled=yes file host:~

BUFFER SIZES:

If HPN is disabled the receive buffer size will be set to the
OpenSSH default of 2MB (for OpenSSH versions before 4.7: 64KB).

If an HPN system connects to a nonHPN system the receive buffer will
be set to the HPNBufferSize value. The default is 6MB but user adjustable.

If an HPN to HPN connection is established a number of different things might
happen based on the user options and conditions.

Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll enabled, TCPRcvBuf NOT Set
HPN Buffer Size = up to 64MB
This is the default state. The HPN buffer size will grow to a maximum of 64MB
as the TCP receive buffer grows. The maximum HPN Buffer size of 64MB is
geared towards 10GigE transcontinental connections.

Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll disabled, TCPRcvBuf NOT Set
HPN Buffer Size = TCP receive buffer value.
Users on non-autotuning systems should disable TCPRcvBufPoll in the
ssh_config and sshd_config

Conditions: HPNBufferSize SET, TCPRcvBufPoll disabled, TCPRcvBuf NOT Set
HPN Buffer Size = minimum of TCP receive buffer and HPNBufferSize.
This would be the system defined TCP receive buffer (RWIN).

Conditions: HPNBufferSize SET, TCPRcvBufPoll disabled, TCPRcvBuf SET
HPN Buffer Size = minimum of TCPRcvBuf and HPNBufferSize.
Generally there is no need to set both.

Conditions: HPNBufferSize SET, TCPRcvBufPoll enabled, TCPRcvBuf NOT Set
HPN Buffer Size = grows to HPNBufferSize
The buffer will grow up to the maximum size specified here.

Conditions: HPNBufferSize SET, TCPRcvBufPoll enabled, TCPRcvBuf SET
HPN Buffer Size = minimum of TCPRcvBuf and HPNBufferSize.
Generally there is no need to set both of these, especially on autotuning
systems. However, if the users wishes to override the autotuning this would be
one way to do it.

Conditions: HPNBufferSize NOT Set, TCPRcvBufPoll enabled, TCPRcvBuf SET
HPN Buffer Size = TCPRcvBuf.
This will override autotuning and set the TCP recieve buffer to the user defined
value.


HPN Specific Configuration options

TcpRcvBuf=[int]KB client
      Set the TCP socket receive buffer to n Kilobytes. It can be set up to the
maximum socket size allowed by the system. This is useful in situations where
the tcp receive window is set low but the maximum buffer size is set
higher (as is typical). This works on a per TCP connection basis. You can also
use this to artifically limit the transfer rate of the connection. In these
cases the throughput will be no more than n/RTT. The minimum buffer size is 1KB.
Default is the current system wide tcp receive buffer size.

TcpRcvBufPoll=[yes/no] client/server
      Enable of disable the polling of the tcp receive buffer through the life
of the connection. You would want to make sure that this option is enabled
for systems making use of autotuning kernels (linux 2.4.24+, 2.6, MS Vista)
default is yes.

NoneEnabled=[yes/no] client/server
      Enable or disable the use of the None cipher. Care must always be used
when enabling this as it will allow users to send data in the clear. However,
it is important to note that authentication information remains encrypted
even if this option is enabled. Set to no by default.

NoneMacEnabled=[yes/no] client/server
      Enable or disable the use of the None MAC. When this is enabled ssh
will *not* provide data integrity of any data being transmitted between hosts. Use
with caution as it, unlike just using NoneEnabled, doesn't provide data integrity and
protection against man-in-the-middle attacks. As with NoneEnabled all authentication 
remains encrypted and integrity is ensured. Default is no.

NoneSwitch=[yes/no] client
     Switch the encryption cipher being used to the None cipher after
authentication takes place. NoneEnabled must be enabled on both the client
and server side of the connection. When the connection switches to the NONE
cipher a warning is sent to STDERR. The connection attempt will fail with an
error if a client requests a NoneSwitch from the server that does not explicitly
have NoneEnabled set to yes. Note: The NONE cipher cannot be used in
interactive (shell) sessions and it will fail silently. Set to no by default.

HPNDisabled=[yes/no] client/server
     In some situations, such as transfers on a local area network, the impact
of the HPN code produces a net decrease in performance. In these cases it is
helpful to disable the HPN functionality. By default HPNDisabled is set to no.

HPNBufferSize=[int]KB client/server
     This is the default buffer size the HPN functionality uses when interacting
with nonHPN SSH installations. Conceptually this is similar to the TcpRcvBuf
option as applied to the internal SSH flow control. This value can range from
1KB to 64MB (1-65536). Use of oversized or undersized buffers can cause performance
problems depending on the length of the network path. The default size of this buffer
is 2MB.

DisableMTAES=[yes/no] client/server
     Switch the encryption cipher being used from the multithreaded MT-AES-CTR cipher
back to the stock single-threaded AES-CTR cipher. Useful on modern processors with
AES-NI instructions which make the stock single-threaded AES-CTR cipher faster than
the multithreaded MT-AES-CTR cipher. Set to no by default.


Credits: This patch was conceived, designed, and led by Chris Rapier (rapier@psc.edu)
         The majority of the actual coding for versions up to HPN12v1 was performed
         by Michael Stevens (mstevens@andrew.cmu.edu). The MT-AES-CTR cipher was
         implemented by Ben Bennet (ben@psc.edu) and improved by Mike Tasota
         (tasota@gmail.com) an NSF REU grant recipient for 2013.
	 Allan Jude provided the code for the NoneMac and buffer normalization. 
         This work was financed, in part, by Cisco System, Inc., the National
         Library of Medicine, and the National Science Foundation.