1gnupg-pkcs11-scd(1) BSD General Commands Manual gnupg-pkcs11-scd(1)
2
4 gnupg-pkcs11-scd — GnuPG-compatible smart-card daemon with PKCS#11 sup‐
5 port
6
8 gnupg-pkcs11-scd [--server] [--multi-server] [--daemon] [--homedir dir]
9 [--uid-acl uid] [--verbose] [--quiet] [--sh] [--csh]
10 [--options file] [--no-detach] [--log-file file]
11 [--help]
12
14 gnupg-pkcs11-scd is a drop-in replacement for the smart-card daemon (scd)
15 shipped with the next-generation GnuPG (gnupg-2). The daemon interfaces
16 to smart-cards by using RSA Security Inc. PKCS#11 Cryptographic Token In‐
17 terface (Cryptoki).
18 The interface with GnuPG is restricted to feching existing keys from the
20 card. Neither new key generation nor key transfer is possible through
21 this interface. Instead, when the smart-card is asked to generate a key
22 in a particular slot, the existing public key in that slot is returned.
23 This facilitates the transfer of keys on the smart-card to usage as a
24 subkey on an existing GnuPG master key. See the GNUPG INTEGRATION sec‐
25 tion for example usage.
26 The following options are available:
28 --server
30 Run in server mode (foreground). If not redirected, input and output
31 are over stdin/stdout.
32 --multi-server
34 Run in multi-server mode (foreground). In addition to communicating
35 over stdin/stdout, the server also opens an additional listening UNIX
36 socket.
37 --daemon
39 Detach and run in background.
40 --homedir dir
42 Use this home directory instead of guessing.
43 --uid-acl uid
45 Create unix socket as world read/write and apply access control that
46 accepts only remote processes of this uid. Usable for proxy scenario.
47 --verbose
49 Be verbose while running.
50 --quiet
52 Be as quiet as possible.
53 --sh
55 Output sh-style environment variable definition.
56 --csh
58 Output csh-style environment variable definition.
59 --options file
61 Read options from file. Some of the configuration options can only
62 be set in the configuration file (see the CONFIGURATION section).
63 --no-detach
65 Do not detach from console (useful for debugging purposes).
66 --log-file file
68 Output log to file.
69 --help
71 Print help information.
72 When the daemon receives any of the SIGHUP, SIGTERM and SIGINT signals,
74 it cleans up and exits.
75 gnupg-pkcs11-scd works only with already personalized cards, and supports
77 (for the time being) only RSA key pairs. The following constraints must
78 be satisfied:
79 1. For each private key object, a certificate object must exist on the
81 card. The existence of the corresponding public key object is not
82 important (since the certificate includes public key).
83 2. The certificate and the corresponding private key must have identi‐
84 cal CKA_ID attribute.
85 The PKCS#11 implementation is not obliged to enforce any of the above
87 rules. However, practice has shown that popular PKCS#11 implementations
88 found "in the wild" seem to respect them.
89
91 Unlike gpg-agent, gnupg-pkcs11-scd supports more than one token available
92 at the same time. In order to make gpg-agent happy, gnupg-pkcs11-scd al‐
93 ways returns the same card serial number to gpg-agent. When unavailable
94 token is requested, gnupg-pkcs11-scd will use NEEDPIN callback in order
95 to ask for the requested token. When and if gpg-agent will support more
96 than one serial number or NEEDTOKEN callback, this behavior will be modi‐
97 fied.
98
100 HOME Used to locate the home directory.
101 GNUPGHOME Used instead of ~/.gnupg.
102 USERPROFILE Used only on Win32 to locate the home directory.
103 GNUPG_PKCS11_SOCKETDIR
104 Create sockets in this directory, default to TMPDIR.
105 Additionally, the \\Software\\GNU\\GnuPG\\HomeDir registry key is used on
107 Win32 to locate the default GNUPGHOME.
108
110 Files affecting the operation of gnupg-pkcs11-scd:
111 ~/.gnupg/gnupg-pkcs11-scd.conf
113 gnupg-pkcs11-scd uses this as a default configuration file.
114 /etc/gnupg-pkcs11-scd.conf
116 gnupg-pkcs11-scd uses this as a default system wide configuration
117 file.
118 ~/.gnupg/gpg-agent.conf
120 Default configuration file for gpg-agent.
121
123 To tell gpg-agent to use another smart-card daemon, the following needs
124 to be put in ~/.gnupg/gpg-agent.conf:
125 scdaemon-program /usr/bin/gnupg-pkcs11-scd
127 pinentry-program /usr/bin/pinentry-qt
128 The first line is mandatory in order to use gnupg-pkcs11-scd. With the
130 second line you can set your preferred pinentry program (it has to be one
131 compatible with GnuPG). Of course, you need to adjust the paths according
132 to your system setup.
133 An example ~/.gnupg/gnupg-pkcs11-scd.conf file (lines beginning with #
135 are comments):
136 # Log file.
138 #log-file log1
139 # Default is not verbose.
141 #verbose
142 # Default is no debugging.
144 #debug-all
145 # Pin cache period in seconds; default is infinite.
147 #pin-cache 20
148 # Use the gnupg PIN cache (>=gnupg-2.3.0)
150 #use-gnupg-pin-cache
151 # Comma-separated list of available provider names. Then set
153 # attributes for each provider using the provider-[name]-attribute
154 # syntax.
155 providers p1
156 # Provider attributes (see below for detailed description)
158 provider-p1-library /usr/lib/pkcs11/p1.so
159 #provider-p1-allow-protected-auth
160 #provider-p1-cert-private
161 #provider-p1-private-mask 0
162 # The following are for >=gnupg-2.0 and <gnupg-2.1.19
164 #openpgp-sign 5C661B8C07CFD957F7D98D5B9A0F31D236BFAC2A
165 #openpgp-encr D2DC0BD1EDD185969748B6025B452816F97CBA57
166 #openpgp-auth A7B8C1A3A8F71FCEC018886F8767927B9C8D871F
167 The following attributes can be set for each provider:
169 library
171 Full path to the PKCS#11 shared library (= provider).
172 allow-protected-auth
174 Allow protected authentication for provider. This needs to be sup‐
175 ported by the provider and you should have appropriate reader hard‐
176 ware.
177 cert-private
179 Authentication is required before certificates can be accessed. Most
180 configurations store certificates as public, so there is no need to
181 use this option.
182 private-mask
184 Private key mask mode. Use this only when you have problem using pri‐
185 vate key operations. The value is hex encoded mask number.
186 0 Determine automatically.
187 1 Force sign.
188 2 Force sign with recovery.
189 4 Force decrypt.
190 8 Force decrypt with unwrap.
191 openpgp-sign
193 [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of signing pub‐
194 lic key see GNUPG INTEGRATION how to obtain.
195 openpgp-encr
197 [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of encryption
198 public key see GNUPG INTEGRATION how to obtain.
199 openpgp-auth
201 [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of authentica‐
202 tion public key see GNUPG INTEGRATION how to obtain.
203
205 Typical steps to set up a card for gpgsm usage:
206 1. Import the CA certificate of your issuer:
208 gpgsm --import < ca-certificate
209 You should also manually import all self-signed certificates.
210 2. Instruct GnuPG to discover all useful certificates on the card:
212 gpgsm --learn-card
213 Signing, verification, etc. work as usual with gpgsm.
215 Typical steps to set up a card for >=gpg-2.0 and <gpg-2.1.19 usage:
217 1. Acquire key ids:
219 gpg-agent --server gpg-connect-agent
220 Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first
221 field is the hash, the second is the subject name.
222 2. Instruct GnuPG to discover all useful information of card:
224 gpg --card-status
225 You should see valid card status.
226 3. Now, you should virtual generate keys, the keys are not actually
228 generated, but returned to gpg to be registered.
229 gpg --card-edit
230 admin
231 generate (DO NOT BACKUP KEYS)
232 Kill gpg-agent and modify configuration to have sign, encrypt, au‐
233 thenticate key hex ids.
234 4. Alternatively, you can add the existing keys as subkeys on an exist‐
236 ing GPG master key:
237 gpg --edit-key MASTER_KEY_ID
238 addcardkey
239 5. In order to reattach a key to smartcard, remove secret key using:
241 gpg --delete-secret-keys KEY_ID
242 Then regenerate but without replace keys using:
243 gpg --card-edit
244 admin
245 generate (DO NOT GENERATE KEYS)
246 Signing, verification, etc. work as usual with gpg.
248 Typical steps to set up a card for >=gpg-2.1.19 and <gpg-2.3 usage:
250 1. Refresh local key store:
252 gpg --card-status
253 2. Acquire key ids:
255 gpg-agent --server gpg-connect-agent
256 Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first
257 field is the keygrip, the second is the subject name.
258 3. Create master key based on existing key using:
260 gpg --expert --full-generate-key
261 Select:
262 (13) Existing key
263 Enter keygrip to be used as primary key.
264 4. Continue as usual to setup your primary key, you should probably use
266 signature for master key.
267 5. Add subkey using:
269 gpg --expert --edit-key ${MASTER_KEY_ID}
270 Enter:
271 gpg> addkey
272 Select:
273 (13) Existing key
274 Enter keygrip to be used as subkey.
275 6. Continue as usual to setup your subkey.
277 Signing, verification, etc. work as usual with gpg.
279 Typical steps to set up a card for >=gpg-2.3 usage:
281 1. Create master key based on existing key using:
283 gpg --expert --full-generate-key
284 Select:
285 (14) Existing key from card
286 Select the key from the list.
287 2. Continue as usual to setup your primary key, you should probably use
289 signature for master key.
290 3. Add subkey using:
292 gpg --expert --edit-key ${MASTER_KEY_ID}
293 Enter:
294 gpg> addkey
295 Select:
296 (14) Existing key from card
297 Select the key from the list.
298 4. Continue as usual to setup your subkey.
300 Signing, verification, etc. work as usual with gpg.
302
304 All communication between components is currently unprotected and in
305 plain text (that's how the Assuan protocol operates). It is trivial to
306 trace (using e.g. the strace(1) program) individual components (e.g.
307 pinentry) and steal sensitive data (such as the smart-card PIN) or even
308 change it (e.g. the hash to be signed).
309 When using the software in production scenario, be sure to turn off
311 debugging/verbose options in configuration of all components. Otherwise,
312 some sensitive data might be displayed on the screen (most notably, the
313 PIN).
314
316 strace(1) truss(1) gnupg(7)
317 GnuPG Home Page, http://www.gnupg.org.
319 gnupg-pkcs11 Home Page, http://gnupg-pkcs11.sourceforge.net.
321
323 Copyright (c) 2006-2007 Zeljko Vrba <zvrba@globalnet.hr>
324 Copyright (c) 2006-2017 Alon Bar-Lev <alon.barlev@gmail.com>
326 All rights reserved.
328 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
330 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL‐
331 ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
332 SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
333 OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
334 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
335 OTHER DEALINGS IN THE SOFTWARE.
336POSIX-compatible October 15, 2017 POSIX-compatible