From 50b752e081e1ca8b674d05e8ddeaf04451065629 Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Fri, 22 Dec 2017 15:18:42 +0100 Subject: Added p11-kit remoting page in manual --- doc/manual/Makefile.am | 1 + doc/manual/p11-kit-docs.xml | 1 + doc/manual/p11-kit-remoting.xml | 253 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 255 insertions(+) create mode 100644 doc/manual/p11-kit-remoting.xml 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 @@ + 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 @@ + + + + Remoting / Forwarding + + 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. + + 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. + + 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. + + + Scenario + + 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. + + + + Setting up the PKCS#11 forwarding server on a local client + + 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: + + + +$ 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 +... + + + 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. + + +$ 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" + + + 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. + + + +P11_KIT_SERVER_ADDRESS=unix:path=/run/user/12345/p11-kit/pkcs11-12345 +P11_KIT_SERVER_PID=12345 + + + 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 + eval $(p11-kit server ...)). + + + + + + Forwarding and using the PKCS#11 Unix socket on the remote server + + 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. + + + + + Preparing the remote system for PKCS#11 socket forwarding + + 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. + + + To locate your user runtime directory, do: + + + +$ systemd-path user-runtime +/run/user/1000 + + + The p11-kit-client.so module looks for the socket file under a + subdirectory (/run/user/1000/p11-kit in this example). To enable + auto-creation of the directory, do the following. + + + +$ systemctl --user enable p11-kit-client.service + + + + + Forwarding the PKCS#11 socket + + 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. + + + +$ ssh [user]@[remotehost] systemd-path user-runtime +/run/user/1000 + + + 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. + + + +$ ssh -R /run/user/[userID]/p11-kit/pkcs11:${P11_KIT_SERVER_ADDRESS#*=} [user]@[remotehost] + + + 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 + p11-kit-client.so. Note that if any error occurs during the forwarding + setup, you will see something like this on your terminal: + + + +Warning: remote port forwarding failed for listen path /run/user/... + + + + + Using the forwarded PKCS#11 socket + + Let's first make sure the smart card works on the remote system, by listing it: + + + +$ 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) +... + + + 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. + + + + + Registering the client module for use with OpenSSL and GnuTLS apps + + 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: + + + +$ mkdir .config/pkcs11/modules/ +$ echo "module: /usr/lib64/pkcs11/p11-kit-client.so" >.config/pkcs11/modules/p11-kit-client.module + + + Once this is done both OpenSSL and GnuTLS applications should work, for example: + + + +$ 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" + + + Note that the token URL remains the same in the forwarded system as in the original one. + + + + + + Using the client module with OpenSSH + + 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: + + + +$ ssh -I /usr/lib64/pkcs11/p11-kit-client.so [user]@[anotherhost] + + + + + Using the client module with NSS applications + + To register the forwarded smartcard in NSS applications, you can set it up with + the modutil command, as follows. + + + +$ 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 + + + + + -- cgit v1.1