--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter xml:id="remoting">
+ <title>Remoting / Forwarding</title>
+
+ <para>Smartcards or hardware security modules (HSM) are technologies to
+ keep private keys on devices physically isolated to a device only available
+ to the user. That way only the intended user can use that device to authenticate,
+ authorize or perform other functions that involve the private keys. These come
+ usually in the form of a USB device or token which is plugged into the local computer.
+ </para>
+ <para>In modern "cloud" computing, it is often desirable to virtually transfer such
+ a device on remote servers. For example, one can sign software or documents on a remote
+ server, use the local smart card to authorize itself to Kerberos, or any other
+ possible use. There are various approaches to tackle that problem, and on different
+ levels of the smart card application stack. It is possible to forward the USB
+ device holding the smart card, or forward the lower-level PC/SC protocol which
+ some smart cards talk, or forward the high-level interface used to communicate
+ with smart cards, the PKCS#11 interface.</para>
+
+ <para>To address that problem, in p11-kit, we allow the forwarding of
+ the higher level smart card interface, PKCS#11. In the following paragraphs
+ we describe the approach and tools needed to perform that forwarding over SSH
+ secure communication channels.</para>
+
+<refsect1 id="remoting-scenario">
+ <title>Scenario</title>
+
+ <para>We assume having a local workstation, and a remote server. On the local
+ computer we have inserted a smart card, in our examples we use a Nitrokey
+ card with the OpenSC drivers. We will forward the card
+ from the workstation to the remote server.</para>
+</refsect1>
+
+<refsect1 id="remoting-setup">
+ <title>Setting up the PKCS#11 forwarding server on a local client</title>
+
+ <para>To forward a smartcard to a remote server, we first need to identify which
+ smartcards are available. To list the smartcards currently attached to the local
+ computer, use the p11tool command from the gnutls package. For example:
+ </para>
+
+<programlisting>
+$ p11tool --list-tokens
+...
+Token 6:
+ URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=www.CardContact.de;serial=DENK0000000;token=UserPIN%20%28Daiki%27s%20token%29
+ Label: UserPIN (Daiki's token)
+ Type: Hardware token
+ Manufacturer: www.CardContact.de
+ Model: PKCS#15 emulated
+ Serial: DENK0000000
+ Module: opensc-pkcs11.so
+...
+</programlisting>
+
+ <para>This is the entry for the card we'd like to forward to remote system. The important
+ pieces are the 'pkcs11:' URL listed above, and the module name. Once we determine which
+ smartcard to forward, we expose it to a local Unix domain socket, with the following
+ p11-kit server command.
+ </para>
+<programlisting>
+$ p11-kit server --provider /usr/lib64/pkcs11/opensc-pkcs11.so "pkcs11:model=PKCS%2315%20emulated;manufacturer=www.CardContact.de;serial=DENK0000000;token=UserPIN%20%28Daiki%27s%20token%29"
+</programlisting>
+
+ <para>Here we provide to the server the module location (optional) with the --provider
+ option, as well as the URL of the card. We copied the values from the Module and URL
+ lines of the p11tool output above. When the p11-kit server command starts, it will
+ print the address of the PKCS#11 unix domain socket and the process ID of the server.
+ </para>
+
+<programlisting>
+P11_KIT_SERVER_ADDRESS=unix:path=/run/user/12345/p11-kit/pkcs11-12345
+P11_KIT_SERVER_PID=12345
+</programlisting>
+
+ <para>For later use, set the variables output by the tool on your shell prompt
+ (e.g., copy and paste them or call the above p11-kit server command line with
+ <literal>eval $(p11-kit server ...)</literal>).
+ </para>
+
+</refsect1>
+
+<refsect1 id="remoting-forwarding-socket">
+ <title>Forwarding and using the PKCS#11 Unix socket on the remote server</title>
+
+ <para>On the remote server, we will initially forward the previously generated PKCS#11
+ unix socket, and then access the smart card through it. To access the forwarded socket
+ as if it were a smart card, a dedicated PKCS#11 module p11-kit-client.so is provided as
+ part of the p11-kit-server package.
+ </para>
+</refsect1>
+
+<refsect1 id="remoting-forwarding-socket-prep">
+ <title>Preparing the remote system for PKCS#11 socket forwarding</title>
+
+ <para>One important detail you should be aware of, is the file system location of the
+ forwarded socket. By convention, the p11-kit-client.so module utilizes the "user runtime
+ directory", managed by systemd; the directory is created when a user logs in, and removed
+ upon logout, so that the user doesn't need to manually clean up the socket file.
+ </para>
+
+ <para>To locate your user runtime directory, do:
+ </para>
+
+<programlisting>
+$ systemd-path user-runtime
+/run/user/1000
+</programlisting>
+
+ <para>The <literal>p11-kit-client.so</literal> module looks for the socket file under a
+ subdirectory (<literal>/run/user/1000/p11-kit</literal> in this example). To enable
+ auto-creation of the directory, do the following.
+ </para>
+
+<programlisting>
+$ systemctl --user enable p11-kit-client.service
+</programlisting>
+</refsect1>
+
+<refsect1 id="remoting-finally-forwarding">
+ <title>Forwarding the PKCS#11 socket</title>
+
+ <para>We will use ssh to forward the local PKCS#11 unix socket to the remote server.
+ Following the p11-kit-client convention, we will forward the socket to the remote user
+ run-time path so that cleaning up on disconnect is not required. The remote location
+ of the run-time path can be obtained as follows.
+ </para>
+
+<programlisting>
+$ ssh [user]@[remotehost] systemd-path user-runtime
+/run/user/1000
+</programlisting>
+
+ <para>The number at the end of the path above is your user ID in that system
+ (and thus will vary from user to user). You can now forward the Unix domain socket
+ with the -R option of the ssh command, after replacing the example path with the
+ actual run-time path.
+ </para>
+
+<programlisting>
+$ ssh -R /run/user/[userID]/p11-kit/pkcs11:${P11_KIT_SERVER_ADDRESS#*=} [user]@[remotehost]
+</programlisting>
+
+ <para>After successfully logging in to the remote host, you can use the forwarded
+ smartcard as if it were directly connected to the server using the
+ <literal>p11-kit-client.so</literal>. Note that if any error occurs during the forwarding
+ setup, you will see something like this on your terminal:
+ </para>
+
+<programlisting>
+Warning: remote port forwarding failed for listen path /run/user/...
+</programlisting>
+</refsect1>
+
+<refsect1 id="remoting-using">
+ <title>Using the forwarded PKCS#11 socket</title>
+
+ <para>Let's first make sure the smart card works on the remote system, by listing it:
+ </para>
+
+<programlisting>
+$ ls -l /run/user/1000/p11-kit/pkcs11
+
+$ p11tool --provider /usr/lib64/pkcs11/p11-kit-client.so --list-tokens
+...
+Token 0:
+ URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=www.CardContact.de;serial=DENK0000000;token=UserPIN%20%28Daiki%27s%20token%29
+ Label: UserPIN (Daiki's token)
+ Type: Hardware token
+ Manufacturer: www.CardContact.de
+ Model: PKCS#15 emulated
+ Serial: DENK0000000
+ Module: (null)
+...
+</programlisting>
+
+ <para>We can similarly generate, copy objects or test certificates to the card using
+ the same command. Any applications which support PKCS#11 can perform cryptographic
+ operations through the client module.
+ </para>
+</refsect1>
+
+<refsect1 id="remoting-registering">
+ <title>Registering the client module for use with OpenSSL and GnuTLS apps</title>
+
+ <para>To utilize the p11-kit-client module with OpenSSL (via engine_pkcs11 provided
+ by the libp11 package) and GnuTLS applications, you have to register it in
+ p11-kit. To do it for the current user, use the following commands:
+ </para>
+
+<programlisting>
+$ mkdir .config/pkcs11/modules/
+$ echo "module: /usr/lib64/pkcs11/p11-kit-client.so" >.config/pkcs11/modules/p11-kit-client.module
+</programlisting>
+
+ <para>Once this is done both OpenSSL and GnuTLS applications should work, for example:
+ </para>
+
+<programlisting>
+$ URL="pkcs11:model=PKCS%2315%20emulated;manufacturer=www.CardContact.de;serial=DENK0000000;token=UserPIN%20%28Daiki%27s%20token%29"
+
+# Generate a key using gnutls’ p11tool
+$ p11tool --generate-ecc --login --label test-key "$URL"
+
+# generate a certificate request with the previous key using openssl
+$ openssl req -engine pkcs11 -new -key "$URL;;object=test-key;type=private;pin-value=XXXX" \
+ -keyform engine -out req.pem -text -subj "/CN=Test user"
+</programlisting>
+
+ <para>Note that the token URL remains the same in the forwarded system as in the original one.
+ </para>
+
+</refsect1>
+
+<refsect1 id="remoting-ssh">
+ <title>Using the client module with OpenSSH</title>
+
+ <para>To re-use the already forwarded smartcard for authentication with another remote host, you can run ssh and provide the -I option with p11-kit-client.so. For example:
+ </para>
+
+<programlisting>
+$ ssh -I /usr/lib64/pkcs11/p11-kit-client.so [user]@[anotherhost]
+</programlisting>
+</refsect1>
+
+<refsect1 id="remoting-nss">
+ <title>Using the client module with NSS applications</title>
+
+ <para>To register the forwarded smartcard in NSS applications, you can set it up with
+ the modutil command, as follows.
+ </para>
+
+<programlisting>
+$ sudo modutil -dbdir /etc/pki/nssdb -add p11-kit-client -libfile /usr/lib64/pkcs11/p11-kit-client.so
+
+$ modutil -dbdir /etc/pki/nssdb -list
+...
+ 3. p11-kit-client
+ library name: /usr/lib64/pkcs11/p11-kit-client.so
+ uri: pkcs11:library-manufacturer=OpenSC%20Project;library-description=OpenSC%20smartcard%20framework;library-version=0.17
+ slots: 1 slot attached
+ status: loaded
+
+ slot: Nitrokey Nitrokey HSM (010000000000000000000000) 00 00
+ token: UserPIN (Daiki's token)
+ uri: pkcs11:token=UserPIN%20(Daiki's%20token);manufacturer=www.CardContact.de;serial=DENK0000000;model=PKCS%2315%20emulated
+</programlisting>
+</refsect1>
+
+
+</chapter>
projects / p11-kit / commitdiff