See https://www.openssh.com/releasenotes.html for the release
notes.

Please read https://www.openssh.com/report.html for bug reporting
instructions and note that we do not use Github for bug reporting.

This is the port of OpenBSD's excellent OpenSSH[0] to Linux and other
Unices.

OpenSSH is based on the last free version of Tatu Ylonen's sample
implementation with all patent-encumbered algorithms removed (to external
libraries), all known security bugs fixed, new features reintroduced and
many other clean-ups.  OpenSSH was created by Aaron Campbell, Bob Beck,
Markus Friedl, Niels Provos, Theo de Raadt, and Dug Song, and has been
developed and maintained by Andre Lucas, Ben Lindstom, Damien Miller,
Darren Tucker and Tim Rice. It has a homepage at https://www.openssh.com/

This port consists of the re-introduction of autoconf support, PAM
support, EGD/PRNGD support and replacements for OpenBSD library
functions that are (regrettably) absent from other unices. This port
has been best tested on AIX, Cygwin, HP-UX, Linux, MacOS/X,
FreeBSD, NetBSD, OpenBSD, OpenServer, Solaris and UnixWare.

This version actively tracks changes in the OpenBSD CVS repository.

There is now several mailing lists for this port of OpenSSH. Please
refer to https://www.openssh.com/list.html for details on how to join.

Please send bug reports and patches to https://bugzilla.mindrot.org or
the mailing list openssh-unix-dev@mindrot.org.  To mitigate spam, the
list only allows posting from subscribed addresses.  Code contribution
are welcomed, but please follow the OpenBSD style guidelines[1].

Please refer to the INSTALL document for information on dependencies and
how to install OpenSSH on your system.

Damien Miller <djm@mindrot.org>

Miscellania -

This version of OpenSSH is based upon code retrieved from the OpenBSD CVS
repository which in turn was based on the last free sample implementation
released by Tatu Ylonen.

References -

[0] https://www.openssh.com/
[1] https://man.openbsd.org/style.9

How to verify host keys using OpenSSH and DNS
---------------------------------------------

OpenSSH contains support for verifying host keys using DNS as described
in https://tools.ietf.org/html/rfc4255. The document contains very brief
instructions on how to use this feature. Configuring DNS is out of the
scope of this document.


(1) Server: Generate and publish the DNS RR

To create a DNS resource record (RR) containing a fingerprint of the
public host key, use the following command:

	ssh-keygen -r hostname -f keyfile -g

where "hostname" is your fully qualified hostname and "keyfile" is the
file containing the public host key file. If you have multiple keys,
you should generate one RR for each key.

In the example above, ssh-keygen will print the fingerprint in a
generic DNS RR format parsable by most modern name server
implementations. If your nameserver has support for the SSHFP RR
you can omit the -g flag and ssh-keygen will print a standard SSHFP RR.

To publish the fingerprint using the DNS you must add the generated RR
to your DNS zone file and sign your zone.


(2) Client: Enable ssh to verify host keys using DNS

To enable the ssh client to verify host keys using DNS, you have to
add the following option to the ssh configuration file
($HOME/.ssh/config or /etc/ssh/ssh_config):

    VerifyHostKeyDNS yes

Upon connection the client will try to look up the fingerprint RR
using DNS. If the fingerprint received from the DNS server matches
the remote host key, the user will be notified.


	Jakob Schlyter
	Wesley Griffin


$OpenBSD: README.dns,v 1.2 2003/10/14 19:43:23 jakob Exp $

# Portable OpenSSH

[![C/C++ CI](../../actions/workflows/c-cpp.yml/badge.svg)](../../actions/workflows/c-cpp.yml)
[![VM CI](../../actions/workflows/vm.yml/badge.svg)](../../actions/workflows/vm.yml)
[![C/C++ CI self-hosted](https://github.com/openssh/openssh-portable-selfhosted/actions/workflows/selfhosted.yml/badge.svg)](https://github.com/openssh/openssh-portable-selfhosted/actions/workflows/selfhosted.yml)
[![CIFuzz](../../actions/workflows/cifuzz.yml/badge.svg)](../../actions/workflows/cifuzz.yml)
[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/openssh.svg)](https://issues.oss-fuzz.com/issues?q="Project:+openssh"+is:open)
[![Coverity Status](https://scan.coverity.com/projects/21341/badge.svg)](https://scan.coverity.com/projects/openssh-portable)

OpenSSH is a complete implementation of the SSH protocol (version 2) for secure remote login, command execution and file transfer. It includes a client ``ssh`` and server ``sshd``, file transfer utilities ``scp`` and ``sftp`` as well as tools for key generation (``ssh-keygen``), run-time key storage (``ssh-agent``) and a number of supporting programs.

This is a port of OpenBSD's [OpenSSH](https://openssh.com) to most Unix-like operating systems, including Linux, OS X and Cygwin. Portable OpenSSH polyfills OpenBSD APIs that are not available elsewhere, adds sshd sandboxing for more operating systems and includes support for OS-native authentication and auditing (e.g. using PAM).

## Documentation

The official documentation for OpenSSH are the man pages for each tool:

* [ssh(1)](https://man.openbsd.org/ssh.1)
* [sshd(8)](https://man.openbsd.org/sshd.8)
* [ssh-keygen(1)](https://man.openbsd.org/ssh-keygen.1)
* [ssh-agent(1)](https://man.openbsd.org/ssh-agent.1)
* [scp(1)](https://man.openbsd.org/scp.1)
* [sftp(1)](https://man.openbsd.org/sftp.1)
* [ssh-keyscan(8)](https://man.openbsd.org/ssh-keyscan.8)
* [sftp-server(8)](https://man.openbsd.org/sftp-server.8)

## Stable Releases

Stable release tarballs are available from a number of [download mirrors](https://www.openssh.com/portable.html#downloads). We recommend the use of a stable release for most users. Please read the [release notes](https://www.openssh.com/releasenotes.html) for details of recent changes and potential incompatibilities.

## Building Portable OpenSSH

### Dependencies

Portable OpenSSH is built using autoconf and make. It requires a working C compiler, standard library and headers.

``libcrypto`` from one of [LibreSSL](https://www.libressl.org/), [OpenSSL](https://www.openssl.org), [AWS-LC](https://github.com/aws/aws-lc) or [BoringSSL](https://github.com/google/boringssl) may also be used.  OpenSSH may be built without either of these, but the resulting binaries will have only a subset of the cryptographic algorithms normally available.

[zlib](https://www.zlib.net/) is optional; without it transport compression is not supported.

FIDO security token support needs [libfido2](https://github.com/Yubico/libfido2) and its dependencies and will be enabled automatically if they are found.

In addition, certain platforms and build-time options may require additional dependencies; see README.platform for details about your platform.

### Building a release

Release tarballs and release branches in git include a pre-built copy of the ``configure`` script and may be built using:

```
tar zxvf openssh-X.YpZ.tar.gz
cd openssh
./configure # [options]
make && make tests
```

See the [Build-time Customisation](#build-time-customisation) section below for configure options. If you plan on installing OpenSSH to your system, then you will usually want to specify destination paths.

### Building from git

If building from the git master branch, you'll need [autoconf](https://www.gnu.org/software/autoconf/) installed to build the ``configure`` script. The following commands will check out and build portable OpenSSH from git:

```
git clone https://github.com/openssh/openssh-portable # or https://anongit.mindrot.org/openssh.git
cd openssh-portable
autoreconf
./configure
make && make tests
```

### Build-time Customisation

There are many build-time customisation options available. All Autoconf destination path flags (e.g. ``--prefix``) are supported (and are usually required if you want to install OpenSSH).

For a full list of available flags, run ``./configure --help`` but a few of the more frequently-used ones are described below. Some of these flags will require additional libraries and/or headers be installed.

Flag | Meaning
--- | ---
``--with-pam`` | Enable [PAM](https://en.wikipedia.org/wiki/Pluggable_authentication_module) support. [OpenPAM](https://www.openpam.org/), [Linux PAM](http://www.linux-pam.org/) and Solaris PAM are supported.
``--with-libedit`` | Enable [libedit](https://www.thrysoee.dk/editline/) support for sftp.
``--with-kerberos5`` | Enable Kerberos/GSSAPI support. Both [Heimdal](https://www.h5l.org/) and [MIT](https://web.mit.edu/kerberos/) Kerberos implementations are supported.
``--with-selinux`` | Enable [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) support.

## Development

Portable OpenSSH development is discussed on the [openssh-unix-dev mailing list](https://lists.mindrot.org/mailman/listinfo/openssh-unix-dev) ([archive mirror](https://marc.info/?l=openssh-unix-dev)). Bugs and feature requests are tracked on our [Bugzilla](https://bugzilla.mindrot.org/).

## Reporting bugs

_Non-security_ bugs may be reported to the developers via [Bugzilla](https://bugzilla.mindrot.org/) or via the mailing list above. Security bugs should be reported to [openssh@openssh.com](mailto:openssh.openssh.com).

This file contains notes about OpenSSH on specific platforms.

AIX

Beginning with OpenSSH 3.8p1, sshd will honour an account's password
expiry settings, where prior to that it did not.  Because of this,
it's possible for sites that have used OpenSSH's sshd exclusively to
have accounts which have passwords expired longer than the inactive time
(ie the "Weeks between password EXPIRATION and LOCKOUT" setting in SMIT
or the maxexpired chuser attribute).

Accounts in this state must have their passwords reset manually by the
administrator.  As a precaution, it is recommended that the administrative
passwords be reset before upgrading from OpenSSH <3.8.

As of OpenSSH 4.0p1, configure will attempt to detect if your version
and maintenance level of AIX has a working getaddrinfo, and will use it
if found.  This will enable IPv6 support.  If for some reason configure
gets it wrong, or if you want to build binaries to work on earlier MLs
than the build host then you can add "-DBROKEN_GETADDRINFO" to CFLAGS
to force the previous IPv4-only behaviour.

IPv6 known to work: 5.1ML7 5.2ML2 5.2ML5
IPv6 known broken: 4.3.3ML11 5.1ML4

If you wish to use dynamic libraries that aren't in the normal system
locations (eg IBM's OpenSSL and zlib packages) then you will need to
define the environment variable blibpath before running configure, eg

blibpath=/lib:/usr/lib:/opt/freeware/lib ./configure \
  --with-ssl-dir=/opt/freeware --with-zlib=/opt/freeware

If sshd is built with the WITH_AIXAUTHENTICATE option (which is enabled
by default) then sshd checks that users are permitted via the
loginrestrictions() function, in particular that the user has the
"rlogin" attribute set.  This check is not done for the root account,
instead the PermitRootLogin setting in sshd_config is used.

If you are using the IBM compiler you probably want to use CC=xlc rather
than the default of cc.


Cygwin
------
To build on Cygwin, OpenSSH requires the following packages:
gcc, gcc-mingw-core, mingw-runtime, binutils, make, openssl,
openssl-devel, zlib, minres, minires-devel.


Darwin and MacOS X
------------------
Darwin does not provide a tun(4) driver required for OpenSSH-based
virtual private networks. The BSD manpage still exists, but the driver
has been removed in recent releases of Darwin and MacOS X.

Tunnel support is known to work with Darwin 8 and MacOS X 10.4 in
Point-to-Point (Layer 3) and Ethernet (Layer 2) mode using a third
party driver. More information is available at:
	https://tuntaposx.sourceforge.net

Recent Darwin/MacOS X versions are likely unsupported.

Linux
-----

Some Linux distributions (including Red Hat/Fedora/CentOS) include
headers and library links in the -devel RPMs rather than the main
binary RPMs. If you get an error about headers, or complaining about a
missing prerequisite then you may need to install the equivalent
development packages.  On Redhat based distros these may be openssl-devel,
zlib-devel and pam-devel, on Debian based distros these may be
libssl-dev, libz-dev and libpam-dev.


Solaris
-------
If you enable BSM auditing on Solaris, you need to update audit_event(4)
for praudit(1m) to give sensible output.  The following line needs to be
added to /etc/security/audit_event:

	32800:AUE_openssh:OpenSSH login:lo

The BSM audit event range available for third party TCB applications is
32768 - 65535.  Event number 32800 has been chosen for AUE_openssh.
There is no official registry of 3rd party event numbers, so if this
number is already in use on your system, you may change it at build time
by configure'ing --with-cflags=-DAUE_openssh=32801 then rebuilding.


Platforms using PAM
-------------------
As of OpenSSH 4.3p1, sshd will no longer check /etc/nologin itself when
PAM is enabled.  To maintain existing behaviour, pam_nologin should be
added to sshd's session stack which will prevent users from starting shell
sessions.  Alternatively, pam_nologin can be added to either the auth or
account stacks which will prevent authentication entirely, but will still
return the output from pam_nologin to the client.

Privilege separation, or privsep, is a method in OpenSSH by which
operations that require root privilege are performed by a separate
privileged monitor process. Its purpose is to prevent privilege
escalation and mitigate attacks by:

 - reducing the privileged attack surface by performing most
   operations involving untrusted data in unprivileged code,
 - facilitating OS-level sandboxing of the components that are most
   exposed to attack,
 - reducing information-sharing between privileged and
   unprivileged code, and
 - containing attacks as much as possible to the unprivileged
   process, should they occur.

To achieve privilege separation in OpenSSH's sshd, the functions
it performs are split across three discrete binaries:

sshd is the main entry-point binary for the server. This binary
retains privilege but performs a very limited set of tasks: loading
and checking the configuration, listening for incoming connections
and monitoring the status of connections through the
pre-authentication phase of their lifecycle to implement the
MaxStartups and PerSourcePenalties features.

Apart from listening for and accepting connections, the sshd binary
does not handle untrusted, network-derived data; instead it forks and
executes the sshd-session binary for each new connection.

+---------------------------------------------------------------+
|                                                               |
|   listening socket     +-------------------+                  |
|         \--------------+  sshd (listener)  |                  |
|                        +--------++---------+                  |
|                                 ||                            |
|                                 || fork+exec                  |
|                                 ||                            |
|                  +--------------++------------------+         |
|                  |  sshd-session (preauth monitor)  |         |
|                  +--------------++------------------+         |
|                                 ||                            |
|                                 || fork+exec                  |
|                                 ||                            |
|   network socket   +------------++--------------+             |
|        \-----------+  sshd-auth (unprivileged)  |             |
|                    +------------++--------------+             |
|                                                               |
+---------------------------------------------------------------+
               pre-authentication process structure

sshd-session initially acts as the privileged monitor process for
a connection before it completes authentication. During this phase,
it does not deal directly with network-derived data, but forks and
executes a third binary (sshd-auth, described next) to handle the
SSH protocol communication over the network socket. sshd-session
receives RPC messages from the sshd-auth subprocess when it needs
to perform privileged operations, such as verifying an account's
existence, signing with a host key, or checking a user's password.
The monitor process implements a loose state machine that enforces
the required structure and order of operations that sshd-auth may
request.

sshd-auth is the network-facing process that implements the initial
key agreement and authentication phase of the SSH protocol. It is
started with privilege, but will sandbox and/or chroot(2) itself
and drop privilege to an unprivileged account before processing
any network traffic. All operations that require privilege, such as
looking up user information, private key signatures, checking
passwords, etc are performed by RPC to the parent sshd-session
process. After authentication completes, sshd-auth serialises its
SSH protocol and connection state, exports this to the parent
sshd-session process and exits.

Communication between parent and child processes occurs over shared
file descriptors. Parent processes also monitor their children for
abnormal exit conditions, such as crashes or signalling via exit(3)
status. These conditions are used in sshd to implement the
PerSourcePenalties controls.

+---------------------------------------------------------------+
|                                                               |
|                 +---------------++------------------+         |
|                 |  sshd-session (postauth monitor)  |         |
|                 +---------------++------------------+         |
|                                 ||                            |
|                                 || fork                       |
|                                 ||                            |
| network socket   +--------------++---------------+            |
|      \-----------+  sshd-session (unprivileged)  |            |
|                  +--------------++---------------+            |
|                                                               |
+---------------------------------------------------------------+
              post-authentication process structure

After authentication, sshd-session disconnects from its parent
listener sshd (which doesn't track connections after authentication
has succeeded) and forks again. The forked sshd-session child process
will drop privilege to that of the authenticated user, import the
previously-serialised connection state from sshd-auth and continue to
perform network and SSH protocol operations for the remainder of the
session.

The parent sshd-session process continues to act as a privileged
monitor process, performing actions that require privilege when
requested via RPC. These operations include allocating PTYs and
signing key re-exchange messages.

In portable OpenSSH several compile-time options affect privilege
separation:

    --with-sandbox=style

Controls the sandboxing implementation used by sshd-auth. OS level
sandboxing is supported on a number of platforms. A fallback
rlimit(2)-based sandbox provides some basic control on a wider set
of platforms. Most supported sandboxes are detected and enabled
automatically, so this option is mostly used to disable the sandbox
(this is handy when debugging or running under tools like
AddressSanitizer).

    --with-privsep-user=user

Specifies the unprivileged user that sshd-auth will switch to
before it starts handling untrusted data. This user must not be
shared with any other system service, should own no files, should
have a locked password, a shell that denies access (such as
/bin/nologin or /bin/false) and the home directory set to the
privilege separation path. For most platforms the default user is
"sshd".

    --with-privsep-path=/path

Controls the directory that sshd-auth will chroot(2) to before
dropping privileges. This directory should be empty, not shared
with other system accounts and not readable or writable by the
sandbox user. The default privsep path is "/var/empty".

You should do something like the following to prepare the privsep
preauth environment:

	# mkdir /var/empty
	# chown root:sys /var/empty
	# chmod 755 /var/empty
	# groupadd sshd
	# useradd -g sshd -c 'sshd privsep' -d /var/empty -s /bin/false sshd

On some platforms, only the pre-authentication part of privsep is
supported, and the post-authentication part is disabled due to lack
of support from the operating system.

This is an example process list for a connection in the
pre-authentication phase:

    PID    PPID   UID CMD

   1436       1     0 sshd: /usr/sbin/sshd -D [listener] 1 of 10-100 startups
  47077    1436     0 sshd-session: djm [priv]
  47078   47077   107 sshd-auth: djm [net]

Where process 1436 is the listener, 47077 is the privileged
sshd-session monitor process and 47078 is the unprivileged,
network-facing sshd-auth process.

And in the post-authentication phase:

    PID    PPID   UID CMD
  47077    1436     0 sshd-session: djm [priv]
  47091   47077  1000 sshd-session: djm@pts/1
  47092   47091  1000 -bash

Where process 47077 continues its role as a privileged monitor,
47091 is the user-privileged network-facing post-authentication
process and 47092 is the user shell started for the session.

How to use OpenSSH-based virtual private networks
-------------------------------------------------

OpenSSH contains support for VPN tunneling using the tun(4) network
tunnel pseudo-device which is available on most platforms, either for
layer 2 or 3 traffic.

The following brief instructions on how to use this feature use
a network configuration specific to the OpenBSD operating system.

(1) Server: Enable support for SSH tunneling

To enable the ssh server to accept tunnel requests from the client, you
have to add the following option to the ssh server configuration file
(/etc/ssh/sshd_config):

	PermitTunnel yes

Restart the server or send the hangup signal (SIGHUP) to let the server
reread it's configuration.

(2) Server: Restrict client access and assign the tunnel

The OpenSSH server simply uses the file /root/.ssh/authorized_keys to
restrict the client to connect to a specified tunnel and to
automatically start the related interface configuration command. These
settings are optional but recommended:

	tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... reyk@openbsd.org

(3) Client: Configure the local network tunnel interface

Use the hostname.if(5) interface-specific configuration file to set up
the network tunnel configuration with OpenBSD. For example, use the
following configuration in /etc/hostname.tun0 to set up the layer 3
tunnel on the client:

	inet 192.168.5.1 255.255.255.252 192.168.5.2

OpenBSD also supports layer 2 tunneling over the tun device by adding
the link0 flag:

	inet 192.168.1.78 255.255.255.0 192.168.1.255 link0

Layer 2 tunnels can be used in combination with an Ethernet bridge(4)
interface, like the following example for /etc/bridgename.bridge0:

	add tun0
	add sis0
	up

(4) Client: Configure the OpenSSH client

To establish tunnel forwarding for connections to a specified
remote host by default, use the following ssh client configuration for
the privileged user (in /root/.ssh/config):

	Host sshgateway
		Tunnel yes
		TunnelDevice 0:any
		PermitLocalCommand yes
	        LocalCommand sh /etc/netstart tun0

A more complicated configuration is possible to establish a tunnel to
a remote host which is not directly accessible by the client.
The following example describes a client configuration to connect to
the remote host over two ssh hops in between. It uses the OpenSSH
ProxyCommand in combination with the nc(1) program to forward the final
ssh tunnel destination over multiple ssh sessions.

	Host access.somewhere.net
	        User puffy
	Host dmzgw
	        User puffy
	        ProxyCommand ssh access.somewhere.net nc dmzgw 22
	Host sshgateway
	        Tunnel Ethernet
	        TunnelDevice 0:any
	        PermitLocalCommand yes
	        LocalCommand sh /etc/netstart tun0
	        ProxyCommand ssh dmzgw nc sshgateway 22

The following network plan illustrates the previous configuration in
combination with layer 2 tunneling and Ethernet bridging.

+--------+       (          )      +----------------------+
| Client |------(  Internet  )-----| access.somewhere.net |
+--------+       (          )      +----------------------+
    : 192.168.1.78                             |
    :.............................         +-------+
     Forwarded ssh connection    :         | dmzgw |
     Layer 2 tunnel              :         +-------+
                                 :             |
                                 :             |
                                 :      +------------+
                                 :......| sshgateway |
                                      | +------------+
--- real connection                 Bridge ->  |          +----------+
... "virtual connection"                     [ X ]--------| somehost |
[X] switch                                                +----------+
                                                          192.168.1.25

(5) Client: Connect to the server and establish the tunnel

Finally connect to the OpenSSH server to establish the tunnel by using
the following command:

	ssh sshgateway

It is also possible to tell the client to fork into the background after
the connection has been successfully established:

	ssh -f sshgateway true

Without the ssh configuration done in step (4), it is also possible
to use the following command lines:

	ssh -fw 0:1 sshgateway true
	ifconfig tun0 192.168.5.1 192.168.5.2 netmask 255.255.255.252

Using OpenSSH tunnel forwarding is a simple way to establish secure
and ad hoc virtual private networks. Possible fields of application
could be wireless networks or administrative VPN tunnels.

Nevertheless, ssh tunneling requires some packet header overhead and
runs on top of TCP. It is still suggested to use the IP Security
Protocol (IPSec) for robust and permanent VPN connections and to
interconnect corporate networks.

	Reyk Floeter

$OpenBSD: README.tun,v 1.4 2006/03/28 00:12:31 deraadt Exp $