1gnupg-pkcs11-scd(1)       BSD General Commands Manual      gnupg-pkcs11-scd(1)
2

NAME

4     gnupg-pkcs11-scd — GnuPG-compatible smart-card daemon with PKCS#11 sup‐
5     port
6

SYNOPSIS

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

DESCRIPTION

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
17     Interface (Cryptoki).
18
19     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
27     The following options are available:
28
29     --server
30         Run in server mode (foreground). If not redirected, input and output
31         are over stdin/stdout.
32
33     --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
38     --daemon
39         Detach and run in background.
40
41     --homedir dir
42         Use this home directory instead of guessing.
43
44     --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
48     --verbose
49         Be verbose while running.
50
51     --quiet
52         Be as quiet as possible.
53
54     --sh
55         Output sh-style environment variable definition.
56
57     --csh
58         Output csh-style environment variable definition.
59
60     --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
64     --no-detach
65         Do not detach from console (useful for debugging purposes).
66
67     --log-file file
68         Output log to file.
69
70     --help
71         Print help information.
72
73     When the daemon receives any of the SIGHUP, SIGTERM and SIGINT signals,
74     it cleans up and exits.
75
76     gnupg-pkcs11-scd works only with already personalized cards, and supports
77     (for the time being) only RSA keypairs.  The following constraints must
78     be satisfied:
79
80     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
86     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

NOTES

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
93     always returns the same card serial number to gpg-agent.  When unavail‐
94     able token is requested, gnupg-pkcs11-scd will use NEEDPIN callback in
95     order to ask for the requested token.  When and if gpg-agent will support
96     more than one serial number or NEEDTOKEN callback, this behavior will be
97     modified.
98

ENVIRONMENT

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
106     Additionally, the \\Software\\GNU\\GnuPG\\HomeDir registry key is used on
107     Win32 to locate the default GNUPGHOME.
108

FILES

110     Files affecting the operation of gnupg-pkcs11-scd:
111
112     ~/.gnupg/gnupg-pkcs11-scd.conf    gnupg-pkcs11-scd uses this as a default
113                                       configuration file.
114
115     /etc/gnupg-pkcs11-scd.conf        gnupg-pkcs11-scd uses this as a default
116                                       system wide configuration file.
117
118     ~/.gnupg/gpg-agent.conf           Default configuration file for gpg-
119                                       agent.
120

CONFIGURATION

122     To tell gpg-agent to use another smart-card daemon, the following needs
123     to be put in ~/.gnupg/gpg-agent.conf:
124
125           scdaemon-program /usr/bin/gnupg-pkcs11-scd
126           pinentry-program /usr/bin/pinentry-qt
127
128     The first line is mandatory in order to use gnupg-pkcs11-scd.  With the
129     second line you can set your preferred pinentry program (it has to be one
130     compatible with GnuPG). Of course, you need to adjust the paths according
131     to your system setup.
132
133     An example ~/.gnupg/gnupg-pkcs11-scd.conf file (lines beginning with #
134     are comments):
135
136           # Log file.
137           #log-file log1
138
139           # Default is not verbose.
140           #verbose
141
142           # Default is no debugging.
143           #debug-all
144
145           # Pin cache period in seconds; default is infinite.
146           #pin-cache 20
147
148           # Comma-separated list of available provider names. Then set
149           # attributes for each provider using the provider-[name]-attribute
150           # syntax.
151           providers p1
152
153           # Provider attributes (see below for detailed description)
154           provider-p1-library /usr/lib/pkcs11/p1.so
155           #provider-p1-allow-protected-auth
156           #provider-p1-cert-private
157           #provider-p1-private-mask 0
158
159           # The following are for gnupg-2.0 mode
160           #openpgp-sign 5C661B8C07CFD957F7D98D5B9A0F31D236BFAC2A
161           #openpgp-encr D2DC0BD1EDD185969748B6025B452816F97CBA57
162           #openpgp-auth A7B8C1A3A8F71FCEC018886F8767927B9C8D871F
163
164     The following attributes can be set for each provider:
165
166     library
167         Full path to the PKCS#11 shared library (= provider).
168
169     allow-protected-auth
170         Allow protected authentication for provider. This needs to be sup‐
171         ported by the provider and you should have appropriate reader hard‐
172         ware.
173
174     cert-private
175         Authentication is required before certificates can be accessed. Most
176         configurations store certificates as public, so there is no need to
177         use this option.
178
179     private-mask
180         Private key mask mode. Use this only when you have problem using pri‐
181         vate key operations. The value is hex encoded mask number.
182         0        Determine automatically.
183         1        Force sign.
184         2        Force sign with recovery.
185         4        Force decrypt.
186         8        Force decrypt with unwrap.
187
188     openpgp-sign
189         [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of signing pub‐
190         lic key see GNUPG INTEGRATION how to obtain.
191
192     openpgp-encr
193         [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of encryption
194         public key see GNUPG INTEGRATION how to obtain.
195
196     openpgp-auth
197         [gnupg-2.0] Hex string (Upper letter, no space) SHA1 of authentica‐
198         tion public key see GNUPG INTEGRATION how to obtain.
199

GNUPG INTEGRATION

201     Typical steps to set up a card for gpgsm usage:
202
203     1.   Import the CA certificate of your issuer:
204                gpgsm --import < ca-certificate
205          You should also manually import all self-signed certificates.
206
207     2.   Instruct GnuPG to discover all useful certificates on the card:
208                gpgsm --learn-card
209
210     Signing, verification, etc. work as usual with gpgsm.
211
212     Typical steps to set up a card for gpg-2.0 usage:
213
214     1.   Aquire key ids:
215                gpg-agent --server gpg-connect-agent
216          Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first
217          field is the hash, the second is the subject name.
218
219     2.   Instruct GnuPG to discover all useful information of card:
220                gpg --card-status
221          You should see valid card status.
222
223     3.   Now, you should virtual generate keys, the keys are not actually
224          generated, but returned to gpg to be registered.
225                gpg --card-edit
226                admin
227                generate (DO NOT BACKUP KEYS)
228          Kill gpg-agent and modify configuration to have sign, encrypt,
229          authenticate key hex ids.
230
231     4.   Alternatively, you can add the existing keys as subkeys on an exist‐
232          ing GPG master key:
233                gpg --edit-key MASTER_KEY_ID
234                addcardkey
235
236     5.   In order to reattach a key to smartcard, remove secret key using:
237                gpg --delete-secret-keys KEY_ID
238          Then regenerate but without replace keys using:
239                gpg --card-edit
240                admin
241                generate (DO NOT GENERATE KEYS)
242
243     Signing, verification, etc. work as usual with gpg.
244
245     Typical steps to set up a card for >=gpg-2.1.19 usage:
246
247     1.   Refresh local key store:
248                gpg --card-status
249
250     2.   Aquire key ids:
251                gpg-agent --server gpg-connect-agent
252          Enter "SCD LEARN" and look for "KEY-FRIEDNLY" responses, the first
253          field is the keygrip, the second is the subject name.
254
255     3.   Create master key based on existing key using:
256                gpg --expert --full-generate-key
257          Select:
258                (13) Existing key
259          Enter keygrip to be used as primary key.
260
261     4.   Continue as usual to setup your primary key, you should probably use
262          signature for master key.
263
264     5.   Add subkey using:
265                gpg --expert --edit-key ${MASTER_KEY_ID}
266                gpg> addkey
267                (13) Existing key
268          Enter keygrip to be used as subkey.
269
270     6.   Continue as usual to setup your subkey.
271
272     Signing, verification, etc. work as usual with gpg.
273

SECURITY CONSIDERATIONS

275     All communication between components is currently unprotected and in
276     plain text (that's how the Assuan protocol operates). It is trivial to
277     trace (using e.g. the strace(1) program) individual components (e.g.
278     pinentry) and steal sensitive data (such as the smart-card PIN) or even
279     change it (e.g. the hash to be signed).
280
281     When using the software in production scenario, be sure to turn off
282     debugging/verbose options in configuration of all components. Otherwise,
283     some sensitive data might be displayed on the screen (most notably, the
284     PIN).
285

SEE ALSO

287     strace(1) truss(1) gnupg(7)
288
289     GnuPG Home Page, http://www.gnupg.org.
290
291     gnupg-pkcs11 Home Page, http://gnupg-pkcs11.sourceforge.net.
292
294     Copyright (c) 2006-2007 Zeljko Vrba <zvrba@globalnet.hr>
295
296     Copyright (c) 2006-2017 Alon Bar-Lev <alon.barlev@gmail.com>
297
298     All rights reserved.
299
300     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
301     OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL‐
302     ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
303     SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
304     OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
305     ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
306     OTHER DEALINGS IN THE SOFTWARE.
307
308POSIX-compatible               October 15, 2017               POSIX-compatible
Impressum