libpam-chroot for Debian
------------------------

This package has not been thoroughly tested by Debian (security wise),
however, it is provided in the hope that it will be useful for some
environments.

RedHat distributes a pam_chroot.so module along with its PAM modules
(last I looked version 0.74) however the source code is not the same
(but might be derived from the same base).

To use this module you need to:

a) modify a PAM-aware application by editing it's file in /etc/pam.d/
For local access this application could be login, xdm, kdm, su or
sudo.  For remote access this application could be ssh, ftp..  Try
adding (as the last line):

# Test Chroot features
session    required   pam_chroot.so debug
 
(the debug option will printout progress of the module to syslog. Debug
messages go to authpriv.notice)

b) Set the proper chroot environment for each user.
(this is quite tricky if you ask me :) For an example of how
to setup an environment for 'login' take a look at the files under 
/usr/share/doc/libpam-chroot/examples/.

Other applications might be more difficult to setup (the more complex
the application the worst).

If you find it difficult to setup a complex chroot you might want to
setup a minimal version of a Debian installation (using 'debootstrap')
and then removing those applications unneded for your environment
(specifically, remove _all_ setuid applications). You might even want
to use some automatic systems to setup chroots like 'makejail'.

c) Configure /etc/security/chroot.conf

Detailed info:
--------------
(based on the RedHat's README for Linux-PAM 0.74)

Operation:
When the calling application attempts to open a session, pam_chroot
opens /etc/security/chroot.conf and searches for a line of the form:

user directory

where the "user" listed can be either a real username or a 
regular expression (if you are using the 'use_regex' option).  If the
PAM_USER for whom the session is being opened matches, 
the module will attempt to chroot() to the given directory.

Optional arguments:
"debug"		Log debug messages to syslog.
"onerr="	Values can be "succeed" or "fail".  The action to take if
		the configuration file cannot be opened, the chroot()
		fails, or the user does not match any of the expressions
		listed in the configuration file.  Default is "succeed".

(for more options see /usr/share/doc/libpam-chroot/options)

Other Notes: The calling application must be executing with root
privileges in order to be able to chroot() at all (see the chroot(2)
manpage).

Warning: If configured incorrectly, this module may potentially render
the service unusable and, under some circumstances, pose a security
risk.

Setting up OpenSSH with libpam-chroot
-------------------------------------

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! WARNING !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
NOTE: OpenSSH supports, since the 4.9 release, the definition of
chrooted enviroments. For more information see the 'ChrootDirectory'
directive in sshd_config (5). 

Setting up OpenSSH libpam-chroot is *not* recommended and most likely will not
work. The following information is provided for those users that want to tinker
with pam-chroot and SSH.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! WARNING !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


Many systems want to setup a restricted remote access to a system in
which users are confined to their user directories, but are unable to
"see" the whole system. If you want to develop this using OpenSSH 
and libpam-chroot you will need to:

0) Setup a chroot environment for your users. Make sure that
environment includes the standard tools they will need (like their
shell) and that it also includes a /dev directory with the /dev/ptmx
and /dev/pty* devices and the /dev/pts/ subdirectory (runnig MAKEDEV
in the /dev directory of the chrooted environment should be
sufficient).

Note: This environment is similar to the 'login' environment detailed
under /usr/share/doc/libpam-chroot/examples

1) Add this line to /etc/pam.d/ssh (should be the last line)
 session     required     pam_chroot.so debug 

2) Configure /etc/security/chroot.conf so that the users you determine
  are chrooted to the directory you setup previously. You might want to have
  independent directories for different users so that they will not be
  able to see neither the whole system nor each other's.

3) Depending on your OpenSSH version it might work or not. Since 3.6.1p2
   the do_pam_session() function is called after sshd has dropped privs,
   since chroot() needs root priviledges it will not work with
   Privilege separation on. In newer OpenSSH versions, however, the
   PAM code has been modified and do_pam_session is called before
   dropping priviledges so it will work even with Privilege separation.

If you don't need to disable Privilege Separation you will need an /etc/passwd
with the user's UID inside the chroot for Privilege Separation to work
properly.

If you have Privilege Separation set to on and your OpenSSH version
does not behave properly you will need to disable it. If you don't,
users that try to connect to your server and would be chrooted by 
this module will see this:

 $ ssh -l user server
 user@server's password:
 Connection to server closed by remote host.
 Connection to server closed. 

 This is because the ssh daemon, which is running as 'sshd', is not
 be able to make the chroot() system call. To disable Privilege separation
 you have to modify the /etc/ssh/sshd_config configuration file.
 Change the (default) line:

 UsePrivilegeSeparation yes

 to

 UsePrivilegeSeparation no

Notice that this will lower the security of your system since the
OpenSSH server will run as 'root' user. This means that if a remote
attack is found against OpenSSH an attacker will get 'root'
priviledges instead of 'sshd', thus compromising the whole system.

If you are using a kernel that implements Mandatory Access Control
(RSBAC/SElinux) you can avoid changing this configuration just by
granting the 'sshd' user priviledges to make the chroot() system call.

Of course, you could just chroot() the daemon in the init.d script to
the chroot environment you have setup, but then you wouldn't need
pam-chroot at all.

4) In order for chroots to work with newer OpenSSH versions the chroot
directory of a user needs to include both the /proc filesystem and
the /dev/pts

    - If /proc is not mounted in the chroot, SSH access will be interrupted
      with the message:

      Connection reset by peer
      Connection to <server-ip> closed.

      To mount /proc do the following:
      mount -t proc /proc <chroot_directory>/proc

    - If /dev/pts is not mounted, the SSH login will freeze after
      authentication with the message:

     PTY allocation request failed on channel 0

      To mount /dev do the following:
      mount --rbind /dev <chroot_directory>/dev


 --
 Javier Fernandez-Sanguino <jfs@debian.org>
 Thu, 03 Jun 2021 13:26:58 +0200


