Added p11-kit remoting page in manual

3 files changed, 255 insertions, 0 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index a3c6b66..8bee2f8 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -87,6 +87,7 @@ content_files=p11-kit-config.xml p11-kit-sharing.xml \
 	p11-kit-devel.xml \
 	p11-kit-proxy.xml \
 	p11-kit-trust.xml \
+	p11-kit-remoting.xml \
 	p11-kit.xml \
 	pkcs11.conf.xml \
 	trust.xml \
diff --git a/doc/manual/p11-kit-docs.xml b/doc/manual/p11-kit-docs.xml
index 77ff318..c7f3400 100644
--- a/doc/manual/p11-kit-docs.xml
+++ b/doc/manual/p11-kit-docs.xml
@@ -14,6 +14,7 @@
 	<xi:include href="p11-kit-config.xml"/>
 	<xi:include href="p11-kit-sharing.xml"/>
 	<xi:include href="p11-kit-proxy.xml"/>
+	<xi:include href="p11-kit-remoting.xml"/>
 	<xi:include href="p11-kit-trust.xml"/>
 
 	<chapter xml:id="tools">
diff --git a/doc/manual/p11-kit-remoting.xml b/doc/manual/p11-kit-remoting.xml
new file mode 100644
index 0000000..f7689f8
--- /dev/null
+++ b/doc/manual/p11-kit-remoting.xml
@@ -0,0 +1,253 @@
+<?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>