Template Version: @(#)sac_nextcase 1.66 04/17/08 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
ChrootDirectory option for SunSSH server
1.2. Name of Document Author/Supplier:
Jan Pechanec
1.3. Date of This Document:
2009-03-04
1.4. Name of Major Document Customer(s)/Consumer(s):
1.4.2. The ARC(s) you expect to review your project:
PSARC
1.4.4. The name of your business unit:
Security
1.5. Email Aliases:
1.5.1. Responsible Manager: Anup.Sekhar at Sun.COM
1.5.2. Responsible Engineer: Jan.Pechanec at Sun.COM
1.5.4. Interest List: security-discuss at opensolaris.org
2. Project Summary
2.1. Project Description:
The goal of this project is to implement the ChrootDirectory option
according to how OpenSSH implemented it in the 5.0p1 version (released
2008-04-03). Using this server side option the server will chroot the
connected clients after the authentication is over to the directory
specified in the option. Part of the project is to implement an
in-process SFTP server (aka internal SFTP) which greatly simplifies
configurations using the ChrootDirectory option.
We fully follow how ChrootDirectory is used by OpenSSH so users that use
this features in OpenSSH should be able to use it with SunSSH without
any configuration changes.
2.2. Risks and Assumptions:
None.
3. Business Summary
3.1. Problem Area:
Customers want this feature that they can find in OpenSSH.
3.3. Business Justification:
There are 14 service records with 5043377.
4. Technical Description:
4.1. Details:
ChrootDirectory path specifies that the server will call chroot(2) on it
after the authentication is over. This feature is about the SSH server
only.
All components of the chroot path MUST be root owned and NOT writable by
any other user or group otherwise the connection fails.
ChrootDirectory works with both the SFTP and plain SSH connections.
With the in-process SFTP server implementation that is part of this
project, there is NO need for other configuration of the chrooted
directory. However, with the plain SSH or the external SFTP
implementation, one has to properly populate the chroot directory with
(at least) a user's shell and all its shared libraries, the dynamic
linker, and possibly terminal databases and devices like /dev/null etc.
The in-process SFTP server is configured using the "internal-sftp"
keyword in place of the SFTP server binary:
Subsystem sftp internal-sftp
If the ChrootDirectory is used with the external SFTP server binary
(/usr/lib/ssh/sftp-server) or with the plain SSH connection without
a properly populated chroot directory, the connection fails. The manual
page draft below discusses the non in-process SFTP case and the need to
prepare the chroot directory beforehand.
The "internal-sftp" will be the new default value for the "sftp"
subsystem already configured in the "Subsystem" option delivered in
/etc/ssh/sshd_config but we will NOT update the existing server
configurations upon the system upgrades.
After the chroot(2) is called, the SSH server tries to find the user's
home directory relatively under the chrooted environment and chdir(2) to
it but the failure to do so is NOT considered an error. In addition to
that, there are 3 tokes that can be used in the ChrootDirectory path. %u
is replaced by the current user's name, %h is replaced by the user's
home directory, and %% is replaced by literal %.
A special ChrootDirectory=none configuration effectively disables this
option and has the same effect as if the option was not set at all.
While I do not think it is needed I follow the OpenSSH implementation so
that we do not confuse the customers that used the ChrootDirectory
option before with OpenSSH.
The implementation will partially use the OpenSSH code. Some code
written as part of the project will be specific to SunSSH since we have
a different privilege separation code that is affected as well.
4.2. Bug/RFE Number(s):
the project implements this RFE:
5043377 provide chroot capability in SunSSH
I'll fix following SunSSH CRs as part of this project:
6809398 default PATH in SunSSH is missing important directories
6810759 remove md5crypt.c from SunSSH since it's not used
A new CR was filed against the STC-2 SSH test suite and it's integration
to STC-2 will part of the project:
6809406 ChrootDirectory option should have its own test case in
the SSH test suite
4.5. Interfaces:
- we do NOT add any new command line options
- we add a new ChrootDirectory option keyword to the server, for use in
the sshd_config file, or with the "-o" command line option with
sshd(1m)
- we change the default Subsystem configuration in the new installations
only, so that the in-process SFTP implementation is used instead of
the external one. The functionality and the interface to the user will
remain unchanged.
4.6. Doc Impact:
Manual page sshd_config(4) will be changed. Draft follows:
+ChrootDirectory
+
+ Specifies a path to chroot(2) to after authentication.
+ This path, and all its components, must be root owned
+ directories that are not writable by any other user or
+ group.
+
+ The server always tries to change to the user's home
+ directory locally under the chrooted environment but a
+ failure to do so it not considered an error. In addition
+ to that, the path may contain the following tokens that
+ are expanded at runtime once the connecting user has
+ been authenticated: %% is replaced by a literal '%', %h
+ is replaced by the home directory of the user being
+ authenticated, and %u is replaced by the username of
+ that user.
+
+ The ChrootDirectory must contain the necessary files and
+ directories to support the users' session. For an
+ interactive SSH session this requires at least a user's
+ shell, shared libraries needed by the shell, dynamic
+ linker, and possibly basic /dev nodes such as null(4),
+ zero(4), stdin(4), stdout(4), stderr(4), random(4) and
+ tty(4) devices, Additionaly, terminal databases are
+ needed for screen oriented applications. For file
+ transfer sessions using ``sftp'' with the SSH protocol
+ version 2, no additional configuration of the
+ environment is necessary if the in-process sftp server
+ is used (see Subsystem for details).
+
+ The default is not to chroot(2).
+
+
Subsystem
Configures an external subsystem (for example, a file
transfer daemon). Arguments should be a subsystem name
and a command to execute upon subsystem request. The
command sftp-server(1M) implements the sftp file
- transfer subsystem. By default, no subsystems are
+ transfer subsystem.
+
+ Alternately the name ``internal-sftp'' implements an
+ in-process ``sftp'' server. This may simplify
+ configurations using ChrootDirectory to force a different
+ filesystem root on clients.
+
+ By default, no subsystems are
defined. This option applies to protocol version 2 only.
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: Automatic
6.6. ARC Exposure: open
