contrib/cygwin/README - security/openssh-library - Rivoreo Source Code Repositories

 This package describes important Cygwin specific stuff concerning OpenSSH.

 The binary package is usually built for recent Cygwin versions and might
 not run on older versions.  Please check http://cygwin.com/ for information
 about current Cygwin releases.

 Build instructions are at the end of the file.

 ===========================================================================
 Important change since 3.7.1p2-2:

 The ssh-host-config file doesn't create the /etc/ssh_config and
 /etc/sshd_config files from builtin here-scripts anymore, but it uses
 skeleton files installed in /etc/defaults/etc.

 Also it now tries hard to create appropriate permissions on files.
 Same applies for ssh-user-config.

 After creating the sshd service with ssh-host-config, it's advisable to
 call ssh-user-config for all affected users, also already exising user
 configurations.  In the latter case, file and directory permissions are
 checked and changed, if requireed to match the host configuration.

 Important note for Windows 2003 Server users:
 ---------------------------------------------

 2003 Server has a funny new feature.  When starting services under SYSTEM
 account, these services have nearly all user rights which SYSTEM holds...
 except for the "Create a token object" right, which is needed to allow
 public key authentication :-(

 There's no way around this, except for creating a substitute account which
 has the appropriate privileges.  Basically, this account should be member
 of the administrators group, plus it should have the following user rights:

 	Create a token object
 	Logon as a service
 	Replace a process level token
 	Increase Quota

 The ssh-host-config script asks you, if it should create such an account,
 called "sshd_server".  If you say "no" here, you're on your own.  Please
 follow the instruction in ssh-host-config exactly if possible.  Note that
 ssh-user-config sets the permissions on 2003 Server machines dependent of
 whether a sshd_server account exists or not.
 ===========================================================================

 ===========================================================================
 Important change since 3.4p1-2:

 This version adds privilege separation as default setting, see
 /usr/doc/openssh/README.privsep.  According to that document the
 privsep feature requires a non-privileged account called 'sshd'.

 The new ssh-host-config file which is part of this version asks
 to create 'sshd' as local user if you want to use privilege
 separation.  If you confirm, it creates that NT user and adds
 the necessary entry to /etc/passwd.

 On 9x/Me systems the script just sets UsePrivilegeSeparation to "no"
 since that feature doesn't make any sense on a system which doesn't
 differ between privileged and unprivileged users.

 The new ssh-host-config script also adds the /var/empty directory
 needed by privilege separation.  When creating the /var/empty directory
 by yourself, please note that in contrast to the README.privsep document
 the owner sshould not be "root" but the user which is running sshd.  So,
 in the standard configuration this is SYSTEM.  The ssh-host-config script
 chowns /var/empty accordingly.
 ===========================================================================

 ===========================================================================
 Important change since 3.0.1p1-2:

 This version introduces the ability to register sshd as service on
 Windows 9x/Me systems.  This is done only when the options -D and/or
 -d are not given.
 ===========================================================================

 ===========================================================================
 Important change since 2.9p2:

 Since Cygwin is able to switch user context without password beginning
 with version 1.3.2, OpenSSH now allows to do so when it's running under
 a version >= 1.3.2. Keep in mind that `ntsec' has to be activated to
 allow that feature.
 ===========================================================================

 ===========================================================================
 Important change since 2.3.0p1:

 When using `ntea' or `ntsec' you now have to care for the ownership
 and permission bits of your host key files and your private key files.
 The host key files have to be owned by the NT account which starts
 sshd. The user key files have to be owned by the user. The permission
 bits of the private key files (host and user) have to be at least
 rw------- (0600)!

 Note that this is forced under `ntsec' only if the files are on a NTFS
 filesystem (which is recommended) due to the lack of any basic security
 features of the FAT/FAT32 filesystems.
 ===========================================================================

 If you are installing OpenSSH the first time, you can generate global config
 files and server keys by running

    /usr/bin/ssh-host-config

 Note that this binary archive doesn't contain default config files in /etc.
 That files are only created if ssh-host-config is started.

 If you are updating your installation you may run the above ssh-host-config
 as well to move your configuration files to the new location and to
 erase the files at the old location.

 To support testing and unattended installation ssh-host-config got
 some options:

 usage: ssh-host-config [OPTION]...
 Options:
     --debug  -d            Enable shell's debug output.
     --yes    -y            Answer all questions with "yes" automatically.
     --no     -n            Answer all questions with "no" automatically.
     --cygwin -c <options>  Use "options" as value for CYGWIN environment var.
     --port   -p <n>        sshd listens on port n.
     --pwd    -w <passwd>   Use "pwd" as password for user 'sshd_server'.

 Additionally ssh-host-config now asks if it should install sshd as a
 service when running under NT/W2K. This requires cygrunsrv installed.

 You can create the private and public keys for a user now by running

   /usr/bin/ssh-user-config

 under the users account.

 To support testing and unattended installation ssh-user-config got
 some options as well:

 usage: ssh-user-config [OPTION]...
 Options:
     --debug      -d        Enable shell's debug output.
     --yes        -y        Answer all questions with "yes" automatically.
     --no         -n        Answer all questions with "no" automatically.
     --passphrase -p word   Use "word" as passphrase automatically.

 Install sshd as daemon via cygrunsrv.exe (recommended on NT/W2K), via inetd
 (results in very slow deamon startup!) or from the command line (recommended
 on 9X/ME).

 If you start sshd as deamon via cygrunsrv.exe you MUST give the
 "-D" option to sshd. Otherwise the service can't get started at all.

 If starting via inetd, copy sshd to eg. /usr/sbin/in.sshd and add the
 following line to your inetd.conf file:

 ssh stream tcp nowait root /usr/sbin/in.sshd sshd -i

 Moreover you'll have to add the following line to your
 ${SYSTEMROOT}/system32/drivers/etc/services file:

    ssh         22/tcp          #SSH daemon

 Please note that OpenSSH does never use the value of $HOME to
 search for the users configuration files! It always uses the
 value of the pw_dir field in /etc/passwd as the home directory.
 If no home diretory is set in /etc/passwd, the root directory
 is used instead!

 You may use all features of the CYGWIN=ntsec setting the same
 way as they are used by Cygwin's login(1) port:

   The pw_gecos field may contain an additional field, that begins
   with (upper case!) "U-", followed by the domain and the username
   separated by a backslash.
   CAUTION: The SID _must_ remain the _last_ field in pw_gecos!
   BTW: The field separator in pw_gecos is the comma.
   The username in pw_name itself may be any nice name:

     domuser::1104:513:John Doe,U-domain\user,S-1-5-21-...

   Now you may use `domuser' as your login name with telnet!
   This is possible additionally for local users, if you don't like
   your NT login name ;-) You only have to leave out the domain:

     locuser::1104:513:John Doe,U-user,S-1-5-21-...

 Note that the CYGWIN=ntsec setting is required for public key authentication.

 SSH2 server and user keys are generated by the `ssh-*-config' scripts
 as well.

 If you want to build from source, the following options to
 configure are used for the Cygwin binary distribution:

 	--prefix=/usr \
 	--sysconfdir=/etc \
 	--libexecdir='$(sbindir)' \
 	--localstatedir=/var \
 	--datadir='$(prefix)/share' \
 	--mandir='$(datadir)/man' \
 	--with-tcp-wrappers

 If you want to create a Cygwin package, equivalent to the one
 in the Cygwin binary distribution, install like this:

 	mkdir /tmp/cygwin-ssh
 	cd $(builddir)
 	make install DESTDIR=/tmp/cygwin-ssh
 	cd $(srcdir)/contrib/cygwin
 	make cygwin-postinstall DESTDIR=/tmp/cygwin-ssh
 	cd /tmp/cygwin-ssh
 	find * \! -type d | tar cvjfT my-openssh.tar.bz2 -

 You must have installed the zlib, the openssl-devel and the minires-devel
 packages to be able to build OpenSSH!

 Please send requests, error reports etc. to cygwin@cygwin.com.

 Have fun,

 Corinna Vinschen
 Cygwin Developer
 Red Hat Inc.
	This package describes important Cygwin specific stuff concerning OpenSSH.

	The binary package is usually built for recent Cygwin versions and might
	not run on older versions. Please check http://cygwin.com/ for information
	about current Cygwin releases.

	Build instructions are at the end of the file.

	===========================================================================
	Important change since 3.7.1p2-2:

	The ssh-host-config file doesn't create the /etc/ssh_config and
	/etc/sshd_config files from builtin here-scripts anymore, but it uses
	skeleton files installed in /etc/defaults/etc.

	Also it now tries hard to create appropriate permissions on files.
	Same applies for ssh-user-config.

	After creating the sshd service with ssh-host-config, it's advisable to
	call ssh-user-config for all affected users, also already exising user
	configurations. In the latter case, file and directory permissions are
	checked and changed, if requireed to match the host configuration.

	Important note for Windows 2003 Server users:
	---------------------------------------------

	2003 Server has a funny new feature. When starting services under SYSTEM
	account, these services have nearly all user rights which SYSTEM holds...
	except for the "Create a token object" right, which is needed to allow
	public key authentication :-(

	There's no way around this, except for creating a substitute account which
	has the appropriate privileges. Basically, this account should be member
	of the administrators group, plus it should have the following user rights:

	Create a token object
	Logon as a service
	Replace a process level token
	Increase Quota

	The ssh-host-config script asks you, if it should create such an account,
	called "sshd_server". If you say "no" here, you're on your own. Please
	follow the instruction in ssh-host-config exactly if possible. Note that
	ssh-user-config sets the permissions on 2003 Server machines dependent of
	whether a sshd_server account exists or not.
	===========================================================================

	===========================================================================
	Important change since 3.4p1-2:

	This version adds privilege separation as default setting, see
	/usr/doc/openssh/README.privsep. According to that document the
	privsep feature requires a non-privileged account called 'sshd'.

	The new ssh-host-config file which is part of this version asks
	to create 'sshd' as local user if you want to use privilege
	separation. If you confirm, it creates that NT user and adds
	the necessary entry to /etc/passwd.

	On 9x/Me systems the script just sets UsePrivilegeSeparation to "no"
	since that feature doesn't make any sense on a system which doesn't
	differ between privileged and unprivileged users.

	The new ssh-host-config script also adds the /var/empty directory
	needed by privilege separation. When creating the /var/empty directory
	by yourself, please note that in contrast to the README.privsep document
	the owner sshould not be "root" but the user which is running sshd. So,
	in the standard configuration this is SYSTEM. The ssh-host-config script
	chowns /var/empty accordingly.
	===========================================================================

	===========================================================================
	Important change since 3.0.1p1-2:

	This version introduces the ability to register sshd as service on
	Windows 9x/Me systems. This is done only when the options -D and/or
	-d are not given.
	===========================================================================

	===========================================================================
	Important change since 2.9p2:

	Since Cygwin is able to switch user context without password beginning
	with version 1.3.2, OpenSSH now allows to do so when it's running under
	a version >= 1.3.2. Keep in mind that `ntsec' has to be activated to
	allow that feature.
	===========================================================================

	===========================================================================
	Important change since 2.3.0p1:

	When using `ntea' or `ntsec' you now have to care for the ownership
	and permission bits of your host key files and your private key files.
	The host key files have to be owned by the NT account which starts
	sshd. The user key files have to be owned by the user. The permission
	bits of the private key files (host and user) have to be at least
	rw------- (0600)!

	Note that this is forced under `ntsec' only if the files are on a NTFS
	filesystem (which is recommended) due to the lack of any basic security
	features of the FAT/FAT32 filesystems.
	===========================================================================

	If you are installing OpenSSH the first time, you can generate global config
	files and server keys by running

	/usr/bin/ssh-host-config

	Note that this binary archive doesn't contain default config files in /etc.
	That files are only created if ssh-host-config is started.

	If you are updating your installation you may run the above ssh-host-config
	as well to move your configuration files to the new location and to
	erase the files at the old location.

	To support testing and unattended installation ssh-host-config got
	some options:

	usage: ssh-host-config [OPTION]...
	Options:
	--debug -d Enable shell's debug output.
	--yes -y Answer all questions with "yes" automatically.
	--no -n Answer all questions with "no" automatically.
	--cygwin -c <options> Use "options" as value for CYGWIN environment var.
	--port -p <n> sshd listens on port n.
	--pwd -w <passwd> Use "pwd" as password for user 'sshd_server'.

	Additionally ssh-host-config now asks if it should install sshd as a
	service when running under NT/W2K. This requires cygrunsrv installed.

	You can create the private and public keys for a user now by running

	/usr/bin/ssh-user-config

	under the users account.

	To support testing and unattended installation ssh-user-config got
	some options as well:

	usage: ssh-user-config [OPTION]...
	Options:
	--debug -d Enable shell's debug output.
	--yes -y Answer all questions with "yes" automatically.
	--no -n Answer all questions with "no" automatically.
	--passphrase -p word Use "word" as passphrase automatically.

	Install sshd as daemon via cygrunsrv.exe (recommended on NT/W2K), via inetd
	(results in very slow deamon startup!) or from the command line (recommended
	on 9X/ME).

	If you start sshd as deamon via cygrunsrv.exe you MUST give the
	"-D" option to sshd. Otherwise the service can't get started at all.

	If starting via inetd, copy sshd to eg. /usr/sbin/in.sshd and add the
	following line to your inetd.conf file:

	ssh stream tcp nowait root /usr/sbin/in.sshd sshd -i

	Moreover you'll have to add the following line to your
	${SYSTEMROOT}/system32/drivers/etc/services file:

	ssh 22/tcp #SSH daemon

	Please note that OpenSSH does never use the value of $HOME to
	search for the users configuration files! It always uses the
	value of the pw_dir field in /etc/passwd as the home directory.
	If no home diretory is set in /etc/passwd, the root directory
	is used instead!

	You may use all features of the CYGWIN=ntsec setting the same
	way as they are used by Cygwin's login(1) port:

	The pw_gecos field may contain an additional field, that begins
	with (upper case!) "U-", followed by the domain and the username
	separated by a backslash.
	CAUTION: The SID _must_ remain the _last_ field in pw_gecos!
	BTW: The field separator in pw_gecos is the comma.
	The username in pw_name itself may be any nice name:

	domuser::1104:513:John Doe,U-domain\user,S-1-5-21-...

	Now you may use `domuser' as your login name with telnet!
	This is possible additionally for local users, if you don't like
	your NT login name ;-) You only have to leave out the domain:

	locuser::1104:513:John Doe,U-user,S-1-5-21-...

	Note that the CYGWIN=ntsec setting is required for public key authentication.

	SSH2 server and user keys are generated by the `ssh-*-config' scripts
	as well.

	If you want to build from source, the following options to
	configure are used for the Cygwin binary distribution:

	--prefix=/usr \
	--sysconfdir=/etc \
	--libexecdir='$(sbindir)' \
	--localstatedir=/var \
	--datadir='$(prefix)/share' \
	--mandir='$(datadir)/man' \
	--with-tcp-wrappers

	If you want to create a Cygwin package, equivalent to the one
	in the Cygwin binary distribution, install like this:

	mkdir /tmp/cygwin-ssh
	cd $(builddir)
	make install DESTDIR=/tmp/cygwin-ssh
	cd $(srcdir)/contrib/cygwin
	make cygwin-postinstall DESTDIR=/tmp/cygwin-ssh
	cd /tmp/cygwin-ssh
	find * \! -type d \| tar cvjfT my-openssh.tar.bz2 -

	You must have installed the zlib, the openssl-devel and the minires-devel
	packages to be able to build OpenSSH!

	Please send requests, error reports etc. to cygwin@cygwin.com.

	Have fun,

	Corinna Vinschen
	Cygwin Developer
	Red Hat Inc.