summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--README52
-rw-r--r--README.dns47
-rw-r--r--README.md79
-rw-r--r--README.platform96
-rw-r--r--README.privsep51
-rw-r--r--README.tun132
6 files changed, 457 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..f69b441
--- /dev/null
+++ b/README
@@ -0,0 +1,52 @@
+See https://www.openssh.com/releasenotes.html#8.4p1 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 or
+patch/pull-request management.
+
+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 has been created by
+Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo de Raadt,
+and Dug Song. 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.
+
+The PAM support is now more functional than the popular packages of
+commercial ssh-1.2.x. It checks "account" and "session" modules for
+all logins, not just when using password authentication.
+
+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
+
diff --git a/README.dns b/README.dns
new file mode 100644
index 0000000..29ecaee
--- /dev/null
+++ b/README.dns
@@ -0,0 +1,47 @@
+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 $
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..28fb43d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# Portable OpenSSH
+
+[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/openssh.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:openssh)
+
+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, and [zlib](https://www.zlib.net/). ``libcrypto`` from either [LibreSSL](https://www.libressl.org/) or [OpenSSL](https://www.openssl.org) may also be used, but OpenSSH may be built without it supporting a subset of crypto algorithms.
+
+FIDO security token support need [libfido2](https://github.com/Yubico/libfido2) and its dependencies. Also, certain platforms and build-time options may require additional dependencies, see README.platform for details.
+
+### Building a release
+
+Releases 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 git, 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.
+``--with-security-key-builtin`` | Include built-in support for U2F/FIDO2 security keys. This requires [libfido2](https://github.com/Yubico/libfido2) be installed.
+
+## 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).
diff --git a/README.platform b/README.platform
new file mode 100644
index 0000000..9210e07
--- /dev/null
+++ b/README.platform
@@ -0,0 +1,96 @@
+This file contains notes about OpenSSH on specific platforms.
+
+AIX
+---
+As of OpenSSH 3.8p1, sshd will now honour an accounts password expiry
+settings, where previously 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.0, 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.
+
+Nevertheless, 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:
+ http://www-user.rhrk.uni-kl.de/~nissler/tuntap/
+
+
+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.
diff --git a/README.privsep b/README.privsep
new file mode 100644
index 0000000..d658c46
--- /dev/null
+++ b/README.privsep
@@ -0,0 +1,51 @@
+Privilege separation, or privsep, is 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 by containing corruption to an unprivileged process.
+More information is available at:
+ http://www.citi.umich.edu/u/provos/ssh/privsep.html
+
+Privilege separation is now mandatory. During the pre-authentication
+phase sshd will chroot(2) to "/var/empty" and change its privileges to the
+"sshd" user and its primary group. sshd is a pseudo-account that should
+not be used by other daemons, and must be locked and should contain a
+"nologin" or invalid shell.
+
+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
+
+/var/empty should not contain any files.
+
+configure supports the following options to change the default
+privsep user and chroot directory:
+
+ --with-privsep-path=xxx Path for privilege separation chroot
+ --with-privsep-user=user Specify non-privileged user for privilege separation
+
+PAM-enabled OpenSSH is known to function with privsep on AIX, FreeBSD,
+HP-UX (including Trusted Mode), Linux, NetBSD and Solaris.
+
+On Cygwin, Tru64 Unix and OpenServer only the pre-authentication part
+of privsep is supported. Post-authentication privsep is disabled
+automatically (so you won't see the additional process mentioned below).
+
+Note that for a normal interactive login with a shell, enabling privsep
+will require 1 additional process per login session.
+
+Given the following process listing (from HP-UX):
+
+ UID PID PPID C STIME TTY TIME COMMAND
+ root 1005 1 0 10:45:17 ? 0:08 /opt/openssh/sbin/sshd -u0
+ root 6917 1005 0 15:19:16 ? 0:00 sshd: stevesk [priv]
+ stevesk 6919 6917 0 15:19:17 ? 0:03 sshd: stevesk@2
+ stevesk 6921 6919 0 15:19:17 pts/2 0:00 -bash
+
+process 1005 is the sshd process listening for new connections.
+process 6917 is the privileged monitor process, 6919 is the user owned
+sshd process and 6921 is the shell process.
diff --git a/README.tun b/README.tun
new file mode 100644
index 0000000..5e1cb07
--- /dev/null
+++ b/README.tun
@@ -0,0 +1,132 @@
+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 $