Skip to content

Commit

Permalink
Added p11-kit remoting page in manual
Browse files Browse the repository at this point in the history
  • Loading branch information
@ueno
Nikos Mavrogiannopoulos authored and ueno committed Jan 5, 2018
1 parent 2c84475 commit 50b752e
Show file tree
Hide file tree
Showing 3 changed files with 255 additions and 0 deletions.
1 change: 1 addition & 0 deletions doc/manual/Makefile.am
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down
1 change: 1 addition & 0 deletions doc/manual/p11-kit-docs.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down
253 changes: 253 additions & 0 deletions doc/manual/p11-kit-remoting.xml
View file
Original file line number Diff line number Diff line change
@@ -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>

0 comments on commit 50b752e

Please sign in to comment.