diff options
Diffstat (limited to 'doc/manual/p11-kit-remoting.xml')
| -rw-r--r-- | doc/manual/p11-kit-remoting.xml | 253 |
1 files changed, 253 insertions, 0 deletions
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> |