1<?xml version="1.0"?> 2<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ 3]> 4<chapter xml:id="remoting"> 5 <title>Remoting / Forwarding</title> 6 7 <para>Smartcards or hardware security modules (HSM) are technologies to 8 keep private keys on devices physically isolated to a device only available 9 to the user. That way only the intended user can use that device to authenticate, 10 authorize or perform other functions that involve the private keys. These come 11 usually in the form of a USB device or token which is plugged into the local computer. 12 </para> 13 <para>In modern "cloud" computing, it is often desirable to virtually transfer such 14 a device on remote servers. For example, one can sign software or documents on a remote 15 server, use the local smart card to authorize itself to Kerberos, or any other 16 possible use. There are various approaches to tackle that problem, and on different 17 levels of the smart card application stack. It is possible to forward the USB 18 device holding the smart card, or forward the lower-level PC/SC protocol which 19 some smart cards talk, or forward the high-level interface used to communicate 20 with smart cards, the PKCS#11 interface.</para> 21 22 <para>To address that problem, in p11-kit, we allow the forwarding of 23 the higher level smart card interface, PKCS#11. In the following paragraphs 24 we describe the approach and tools needed to perform that forwarding over SSH 25 secure communication channels.</para> 26 27<refsect1 id="remoting-scenario"> 28 <title>Scenario</title> 29 30 <para>We assume having a local workstation, and a remote server. On the local 31 computer we have inserted a smart card, in our examples we use a Nitrokey 32 card with the OpenSC drivers. We will forward the card 33 from the workstation to the remote server.</para> 34</refsect1> 35 36<refsect1 id="remoting-setup"> 37 <title>Setting up the PKCS#11 forwarding server on a local client</title> 38 39 <para>To forward a smartcard to a remote server, we first need to identify which 40 smartcards are available. To list the smartcards currently attached to the local 41 computer, use the p11tool command from the gnutls package. For example: 42 </para> 43 44<programlisting> 45$ p11tool --list-tokens 46... 47Token 6: 48 URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=www.CardContact.de;serial=DENK0000000;token=UserPIN%20%28Daiki%27s%20token%29 49 Label: UserPIN (Daiki's token) 50 Type: Hardware token 51 Manufacturer: www.CardContact.de 52 Model: PKCS#15 emulated 53 Serial: DENK0000000 54 Module: opensc-pkcs11.so 55... 56</programlisting> 57 58 <para>This is the entry for the card we'd like to forward to remote system. The important 59 pieces are the 'pkcs11:' URL listed above, and the module name. Once we determine which 60 smartcard to forward, we expose it to a local Unix domain socket, with the following 61 p11-kit server command. 62 </para> 63<programlisting> 64$ 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" 65</programlisting> 66 67 <para>Here we provide to the server the module location (optional) with the --provider 68 option, as well as the URL of the card. We copied the values from the Module and URL 69 lines of the p11tool output above. When the p11-kit server command starts, it will 70 print the address of the PKCS#11 unix domain socket and the process ID of the server. 71 </para> 72 73<programlisting> 74P11_KIT_SERVER_ADDRESS=unix:path=/run/user/12345/p11-kit/pkcs11-12345 75P11_KIT_SERVER_PID=12345 76</programlisting> 77 78 <para>For later use, set the variables output by the tool on your shell prompt 79 (e.g., copy and paste them or call the above p11-kit server command line with 80 <literal>eval $(p11-kit server ...)</literal>). 81 </para> 82 83</refsect1> 84 85<refsect1 id="remoting-forwarding-socket"> 86 <title>Forwarding and using the PKCS#11 Unix socket on the remote server</title> 87 88 <para>On the remote server, we will initially forward the previously generated PKCS#11 89 unix socket, and then access the smart card through it. To access the forwarded socket 90 as if it were a smart card, a dedicated PKCS#11 module p11-kit-client.so is provided as 91 part of the p11-kit-server package. 92 </para> 93</refsect1> 94 95<refsect1 id="remoting-forwarding-socket-prep"> 96 <title>Preparing the remote system for PKCS#11 socket forwarding</title> 97 98 <para>One important detail you should be aware of, is the file system location of the 99 forwarded socket. By convention, the p11-kit-client.so module utilizes the "user runtime 100 directory", managed by systemd; the directory is created when a user logs in, and removed 101 upon logout, so that the user doesn't need to manually clean up the socket file. 102 </para> 103 104 <para>To locate your user runtime directory, do: 105 </para> 106 107<programlisting> 108$ systemd-path user-runtime 109/run/user/1000 110</programlisting> 111 112 <para>The <literal>p11-kit-client.so</literal> module looks for the socket file under a 113 subdirectory (<literal>/run/user/1000/p11-kit</literal> in this example). To enable 114 auto-creation of the directory, do the following. 115 </para> 116 117<programlisting> 118$ systemctl --user enable p11-kit-client.service 119</programlisting> 120</refsect1> 121 122<refsect1 id="remoting-finally-forwarding"> 123 <title>Forwarding the PKCS#11 socket</title> 124 125 <para>We will use ssh to forward the local PKCS#11 unix socket to the remote server. 126 Following the p11-kit-client convention, we will forward the socket to the remote user 127 run-time path so that cleaning up on disconnect is not required. The remote location 128 of the run-time path can be obtained as follows. 129 </para> 130 131<programlisting> 132$ ssh [user]@[remotehost] systemd-path user-runtime 133/run/user/1000 134</programlisting> 135 136 <para>The number at the end of the path above is your user ID in that system 137 (and thus will vary from user to user). You can now forward the Unix domain socket 138 with the -R option of the ssh command, after replacing the example path with the 139 actual run-time path. 140 </para> 141 142<programlisting> 143$ ssh -R /run/user/[userID]/p11-kit/pkcs11:${P11_KIT_SERVER_ADDRESS#*=} [user]@[remotehost] 144</programlisting> 145 146 <para>After successfully logging in to the remote host, you can use the forwarded 147 smartcard as if it were directly connected to the server using the 148 <literal>p11-kit-client.so</literal>. Note that if any error occurs during the forwarding 149 setup, you will see something like this on your terminal: 150 </para> 151 152<programlisting> 153Warning: remote port forwarding failed for listen path /run/user/... 154</programlisting> 155</refsect1> 156 157<refsect1 id="remoting-using"> 158 <title>Using the forwarded PKCS#11 socket</title> 159 160 <para>Let's first make sure the smart card works on the remote system, by listing it: 161 </para> 162 163<programlisting> 164$ ls -l /run/user/1000/p11-kit/pkcs11 165 166$ p11tool --provider /usr/lib64/pkcs11/p11-kit-client.so --list-tokens 167... 168Token 0: 169 URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=www.CardContact.de;serial=DENK0000000;token=UserPIN%20%28Daiki%27s%20token%29 170 Label: UserPIN (Daiki's token) 171 Type: Hardware token 172 Manufacturer: www.CardContact.de 173 Model: PKCS#15 emulated 174 Serial: DENK0000000 175 Module: (null) 176... 177</programlisting> 178 179 <para>We can similarly generate, copy objects or test certificates to the card using 180 the same command. Any applications which support PKCS#11 can perform cryptographic 181 operations through the client module. 182 </para> 183</refsect1> 184 185<refsect1 id="remoting-registering"> 186 <title>Registering the client module for use with OpenSSL and GnuTLS apps</title> 187 188 <para>To utilize the p11-kit-client module with OpenSSL (via engine_pkcs11 provided 189 by the libp11 package) and GnuTLS applications, you have to register it in 190 p11-kit. To do it for the current user, use the following commands: 191 </para> 192 193<programlisting> 194$ mkdir .config/pkcs11/modules/ 195$ echo "module: /usr/lib64/pkcs11/p11-kit-client.so" >.config/pkcs11/modules/p11-kit-client.module 196</programlisting> 197 198 <para>Once this is done both OpenSSL and GnuTLS applications should work, for example: 199 </para> 200 201<programlisting> 202$ URL="pkcs11:model=PKCS%2315%20emulated;manufacturer=www.CardContact.de;serial=DENK0000000;token=UserPIN%20%28Daiki%27s%20token%29" 203 204# Generate a key using gnutls’ p11tool 205$ p11tool --generate-ecc --login --label test-key "$URL" 206 207# generate a certificate request with the previous key using openssl 208$ openssl req -engine pkcs11 -new -key "$URL;;object=test-key;type=private;pin-value=XXXX" \ 209 -keyform engine -out req.pem -text -subj "/CN=Test user" 210</programlisting> 211 212 <para>Note that the token URL remains the same in the forwarded system as in the original one. 213 </para> 214 215</refsect1> 216 217<refsect1 id="remoting-ssh"> 218 <title>Using the client module with OpenSSH</title> 219 220 <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: 221 </para> 222 223<programlisting> 224$ ssh -I /usr/lib64/pkcs11/p11-kit-client.so [user]@[anotherhost] 225</programlisting> 226</refsect1> 227 228<refsect1 id="remoting-nss"> 229 <title>Using the client module with NSS applications</title> 230 231 <para>To register the forwarded smartcard in NSS applications, you can set it up with 232 the modutil command, as follows. 233 </para> 234 235<programlisting> 236$ sudo modutil -dbdir /etc/pki/nssdb -add p11-kit-client -libfile /usr/lib64/pkcs11/p11-kit-client.so 237 238$ modutil -dbdir /etc/pki/nssdb -list 239... 240 3. p11-kit-client 241 library name: /usr/lib64/pkcs11/p11-kit-client.so 242 uri: pkcs11:library-manufacturer=OpenSC%20Project;library-description=OpenSC%20smartcard%20framework;library-version=0.17 243 slots: 1 slot attached 244 status: loaded 245 246 slot: Nitrokey Nitrokey HSM (010000000000000000000000) 00 00 247 token: UserPIN (Daiki's token) 248 uri: pkcs11:token=UserPIN%20(Daiki's%20token);manufacturer=www.CardContact.de;serial=DENK0000000;model=PKCS%2315%20emulated 249</programlisting> 250</refsect1> 251 252 253</chapter> 254