UPDATE 2009-11-20: the Match keyword option has been resynced so it's possible to use ChrootDirectory selectively on specific user accounts, for example.

I resynced the ChrootDirectory option from OpenSSH to SunSSH, and pushed the change to the repository today. It wasn't a straightforward resync since we have different privilege separation code. I also found a few very minor issues in the OpenSSH code, and filed bugs with patches (1562, 1564, and 1566).

If you want to use the option, create an empty root-owned directory with proper permissions (no group/other writable along the whole path, so don't even use /tmp, for example, since we don't accept the sticky bit). After that, set ChrootDirectory option to it, and check that the Subsystem option contains internal-sftp. This internal SFTP will be the default in the new OpenSolaris/Nevada installations but we do not change any existing confirations on upgrades. It's quite probable you will have an existing config file with the following line:

Subsystem       sftp    /usr/lib/ssh/sftp-server

If you run the server in the debug mode (/usr/lib/ssh/sshd -p 2222 -ddd) with the chroot directory option set and the line as displayed above, you would see something like this in the server's output after you try to connect (sftp -o Port=2222 the-hostname):

subsystem request for sftp
subsystem: cannot stat /usr/lib/ssh/sftp-server under
    chroot directory /var/root/chroot/: No such file
    or directory
subsystem: please see the Subsystem option in
    sshd_config(4) for an explanation of 'internal-sftp'.
subsystem request for sftp failed, subsystem not found

Just change /usr/lib/ssh/sftp-server to internal-sftp, restart the SSH server (svcadm restart ssh), and you will be fine. The chroot directory option does work with the plain SSH connection or with the /usr/lib/ssh/sftp-server binary as well. However, you must provide some files in that directory, because SSH server will exec(2)'s the shell or the SFTP server process after calling chroot(2). My test chroot directory has the same list of files but check that the connecting user has the same shell, bash, as mine. If not, the list of libraries will probably be different, use ldd(1) to get your list. The list follows:

./bin/bash
./bin/ls
./lib/libcurses.so.1
./lib/libsocket.so.1
./lib/libnsl.so.1
./lib/libdl.so.1
./lib/libc.so.1
./lib/libmp.so.2
./lib/libmd.so.1
./lib/libscf.so.1
./lib/libuutil.so.1
./lib/libgen.so.1
./lib/libm.so.2
./lib/libresolv.so.2
./lib/libcrypto.so.0.9.8
./lib/libz.so.1
./lib/libsecdb.so.1
./lib/libmapmalloc.so.1
./lib/libcrypt.so.1
./lib/libsec.so.1
./usr/lib/ld.so.1

and I can log in via plain SSH, and run ls(1) command:

-bash-3.2$ ls
bin  lib  usr
-bash-3.2$ pwd
/

Note that the external SFTP server process would need yet another list of files, and at least one device - /dev/null, but there is really no reason to use the external binary when there is the above mentioned internal-sftp mode. Nothing is exec()'ed, the SFTP server loop is run inside of the existing SSH server process, and that means that no other files are needed in the chroot directory. If you are still not convinced then know that the SFTP server code used is the same. In the in-process implementation, the server uses the SFTP object code that is linked directly to the SSH server binary while in the external case the code is wrapped in an additional few lines to create an independent binary.

The sshd_config(4) manual page will be updated but we are in the queue so I'm not sure it will get to the same Nevada build as the code change, which is 112. It may get to 113. From that reason, see the change here:

+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 is 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 user's 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).  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. 

As a last note, as of now, we do not plan to backport this to Solaris 10.

I have generated a PKCS#11 patch for OpenSSL 0.9.8l. It includes one new feature I have recently integrated into Nevada - RSA Keys by Reference. You can read the README here, and download the PKCS#11 patch.

As a test I've built the code on Solaris 10 and one Linux distro (which identified itself as GNU/Linux, I have no idea which distro was that). I had to make a couple of modifications since other systems do not have getpassphrase() function, and Linux distros have no strlcpy() function (because GNU C library has none). Hopefully I have not broken anything.

If you plan to use the patch, do not forget to check out examples and the PKCS#11 URI format in the presentation for the project. As usual, if you find problems with the patch, let me know please. And of course, if you find it really useful, you can say that as well :-)

The man page will be updated soon but before that gets to a public build it will take some time. So, below is the current draft change for the openssl(5) man page. Note that the man page in section 5 is for OpenSSL in Solaris, the one in section 1 is the original man page from the OpenSSL project. Obviously, we ship both. Use "man -s 5 openssl" to see the Sun's one, or "man -a" if unsure about sections.

openssl(5) planned addition:

  Accessing RSA Keys in PKCS#11 Keystores

     OpenSSL can access RSA keys in PKCS#11 keystores using the
     following functions of the ENGINE API:

       EVP_PKEY *ENGINE_load_private_key(ENGINE *e,
                const char *key_id, UI_METHOD *ui_method,
                void *callback_data)

       EVP_PKEY *ENGINE_load_public_key(ENGINE *e,
                const char *key_id, UI_METHOD *ui_method,
                void *callback_data)

     key_id, formerly for filenames only, can be now also set to
     a PKCS#11 URI. The EVP_PKEY structure is newly allocated and
     caller is responsible to free the structure later. To avoid
     clashes with existing filenames, "file://" prefix for
     filenames is now also accepted but only when the PKCS#11
     engine is in use. The PKCS#11 URI specification follows:

        pkcs11:[token=<label>][;manuf=<label>][;serial=<label>]
               [;model=<label>][;object=<label>]
               [;objecttype=(public|private|cert)]
               [;passphrasedialog=(builtin|exec:<file>)]

     The ordering of keywords is not significant. The PKCS#11
     engine uses the keystore for the slot chosen for public key
     operations whic is metaslot on a standardly configured
     machine. Currently, the PKCS#11 engine ignores "objecttype"
     keyword. The only mandatory keyword is "object" which is
     the key object label. For information on how to use a
     different, possibly hardware, keystore with metaslot see
     libpkcs11(3LIB).

     The token PIN is provided via "passphrasedialog" keyword and
     is either read from the terminal ("builtin") or from the
     output of an external command ("exec:<file>"). The PIN is
     used to log into the token and by default is deleted from
     the memory then. The keyword "pin" is intentionally not
     provided due to inherent security problems of possible use
     of a password in the process arguments.

     Due to fork safety issues the application must re-login if
     the child continues to use the PKCS#11 engine. It is done
     inside of the engine automatically if fork is detected and
     in that case, "exec:<file>" option of the "passphrasedialog"
     keyword can be used. Alternatively, an enviroment variable
     OPENSSL_PKCS11_PIN_CACHING_POLICY can be used to allow the
     PIN to be cached in memory and reused in the child. It can
     be set to "none" which is the default, "memory" to store
     the PIN in memory, and "mlocked-memory" keep the PIN in a
     locked page via mlock(3C). Note that PRIV_PROC_LOCK_MEMORY
     privilege is required in that case.

     Sensitive parts of private keys are never read from the
     token to the process memory no matter whether the key is
     tagged with sensitive flag or not. The PKCS#11 engine uses
     the public compoments as a search key to get a PKCS#11
     object handle to the private key.

     Note that in order to use the RSA keys by reference, high
     level API functions must be used, like RSA_public_decrypt(),
     EVP_PKEY_set1_RSA(), or EVP_SignInit(). Low level functions
     might go around the engine and thus fail to make use of the
     feature.

  Additional Documentation

      Extensive additional documentation for  OpenSSL  modules  is
      available       in      the      /usr/share/man/man1openssl,
      /usr/share/man/man3openssl, /usr/share/man/man5openssl,  and
      /usr/share/man/man7openssl directories.

      To view the license terms, attribution,  and  copyright  for
      OpenSSL, see /var/sadm/pkg/SUNWopensslr/install/copyright.

EXAMPLES

     Example 1: generate and print a public key stored in an
                already initilized PKCS#11 keystore. Note the
                use of "-engine pkcs11" and "-inform e".

        $ pktool gencert keystore=pkcs11 label=mykey \
            subject="CN=test" keytype=rsa keylen=1024 serial=01
        $ openssl rsa -in \
            "pkcs11:object=mykey;passphrasedialog=builtin" \
            -pubout -text -engine pkcs11 -inform e

UPDATE 2009-11-19: I have generated the PKCS#11 patch for 0.9.8l.

I have just done my putback to the SFW gate for the "RSA Keys by Reference" project. It will be part of the Nevada build 129 and the next version of OpenSolaris. The CR was "6479874 OpenSSL should support RSA key by reference/hardware keystores". With this code, applications can access RSA keys stored in PKCS#11 tokens through the existing OpenSSL API functions ENGINE_load_private_key() and ENGINE_load_public_key(), without any need for the private keys to be loaded to memory. The code was based on alpha code I wrote more than 2 years ago, and which was quickly part of the PKCS#11 patch. The code was really alpha, more proof of concept that something usable in the production environment. It took me another couple of months to mold it into the current form that could be commited to the repository.

Part of the project was a specification of the PKCS#11 URI. Unfortunately I do not have many cycles right now for this blog entry so if you are interested or if you have any questions, please read slides I wrote for the project presentation I gave here at Sun to our team. It has enough details and a few examples. I'm sure I'll get back here with some multithreaded C code and possibly more information.

There is no patch available yet against the regular OpenSSL tarball distribution. I need some time to take care of other stuff I did not have time for recently because I have been finishing up this project. I'd like to generate it soon though.